XmlDataCursor (webMethods Java API Reference)

All Known Subinterfaces:: XmlDataTreeCursor

All Known Implementing Classes:: XmlDataCursorImpl, XmlDataTreeCursorImpl

public interface XmlDataCursor

Defines the basic programming interface for navigating and manipulatng the XMLData infoset. This includes support for attributes, substitution groups, any wildcards, repeating and nested model groups, and namespace-qualified tags.

Introduction

XmlDataCursor defines the basic programming interface for navigating and manipulating the XmlData infoset. The XmlData infoset is a convention for encoding an XML infoset using IData. The XmlData infoset is similar to the legacy XML IData encoding of past implementations, but is more comprehensive. Like the legacy encoding, the XmlData encoding consists of tag-object-pairs. The tags correspond roughly to fully qualified XML infoset element and attribute tags; the values correspond roughly to the content associated with those tags. The IData containing the tag-object pairs corresponding to element content is typically called a group-value and it is the basic unit of encoding for XmlData. In addition to group-values, there are also attributes-sets that contain tag-value-pairs corresponding to attributes and their values. For a complete description see XmlData.

There is only one implementation of this interface. The XmlData concrete class is used to obtain an XmlDataCursor on an IData object containing an XmlData infoset. This is accomplished using XmlData.getXmlDataCursor(IData).

Within a Java application, all manipulation of the XmlData infoset should be accomplished using either this class, the XmlDataTreeCursor class, the static methods of the XmlData class, or one the helper classes such as XmlDataMap or XmlDataCopy. Direct manipulation of the XmlData infoset using raw IDataCursors is strongly discouraged, as it may make applications vulnerable to future changes in the XmlData infoset necessitated by enhancements or bug fixes.

Retrieving and updating the content of XmlData infoset is very similar to that of the legacy approach using navigation methods such as first() and next() and using accessor methods such as getValue() and setValue(). Just as with the IDataCursor, the XmlDataCursor must be positioned on the tag corresponding to the element whose value is to be retrieved or modified. However, navigation using XnlDataCursor is much more structured and constrained than using the legacy IDataCursor.

Attributes are also accessed through the XmlDataCursor. However, unlike the legacy IData structure, XmlData stores attributes separately from the child element content. The attributes are not accessible as "peers" of the child elements and are not accessed using cursor navigation of the children. Instead, there are explicit methods such as getAttributeValue(XmlDataAttributeTag, int...) that access the attribute by name (rather than cursor position). This is consistent with the definition of the XML infoset which asserts that attributes are unique and not ordered for any given element.

There are two varieties of the XmlData infoset. The conforming-XmlData-infoset variation has a format that conforms to a collection of XmlData document types that were created from an XML schema. These conforming XmlData infosets have special constructs (and corresponding special tags) that represent repeating model groups, any wildcards, and substitution groups. The nonconforming-XmlData-infosets have only element tags and attribute tags.

See glossary of terms

Tag creation

The tags used by XmlData are Strings, but their format is rather complex. The application is not expected to construct these tags directly. There are constructors for this purpose such as XmlDataElementTag. The cursor methods accept the parsed-tag format created by those constructors. In addition, there are static methods in XmlDataConstants that serve as short-cuts for these methods and can be conveniently "added" to any code simply by importing all static members of that class. These short-cuts are meant to reduce the syntactic overhead of using formal tag constructors. The association between tag-type, appropriate constructor, and short-cut is:

XmlData tag type	Role	Constructor	`XmlDataConstants` short cut
element-tag	Corresponds to: an element tag in the XML infoset when using a nonconforming-XmlData-infoset an element particle in a schema group model when using a conforming-XmlData-infoset	`XmlDataElementTag`	`eTag()`
group-tag	Corresponds to a group model in a schema when using a conforming-XmlData-infoset	`XmlDataGroupTag`	`gTag()`
any-tag	Corresponds to an any wildcard particle in a schema when using a conforming-XmlData-infoset	`XmlDataAnyTag`	`anyTag()`
substitution-tag	Corresponds to an element particle that is also the head of a substitution group in a schema group model when using a conforming-XmlData-infoset	`XmlDataSubstitutionTag`	`sTag()`
attribute-tag	Corresponds to: an attribute tag in the XML infoset when using a nonconforming-XmlData-infoset an attribute declaration in a schema complexType when using a conforming-XmlData-infoset	`XmlDataAttributeTag`	`aTag()`

Three modes of access: value, item, and object.

There are three different ways of accessing the content using the XmlDataCursor: "value", "item", or "object".

The "object" methods are used to access the complete Java object associated with a tag. When repeating values are not present, the object is simply an individual item (value or indirect-item). When repeating values are present, the object is an array of items (an array of values or an array of indirect-items). Thus, methods like getObject() and setObject() allow the entire collection of items to be accessed in a single operation. The items are either direct representations of a value (simple-value, group-value, or complex-value) or an indirect-value (any-items or substitution-items). The tags and object must be compatible. An element-tag must be paired with a value (simple-value, group-value, or complex-value). A group-tag must be paired with a group-value or an array of group-values. An any-tag is always paired with an any-value or an array of anny-values, a substitution-tag is always paired with a substitution-item or an array of substitution-items.

The "item" methods are similar to the "object" methods but include an index qualifier. The "item" methods therefore are used to access a single item if the object contains repeating values. When repeating values are not present, the "item" methods (without an index qualifier) and the "object" methods are equivalent. Simple-values, group-values, and complex-values are directly paired with their tag, while indirect-items (any-items and substitution-items) have their value-tag embedded in the indirect-item.

The "value" methods (e.g., getValue() and setValue()) are the most natural way of accessing the XmlData infoset and are most typically used. An application positions to a particular tag using a method such as first() or next(), and then uses getValue() to obtain the effective value stored at the tag or setValue() to set the value stored at the tag. When positioned on element-tags or group-tags, the "value" methods directly access the values stored at the tag (and operate exactly like the "item" methods). When positioned on any-tags or substitution-tags, the "value" methods transparently access the values stored in indirect-items (substitution-items and any-items) so that the application does not concern itself with the format of values stored as indirect-items.

Even when using the "value" methods, there is still complexity because the value may be a simple-value, a group-value, or complex-value with or without attributes. The content methods, getContent(int...) and setContent(Object, int...) give direct access to the simple or complex content regardless of the presence or absence of attributes. In similar fashion, the getAttributes(), setAttributes(), and setAttributeValue() methods allow direct access to the attribute regardless of the absence or presence of content, or whether the value is an indirect-item.

The getTag() method returns the tag associated with the current cursor position. However, when using element wildcard (any) or substitution groups, the current tag is a specialized tag (e.g. an any-tag or an substitution-tag, not the actual XML element name as present in the instance data. In order to access the actual tag, the getValueTag(int...) and setValueTag(XmlDataContentTag, int...) methods are used. These methods extract the tag from the specialized any-item or substitution-item structure. For normal element tags, getValueTag() and setValueTag() behave exactly like getTag() and setTag().

Namespace declarations and instance properties

Namespace declarations (the xmlns prefix) and instance properties (conventionally the xsi prefix) are not specified using the attribute methods. This is because they are not stored in the XmlData infoset as attributes. They have their own accessor methods such as getNamespaceDecl(String, int...), setNamespaceDecl(String, String, int...), getInstanceProp(String, int...), and setInstanceProp(String, String, int...).

XmlDataCursor method summary:

Methods	Operation
`getObject()`, `setObject()`, `deleteObject()`, `insertObjectBefore()`, `insertObjectAFter()` `getTag()`, `setTag()`	Get or set the entire object at the current position which might be a single item or an array of repeating items
`getItem()`, `setItem()`, `deleteItem()`, `insertItemAfter()`, `insertItemBefore()`	Get or set an individual item. For non-repeating values, theses methods operate like getObject() and setObject() and return the item at the current cursor position. When repeating values are present, an index is required to select one item from the object array. The item may be a simple-value, group-value, complex-value, or indirect-item.
`getValue()`, `setValue()` `getValueTag()`, `setValueTag()`, `insertValueAfter()`, `insertValueBefore()`, `getValueTag()`, `setValueTag()` `getComplexValueContent()`, `setComplexValueContent()`, `getContent()`, `setContent()`, `isEmpty()`, `isSimpleValue()`, `isGroupValue()`, `isComplexValue()`	Get or set an individual value. If repeating values are present, an index must be specified. When the current-tag is an element-tags or group-tag, these methods behave exactly like getItem() and setItem(). For indirect-tags (substitution-tags and any-tags), the value of the indirect-item is accessed. For an any-item, this is the value stored at the *value field in the any-item. For substitution-items it is the value of the first and only child of the substitution-item. There is no deleteValue() method because deleteItem() has the same effect. For non indirect-items, insertItemBefore() and insertValueBefore() operate identically, as do insertValueAfter() and insertItemAfter().
`getAttributes()`, `setAttributes()`, `getAttributeValue()`, `setAttributeValue()`, `hasAttributes()`, `getAttributeNames()`, `removeAttribute()`	Get or set attributes values. If the cursor is positioned on an object with repeating values, an index is required.
`first()`, `next()`, `previous()`, `firstPartial()`, `nextPartial()`, `previousPartial()`, `lastPartial()`	Reposition the cursor.
`getNamespaceDecl` , `setNamespaceDecl()` , `getNamespaceDecls()` , `setNamespaceDecls()` , `getUnstanceProp()`, `setInstanceProp()`	Get or set namespace declarations and xsi instance properties.
`count()`, `isRepeating()` , `isAny()`, `isSubstitution()` , `isGroup()`, `recast()`, `isRecast()`, `data()`, `copyCursor()`, `destroy()`, `valueCursor()`	Utility.

Glossary of terms:

current-object - the entire Object stored at the current-position. When repeating values are associated with a tag, the Object is an array, otherwise it is a scalar.
current-position - the tag-object-pair where this cursor is positioned. It is possible for a cursor to be unpositioned, such as when a cursor is initially obtained. For methods that require a positioned cursor, the XmlDataException.UnpositionedCursor exception is thrown if the cursor is not positioned.
current-tag - the tag part of the tag-object-pair at the current-position. When an XmlData infoset is conforming to a document type, the current-tag may either an element-tag, a group-tag, an any-tag, or a substitution-tag. When the XmlData infoset is not conforming, the current-tag is always an element-tag.

See Also:: XmlData

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`XmlDataCursor`	`copyCursor()`
`int`	`count()` Returns the number of items stored at the current cursor position.
`IData`	`data()` Returns the IData for which this cursor is defined.
`boolean`	`deleteItem(int... index)` Removes a single item from the array of items stored at the current cursor position.
`boolean`	`deleteObject()` Removes the tag-object-pair (single value or array of repeating values) from the current position.
`void`	`destroy()` Release any resources associated with the current cursor.
`boolean`	`first()` Positions the cursor at the first tag-object-pair.
`boolean`	`first(XmlDataContentTag tag)` Positions the cursor on the first tag-object-pair with the specified tag and returns true.
`boolean`	`firstPartial(XmlDataContentTag tag)` Positions the cursor on the first tag-object-pair with a tag that partially matches the specified tag.
`XmlDataContentTag`	`getAnyTag(int... index)` Returns a parsed-tag constructed from the ncName and namespace fields in the any-item.
`XmlDataAttributeTag[]`	`getAttributeNames(int... index)` Returns a list of attribute-tags for a complex-value stored at the current cursor position.
`IData`	`getAttributes(int... index)` Returns an IData list of attributes and values for the complex-value stored at the current cursor position.
`java.lang.String`	`getAttributeValue(XmlDataAttributeTag attribute, int... index)` Returns the value of an attribute for the complex-value at the current cursor position.
`java.lang.Object`	`getComplexValueContent(int... index)` Returns the value paired with the *simple field or the solitary top-level group-tag.
`java.lang.Object`	`getContent(int... index)` Returns the content of the current value.
`java.lang.String`	`getInstanceProp(java.lang.String name, int... optionalIndex)` Retrieves the value of an instance (xsi) attribute specified for the current value.
`java.lang.Object`	`getItem(int... index)` Returns an item from the current-object.
`java.lang.String`	`getNamespaceDecl(java.lang.String prefix, int... optionalIndex)` Returns the the namespace URI associated with the specified prefix.
`IData`	`getNamespaceDecls(int... optionalIndex)` Gets all of the namespace-prefix associations for the current value.
`java.lang.Object`	`getObject()` Returns the current-object, the object stored at the current-position.
`XmlDataContentTag`	`getTag()` Returns the current-tag as a parsed-tag.
`java.lang.Object`	`getValue(int... index)` Returns a value from the current-object.
`XmlDataCursor`	`getValueCursor(int... optionalIndex)` Returns an XmlDataCursor positioned on the first child of the specified value in the current-object.
`XmlDataContentTag`	`getValueTag(int... index)` Returns the value-tag associated with the value at the current-position.
`boolean`	`hasAttributes(int... index)` Determines if the value at the specified index has attributes.
`void`	`home()` The cursor becomes unpositioned as if newly created.
`void`	`insertItemAfter(java.lang.Object item, int index)` Inserts an item after the specified index into the array of repeating values at the current-position.
`void`	`insertItemBefore(java.lang.Object item, int index)` Inserts an item before the specified index into the array of repeating values at the current-position.
`void`	`insertObjectAfter(XmlDataContentTag tag, java.lang.Object object)` Inserts a tag-object-pair after the current-position.
`void`	`insertObjectBefore(XmlDataContentTag tag, java.lang.Object object)` Inserts a tag-object-pair before the current-position.
`void`	`insertValueAfter(XmlDataContentTag tag, java.lang.Object value, int index)` Inserts a value into an array of repeating values at the current-position, after the specified index.
`void`	`insertValueBefore(XmlDataContentTag tag, java.lang.Object value, int index)` Inserts a value into an array of repeating values at the current-position, before the specified index.
`boolean`	`isAny()` Determines if the current-tag is an any-tag.
`boolean`	`isComplexValue(int... index)` Determines if the value at the current-position is an IData with a single group tag, an attribute tga, or a simple tag.
`boolean`	`isEmpty(int... index)` Determines if the value at the current-position is empty (or non-existent complex content for complex-values).
`boolean`	`isGroup()` Determines if the current-tag is a group-tag.
`boolean`	`isGroupValue(int... index)` Determines if the value at the current-position is a group-value.
`boolean`	`isHome()` Indicates whether the cursor is unpositioned.
`boolean`	`isRecast()` Indicates if automatic recast is in effect.
`boolean`	`isRepeating()` Determines if the current-object is a repeating value.
`boolean`	`isSimpleValue(int... index)` Determines if the value at the current-position is a simple value.
`boolean`	`isSubstitution()` Determines if the current-tag is a substitution-tag
`boolean`	`last()` Positions the cursor at the last tag-object-pair.
`boolean`	`last(XmlDataContentTag tag)` Positions the cursor on the last occurrence of the last tag-object-pairg with the specified tag and return true.
`boolean`	`lastPartial(XmlDataContentTag tag)` Positiosn the cursor on the last tag-object-pair with a tag that partially matches the specified tag.
`XmlDataCursor`	`newCursor(IData data)` Creates a new XmlDataCuror instances from an existing cursor factory.
`boolean`	`next()` Positions the cursor on the next tag-object-pair.
`boolean`	`next(XmlDataContentTag tag)` Positiona the cursor on the next tag-object-pair that has the specified tag and returns true.
`boolean`	`nextPartial(XmlDataContentTag tag)` Positions the cursor on the next tag-object-pair with a tag that partially matches the specified tag.
`boolean`	`previous()` Positions the cursor on the previous tag-object-pair.
`boolean`	`previous(XmlDataContentTag tag)` Positions the cursor on the previous tag-object-pair with the specified tag and return true.
`boolean`	`previousPartial(XmlDataContentTag tag)` Positions the cursor on the previous tag-object-pair with a tag that partially matches the specified tag.
`void`	`recast(boolean mode)` Indicates whether existing String[] or IData[] arrays for repeating values should be automatically recreated as an Object[] when the inserted or set value type doesn't match the type of the repeating item array that is already present.
`boolean`	`removeAttribute(XmlDataAttributeTag attribute, int... index)` Removes the specified attribute from an item value stored at the current cursor position.
`void`	`setAnyTag(XmlDataContentTag tag, int... index)` Sets the ncName and namespace fields of an any-item.
`void`	`setAttributes(IData attributes, int... index)` Sets the attribute-set for the current element
`void`	`setAttributeValue(XmlDataAttributeTag attribute, java.lang.String value, int... index)` Sets the value for the specified attribute.
`void`	`setComplexValueContent(java.lang.Object content, int... index)` Replaces the content of a complex-value at the current-position while preserving any original associated attributes.
`void`	`setContent(java.lang.Object content, int... index)` Replaces the content of the value at the current-position.
`void`	`setInstanceProp(java.lang.String name, java.lang.String value, int... index)` Sets an XML instance property (xsi attribute) on the current item.
`void`	`setItem(java.lang.Object object, int... index)` Stores a value or an indirect-item at the current cursor position.
`void`	`setNamespaceDecl(java.lang.String prefix, java.lang.String uri, int... index)` Sets a namespace declaration for the current item.
`void`	`setNamespaceDecls(IData nsDecls, int... optionalIndex)` Sets the namespace declarations for the current item.
`void`	`setObject(java.lang.Object object)` Sets the object stored at the current cursor position ( a value or array of repeating values).
`void`	`setTag(XmlDataContentTag tag)` Sets the tag of the current tag-object pair.
`void`	`setValue(java.lang.Object value, int... index)` Sets the value at the current cursor position (and index if repeating values are present).
`void`	`setValueTag(XmlDataContentTag tag, int... index)` Sets the tag of the value stored at the current cursor.

- Method Detail
  - copyCursor
```
XmlDataCursor copyCursor()
```
    Returns:
    
    a copy of this cursor
  - count
```
int count()
```
    Returns the number of items stored at the current cursor position. Items are either values or indirect-items. For a tag with repeating values (an array), the length of the array is returned. For a non-repeating value, 1 is returned. if the cursor is unpositioned, 0 is returned.
    
    Returns:
    
    number of values held by the current item.
  - data
```
IData data()
```
    Returns the IData for which this cursor is defined.
    
    Returns:
    
    the IData instance for which this cursor was obtained.
  - deleteItem
```
boolean deleteItem(int... index)
```
    Removes a single item from the array of items stored at the current cursor position. If only one item is stored at the current position, then the entire current entry is deleted (both tag and object). If only one item is present, the index must be zero, or omitted. This is true whether the current item is a single item or an array containing one item. If an index is specified, it must be less than the number of repeating values present (zero is the index of the first item). An index of -1 is interpreted as the index of the last item (i.e. count() - 1). It is an error if the cursor is unpositioned, or the index is outside of the range of items, of if repeating values are present and an index is not specified. If one or more items remain after the specified item is deleted, false is returned and the cursor remains unpositioned. If the last or only remaining item at the current position is deleted, the entire entry (tag and object) is deleted. When this happens, the cursor is positioned on the next tag, and true is returned. If there is no next tag, the cursor is positioned on the previous tag and false is returned. If there are no reaming tags, the cursor is unpositioned. In other words, true is only returned when the cursor is moved forward to the next tag because all items have been removed from the current item array. This behavior is similar to legacy IDataCursor delete() behavior.
    
    Parameters:
    
    index - optional offset (starting at zero) into the array if repeating values present
    
    Returns:
    
    true if cursor is positioned on the next item after deletion
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values present
  - deleteObject
```
boolean deleteObject()
```
    Removes the tag-object-pair (single value or array of repeating values) from the current position. If there are tags following the current position, the cursor is positioned on the next tag and true is returned. If there is no next tag, the cursor is positioned on the previous tag and false is returned. If there are no remaining tags, the cursor is unpositioned and false is returned. This behavior is similar to legacy IDataCursor delete() behavior.
    
    Returns:
    
    true if cursor is positioned on the next item after deletion
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when cursor is not positioned
  - destroy
```
void destroy()
```
    Release any resources associated with the current cursor. The cursor becomes unpositioned and no longer has any content.
  - first
```
boolean first()
```
    Positions the cursor at the first tag-object-pair. Objects are either values paired with element-tags, group-values paired with group-tags, any-items paired with any-tags, or substitution-items paired with substitution-tags. If there is no first tag-object-pair, the cursor remains unpositioned.
    
    Returns:
    
    true if there is a first item
  - first
```
boolean first(XmlDataContentTag tag)
```
    Positions the cursor on the first tag-object-pair with the specified tag and returns true. Otherwise return false and leaves the cursor unchanged.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if item is found
  - firstPartial
```
boolean firstPartial(XmlDataContentTag tag)
```
    Positions the cursor on the first tag-object-pair with a tag that partially matches the specified tag. Otherwise returns false and leave the cursor unchanged. For purposes of comparison, the particle-ids of the tags are ignored during comparison in order to find the first occurrence regardless of its particle-id. It is as if the home() method is invoked and then the next() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if item is found
  - getAnyTag
```
XmlDataContentTag getAnyTag(int... index)
```
    Returns a parsed-tag constructed from the *ncName and *namespace fields in the any-item. It will be be an instance of XmlDataElementTag or XmlDataSubstitutionTag. This is a very specialized method. More typically, getValueTag(int...) is used to return the tag associated with the item. However, if the any-item references a substitution group, the getValueTag() method returns the element tag present in the substitution group. This specialized method returns the tag created from fields in the any-item which will be either be an element-tag or a substitution-tag. This method is used only when it is necessary to distinguish between substitution tags and element tags in a any-item document. Normally, getValueTag(int...) will be sufficient, and more general.
    
    Parameters:
    
    index - offset into the repeating item array (if repeating values are present)
    
    Returns:
    
    The tag present in the any-item Document.
    
    Throws:
    
    XmlDataException.TagConflict - if the cursor is not positioned on an any-tag.
  - getAttributeNames
```
XmlDataAttributeTag[] getAttributeNames(int... index)
```
    Returns a list of attribute-tags for a complex-value stored at the current cursor position. If the value is repeating, it is necessary to specify an index to select a specific member of the array. The value of the item is as if getValue(int...) was invoked, and then attribute-tags extracted from the result.
    
    Parameters:
    
    index - offset into the repeating value array (if repeating values are present)
    
    Returns:
    
    An array of XmlDataAttributeTags, null if no attributes present
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - getAttributes
```
IData getAttributes(int... index)
```
    Returns an IData list of attributes and values for the complex-value stored at the current cursor position. If repeating values are present, it is necessary to specify an index to select a specific member of the array. This is the attribute-set paired with the *attributes field of a complex-value. If the current value is not complex or does not have a *attributes field. a null is returned. The value is obtained as if getValue(int...) was invoked, and then attribute-set is retrieved from the value.
    
    Parameters:
    
    index - the offset of the item of repeating values are present
    
    Returns:
    
    An IData object containing the attributes.
  - getAttributeValue
```
java.lang.String getAttributeValue(XmlDataAttributeTag attribute,
                                   int... index)
```
    Returns the value of an attribute for the complex-value at the current cursor position. It is an error if the cursor is unpositioned. It is an error if an element has repeating values and no index is specified. If the attribute is not defined, null is returned.
    
    Parameters:
    
    attribute - the tag of the attribute XmlDataAttributeTag)
    
    index - offset into the list of repeating values (starting at 0)
    
    Returns:
    
    null if attribute not present. May return empty String if attribute has that value.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - getContent
```
java.lang.Object getContent(int... index)
```
    Returns the content of the current value. The content does not include attributes. For non-complex-values, the current value itself is returned. For complex-values, the result obtained by getComplexValueContent(int...) is returned. If the complex-value has no content, null is returned; but if the complex-value can be interpreted as an empty group-value, the empty group is returned (rather than null). If the content is a repeating group, an IData[] is returned.
    
    Parameters:
    
    index - offset into repeating values
    
    Returns:
    
    the content of the current value.
  - getComplexValueContent
```
java.lang.Object getComplexValueContent(int... index)
```
    Returns the value paired with the *simple field or the solitary top-level group-tag. Content will always be either simple-value (a String), a group-value (an IData of tag/value pairs), or an array of group-values. A null is returned if the current value is in complex-value format but has no *simple or group-tag content.
    
    Parameters:
    
    index - the index of the repeating value that is a complex-value
    
    Returns:
    
    the content of the current element (this is the highest-level parent that does not include the attributes container)
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    XmlDataException.FormatError - when the current value is not a complex-value
  - getInstanceProp
```
java.lang.String getInstanceProp(java.lang.String name,
                                 int... optionalIndex)
```
    Retrieves the value of an instance (xsi) attribute specified for the current value. If repeating values are present, an index must be specified.
    
    Parameters:
    
    name - the name of the xsi property (e.g. nil, type)
    
    optionalIndex - offset into the repeating values
    
    Returns:
    
    the value of the property. Null if the property is not present
  - getItem
```
java.lang.Object getItem(int... index)
```
    Returns an item from the current-object. If repeating values are present, an index must be specified. If the current-tag is an element-tag, a value is returned. If the current-tag is a group-tag, a group-value is returned. If the current-tag is an indirect-tag, an indirect-item is returned (either an any-item or substitution-item). It is an error if the cursor is not positioned. It is an error if an array with more than one value is present and no index is specified. If a scalar is present, the index may be specified as zero or omitted. If an index is specified, the item at that offset in the array is returned. It is an error if index exceeds the number of items present. An index of -1 is equal to the index of the last repeating value. If the current-object is a scalar and an index of 0 or -1 is specified, the value is returned; otherwise it is an error to specify an index for a scalar value. Empty values are always be represented as empty Strings or empty IDatas, never as Java nulls.
    
    Parameters:
    
    index - offset into the repeating values array (if repeating values are present)
    
    Returns:
    
    the requested value
  - getNamespaceDecl
```
java.lang.String getNamespaceDecl(java.lang.String prefix,
                                  int... optionalIndex)
```
    Returns the the namespace URI associated with the specified prefix.
    
    Parameters:
    
    prefix - the prefix
    
    optionalIndex - the namespace URI associated with the prefix
    
    Returns:
    
    the namespace URI associated with the prefix
  - getNamespaceDecls
```
IData getNamespaceDecls(int... optionalIndex)
```
    Gets all of the namespace-prefix associations for the current value.
    
    Parameters:
    
    optionalIndex - the index of the repeating value for which prefixes are returned
    
    Returns:
    
    an IData containing prefix/namespace URI pairs
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed value does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - getObject
```
java.lang.Object getObject()
```
    Returns the current-object, the object stored at the current-position. If repeating values are present, then the entire array is returned. It is an error if the cursor is unpositioned. Normally, getObject will return a String, String[], IData, IData[], or Object[]. If the current-tag is an element-tag, a value or array of values is returned; if the the current-tag is a group-tag, a group-value or array of group-values is returned; if the current-tag is an any-tag, an any-item or array of any-items is returned; if the current-tag is a substitution-tag, a substitution-item or an array of substitution-items is returned.
    
    Returns:
    
    object stored at current cursor position
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - getTag
```
XmlDataContentTag getTag()
```
    Returns the current-tag as a parsed-tag. The tag will be either an XmlDataElementTag, an XmlDataAnyTag, an XmlDataGroupTag, or an XmlDataSubstitutionTag. An exception is thrown if the cursor is not positioned.
    
    Returns:
    
    One of the XmlDataContentTags mentioned above.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - getValue
```
java.lang.Object getValue(int... index)
```
    Returns a value from the current-object. If repeating values are present, an index must be specified. For indirect-items (items paired with any-tags or substitution-tags), the value of the indirect-item is returned. For items paired with element-tags or group-tags, the item is returned directly as the value.
    
    Parameters:
    
    index - the offset into repeating values
    
    Returns:
    
    The value stored at the current-position. It will be either complex-value, group-value, simple-value.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    See Also:
    
    XmlData.getAnyItemValueTag(IData), XmlData.getSubstitutionItemValueTag(IData)
  - getValueCursor
```
XmlDataCursor getValueCursor(int... optionalIndex)
```
    Returns an XmlDataCursor positioned on the first child of the specified value in the current-object. If the current value is not a group-value or a complex-value with non-repeating top-level group content, a null is returned. If the value is an empty XmlData, the returned cursor is in home state.
    
    Parameters:
    
    optionalIndex - the index of the repeating value
    
    Returns:
    
    an XmlDataCursor positioned on the first child of the current value.
  - getValueTag
```
XmlDataContentTag getValueTag(int... index)
```
    Returns the value-tag associated with the value at the current-position. If repeating values are present, an index must be specified. The tag is returned as a parsed-tag (in this case as an instance of XmlDataElementTag or XmlDataGroupTag). If the current-tag is an element-tag or a group-tag, the current-tag is simply returned. The behavior is the same as that of getTag(). If the current-tag is an any-tag or a substitution-tag, an XmlDataElementTag is constructed from the associated indirect-item.
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    an instance of an appropriate subclass of XmlDataTag (either XmlDataElementTag or XmlDataGroupTag)
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    See Also:
    
    XmlData.getAnyItemValueTag(IData), XmlData.getSubstitutionItemValueTag(IData)
  - hasAttributes
```
boolean hasAttributes(int... index)
```
    Determines if the value at the specified index has attributes. If an index is not specified and the current item has repeating values, true is returned if any of the values has attributes. If an index is specified, true is returned if the specified member has attributes.
    
    Parameters:
    
    index - the index offset into repeating values
    
    Returns:
    
    true if any member of the value has attributes, or the specified index member has attributes.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
  - home
```
void home()
```
    The cursor becomes unpositioned as if newly created.
  - insertItemAfter
```
void insertItemAfter(java.lang.Object item,
                     int index)
```
    Inserts an item after the specified index into the array of repeating values at the current-position. An index of -1 causes the item to be appended to the end of the array. Otherwise, the index must be a number between 0 and the length of the array minus 1. An item may be either a value or an indirect-item. When the current-tag is a substitution-tag, the value must be a substitution-item. When the current-tag is an any-tag, the value must be an an any-item. These items may be created, for example, using XmlData.createSubstitutionItem(XmlDataElementTag, Object) or XmlData.createAnyItem(XmlDataContentTag, Object). If the current-object is a scalar, it is promoted to an array prior to insertion of the new item. If the cursor has recast set to true, the new array is an Object[].
    
    Parameters:
    
    index - The insert position after which the value is inserted
    
    item - the scalar value inserted (must be simple-value, group-value, complex-value, or indirect-item)
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed value does not exist
    
    XmlDataException.UnsupportedType - when the inserted value is not an IData or String instance
    
    XmlDataException.TagAndContentConflict - when the inserted item is incompatible with the current tag (for example inserting a String when the current tag is a substitution group tag)
  - insertItemBefore
```
void insertItemBefore(java.lang.Object item,
                      int index)
```
    Inserts an item before the specified index into the array of repeating values at the current-position. An index == array.length adds to end. An index of -1 inserted the values before the last value. An item may be either a value or an indirect-item. When the current-tag is a substitution-tag, the value must be a substitution-item. When the current current-tag is an any-tag, the value must be an an any-item. These item may be created, for example, using XmlData.createSubstitutionItem(XmlDataElementTag, Object) or XmlData.createAnyItem(XmlDataContentTag, Object). If the current-object is a scalar, it is promoted to an array prior to insertion of the new item. If the cursor has recast set to true, the new array is an Object[].
    
    Parameters:
    
    item - the scalar value inserted (must be simple-value, group-value, complex-value, or indirect-item)
    
    index - the index position before which the value is inserted
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed value does not exist
    
    XmlDataException.UnsupportedType - when the inserted value is not an IData or String instance
    
    XmlDataException.TagAndContentConflict - when the inserted item is incompatible with the current tag (for example inserting a String when the current tag is a substitution group tag)
  - insertObjectAfter
```
void insertObjectAfter(XmlDataContentTag tag,
                       java.lang.Object object)
```
    Inserts a tag-object-pair after the current-position. The object may be a value, an indirect-item, or a list of values or indirect-items. The tag and values must be compatible. For example, a group-tag may only have a group-value or an array of group-values, a substitution-tag must have a substitution-item or array of substitution-items, etc.
    
    Parameters:
    
    tag - the tag of the tag/object pair to be inserted before the current cursor position
    
    object - the item or array of repeating values that is inserted (must be String, String[], IData, IData[], or Object[])
  - insertObjectBefore
```
void insertObjectBefore(XmlDataContentTag tag,
                        java.lang.Object object)
```
    Inserts a tag-object-pair before the current-position. The object may be a value, an indirect-item, or a list of values or indirect-items. The tag and values must be compatible. For example, a group-tag may only have a group-value or an array of group-values, a substitution-tag must have a substitution-item or array of substitution-items, etc.
    
    Parameters:
    
    tag - the tag of the tag/object pair to be inserted before the current cursor position
    
    object - the item or array of repeating values that is inserted (must be String, String[], IData, IData[], or Object[])
  - insertValueAfter
```
void insertValueAfter(XmlDataContentTag tag,
                      java.lang.Object value,
                      int index)
```
    Inserts a value into an array of repeating values at the current-position, after the specified index. An index of -1 causes the item to be appended to the end of the array. Otherwise, the index must be a number between 0 and the length of the array minus 1. If the current-tag is an element-tag or group-tag, the value is inserted directly into the repeating value array at the specified offset. The content-tag is irrelevant (for groups and elements) and may be null. If not null, it must match the current tag. If the current-tag is a substitution-tag or an any-tag, a substitution-item or any-item is created from the content-tag and value, and inserted into the repeating values at the specified index offset. If the current Object is a scalar, it is promoted to an array prior to insertion of the new item. If the cursor has recast set to true, the new array is an Object[].
    
    Parameters:
    
    tag - the name of the repeating value for indirect-items (may be null if current tag is an element and group)
    
    value - the value to insert (if the current tag is an any tag and the content tag is a substitution tag, value must be a substitution value).
    
    index - the index of the repeating item
    
    Throws:
    
    XmlDataException.TagAndContentConflict - when the contentTag is inappropriate for the current tag (for a substitution tag, the content tag should be an XmlDataElementTag, and for an any tag, the content tag should be an XmDataElementTag or an XmlDataSubstitutionTag
  - insertValueBefore
```
void insertValueBefore(XmlDataContentTag tag,
                       java.lang.Object value,
                       int index)
```
    Inserts a value into an array of repeating values at the current-position, before the specified index. If the current-tag is an element-tag or group-tag, the value is inserted directly into the repeating value array at the specified offset. The content-tag is irrelevant (for groups and elements) and may be null. If not null, it must match the current tag. If the current-tag is a substitution-tag or an any-tag, a substitution-item or any-item is created from the content-tag tag and value, and inserted into the repeating values before the specified index offset. If the current Object is a scalar it is promoted to an array prior to insertion of the new item. If the cursor has recast set to true, the new array is an Object[].
    
    Parameters:
    
    tag - the tag of the value for indirect-items (may be null if current tag is an element and group tag)
    
    value - the value to insert (if the current tag is an any tag and the content tag is a substitution tag, value must be a substitution value).
    
    index - the index of the repeating item
    
    Throws:
    
    XmlDataException.TagAndContentConflict - when the contentTag is inappropriate for the current tag (for a substitution tag, the content tag should be an XmlDataElementTag, and for an any tag, the content tag should be an XmDataElementTag or an XmlDataSubstitutionTag
  - isAny
```
boolean isAny()
```
    Determines if the current-tag is an any-tag.
    
    Returns:
    
    true if the current item has an XmlDataAnyTag tag
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - isComplexValue
```
boolean isComplexValue(int... index)
```
    Determines if the value at the current-position is an IData with a single group tag, an *attribute tga, or a *simple tag. If repeating values are present, an index must be specified.
    
    Parameters:
    
    index - offset into repeating values.
    
    Returns:
    
    true if the current value is complex.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - isEmpty
```
boolean isEmpty(int... index)
```
    Determines if the value at the current-position is empty (or non-existent complex content for complex-values). If repeating values are present, an index must be specified.
    
    Parameters:
    
    index - offset into repeating values
    
    Returns:
    
    true if the current value is an empty String, an empty IData, or a complex-value with empty content, or a complex-value with no content.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - isGroup
```
boolean isGroup()
```
    Determines if the current-tag is a group-tag.
    
    Returns:
    
    true if the current item has an XmlDataGroupTag tag
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    See Also:
    
    XmlDataContentTag.isGroup()
  - isGroupValue
```
boolean isGroupValue(int... index)
```
    Determines if the value at the current-position is a group-value. A group-value is an IData that does not have a *attributes field, a *simple field, or solitary top-level group-tag. If repeating values are present, an index must be specified.
    
    Parameters:
    
    index - the offset into the repeating values array
    
    Returns:
    
    true if the value is an IData that cannot be interpreted as a complex-value.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    See Also:
    
    XmlData.isGroupValue(Object)
  - isHome
```
boolean isHome()
```
    Indicates whether the cursor is unpositioned.
    
    Returns:
    
    true if the cursor is unpositioned
  - isRecast
```
boolean isRecast()
```
    Indicates if automatic recast is in effect.
    
    Returns:
    
    true if it is in effect
  - isRepeating
```
boolean isRepeating()
```
    Determines if the current-object is a repeating value. True is returned in the current-object is array (by convention, zero-length arrays are not allowed). False is returned if the current-object is not an array.
    
    Returns:
    
    true if current-object contains a repeating value
    
    Throws:
    
    XmlDataException.UnpositionedCursor - if the cursor is not positioned
  - isSimpleValue
```
boolean isSimpleValue(int... index)
```
    Determines if the value at the current-position is a simple value. If repeating values are present, an index must be specified.
    
    Parameters:
    
    index - the offset into the repeating values array
    
    Returns:
    
    true if the specified value an instance of String
    
    Since:
    
    10.2
  - isSubstitution
```
boolean isSubstitution()
```
    Determines if the current-tag is a substitution-tag
    
    Returns:
    
    true if the current-object has an substitution-tag
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - last
```
boolean last()
```
    Positions the cursor at the last tag-object-pair. Objects are either values paired with element-tags, group-values paired with group-tags, any-items paired with any-tags, or substitution-items paired with substitution-tags. If there is no last tag-object-pair, the cursor remains unpositioned.
    
    Returns:
    
    true if there is a last value
  - last
```
boolean last(XmlDataContentTag tag)
```
    Positions the cursor on the last occurrence of the last tag-object-pairg with the specified tag and return true. Otherwise return false and leave the cursor unchanged.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if tag is found
  - lastPartial
```
boolean lastPartial(XmlDataContentTag tag)
```
    Positiosn the cursor on the last tag-object-pair with a tag that partially matches the specified tag. Otherwise return false and leave the cursor unchanged. For purposes of comparison, the particle-ids of the tags are ignored during comparison in order to find the last occurrence regardless of its particle-id. It is as if the last() method is invoked and then the previous() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.
    
    Parameters:
    
    tag - the XmlDataContentTag to be searched
    
    Returns:
    
    true if tag is found
  - newCursor
```
XmlDataCursor newCursor(IData data)
```
    Creates a new XmlDataCuror instances from an existing cursor factory.
    
    Parameters:
    
    data - an existing IData who's cursor factory is used to create a new XmlDataCursor instance.
    
    Returns:
    
    a new cursor using the same factory that create this cursor.
  - next
```
boolean next()
```
    Positions the cursor on the next tag-object-pair. Returns false if there is no next pair and the cursor remains unchanged.
    
    Returns:
    
    true if there is a next tag-object pair.
  - next
```
boolean next(XmlDataContentTag tag)
```
    Positiona the cursor on the next tag-object-pair that has the specified tag and returns true. Otherwise returns false and leaves the cursor unchanged.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if tag is found
  - nextPartial
```
boolean nextPartial(XmlDataContentTag tag)
```
    Positions the cursor on the next tag-object-pair with a tag that partially matches the specified tag. Otherwise returns false and leavse the cursor unchanged. For purposes of comparison, the particle-ids of the tags are ignored during comparison in order to find the next occurrence regardless of its particle-id. It is as if the next() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if item is found
  - previous
```
boolean previous()
```
    Positions the cursor on the previous tag-object-pair. Returns false if there is no previous item and the cursor remains unchanged.
    
    Returns:
    
    true if there is a previous item
  - previous
```
boolean previous(XmlDataContentTag tag)
```
    Positions the cursor on the previous tag-object-pair with the specified tag and return true. Otherwise returns false and leaves the cursor unchanged.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if item is found
  - previousPartial
```
boolean previousPartial(XmlDataContentTag tag)
```
    Positions the cursor on the previous tag-object-pair with a tag that partially matches the specified tag. Otherwise returns false and leave the cursor unchanged. For purposes of comparison, the particle-ids of the tags are ignored during comparison in order to find the previous occurrence regardless of its particle-id. It is as if the previous() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.
    
    Parameters:
    
    tag - the searched content-tag
    
    Returns:
    
    true if item is found
  - removeAttribute
```
boolean removeAttribute(XmlDataAttributeTag attribute,
                        int... index)
```
    Removes the specified attribute from an item value stored at the current cursor position. It is an error if the cursor is not positioned on an element, or indirect-item. It is an error if repeating values are present and an index is not provided.
    
    Parameters:
    
    attribute - an XmlDataAttributeTag naming the attribute
    
    index - the offset if the element is a repeating value
    
    Returns:
    
    true if the attribute was found and removed
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - recast
```
void recast(boolean mode)
```
    Indicates whether existing String[] or IData[] arrays for repeating values should be automatically recreated as an Object[] when the inserted or set value type doesn't match the type of the repeating item array that is already present. This is typically set true when inserting values into an infoset that was created without a document type template and therefore contains Object[]s rather than String[] and IData[]s.
    
    Parameters:
    
    mode - true causes automatic recast; default is false
  - setAttributes
```
void setAttributes(IData attributes,
                   int... index)
```
    Sets the attribute-set for the current element
    
    Parameters:
    
    attributes - IData list of attributes
    
    index - position in repeating value
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - setAttributeValue
```
void setAttributeValue(XmlDataAttributeTag attribute,
                       java.lang.String value,
                       int... index)
```
    Sets the value for the specified attribute. If a repeating value is present, an index must be specified. If the current content is simple (a String), the content is replaced by complex content with a *simple child containing the original String value.
    
    Parameters:
    
    attribute - an XmlDataAttributeTag naming the attribute
    
    value - the value to set (must be a String)
    
    index - optional offset into array of repeating values
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    XmlDataException.UnsupportedType - when a value other than a String is passed
  - setComplexValueContent
```
void setComplexValueContent(java.lang.Object content,
                            int... index)
```
    Replaces the content of a complex-value at the current-position while preserving any original associated attributes. If repeating values are present, an index must be provided. It is an error if the cursor is not positioned on an element. It is an error if the index lies outside the range of the list of values.
    
    Parameters:
    
    content - the value that replaces the current content
    
    index - optional offset when repeating values are present; a second index is required when repeating content is present
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present.
  - setContent
```
void setContent(java.lang.Object content,
                int... index)
```
    Replaces the content of the value at the current-position. For simple-values it must be a String. For group-values, it must be an IData. For complex-values it may be a String, IData, or IData[]. A null child causes the content of complex-values to be removed completely. setContent is a convenience method. Essentially, if the accessed value is simple or group, setContent() behaves like setValue(Object, int...). When the accessed value is complex, this method behaves like setComplexValueContent(Object, int...).
    
    Parameters:
    
    content - the content of the current value
    
    index - the offset into a list of repeating values
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present.
  - setInstanceProp
```
void setInstanceProp(java.lang.String name,
                     java.lang.String value,
                     int... index)
```
    Sets an XML instance property (xsi attribute) on the current item. If the current item has repeating values, an index is required.
    
    Parameters:
    
    name - the name of the property(e.g. 'nil')
    
    value - the value of the property (e.g. 'true')
    
    index - the offset index into repeating values
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present.
  - setItem
```
void setItem(java.lang.Object object,
             int... index)
```
    Stores a value or an indirect-item at the current cursor position. If the current cursor is positioned on a repeating value, an index must be specified. It is an error if the cursor is unpositioned. The value stored must be a simple-value, a group-value, a complex-value, or an indirect-item. Empty values should be represented by empty Strings or empty IData. For document-type-directed conversion, a repeating value is always represented as either a String[] or an IData[], or Object[]s, as appropriate. For non-directed conversion, repeating values are always stored as Object[]s.
    It is always preferable to use one of the XmlData methods to construct the value if it is not a String or String[]. For example, use XmlData.createGroupValue(Object...) if the content does not contain attributes and the top-level group does not contain repeating values. Otherwise use XmlData.createComplexValue(). When creating an indirect-item, use a methods such as XmlData.createAnyItem(XmlDataContentTag, Object) to create an any-item or a method such as XmlData.createSubstitutionItem(XmlDataElementTag, Object) to create a substitution-item.
    If an index is specified, the specified value in the array of repeating values is set and any associated attributes cleared. When no index is specified, the object must be scalar String or IData object. An index of -1 is equivalent to the index of the last repeating item. It is an error if the value is incompatible with the current-tag. For example, substitution-tags, group-tags, and any-tags only accept an IData as value. If tag and content are not compatible, the TagAndContentConflict exception is thrown.
    
    Parameters:
    
    object - the value to be replaced.
    
    index - the position in the list of repeating values to be set. When index is specified, the value may not be an array.
    
    Throws:
    
    XmlDataException.UnsupportedType - when content other than a String or an IData instance is passed
    
    XmlDataException.TagAndContentConflict - when the content is not appropriate for the current tag (for example if the current tag is an XmlDataSubstitutionTag, then the content must be an IData in *substitution document format).
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - setNamespaceDecl
```
void setNamespaceDecl(java.lang.String prefix,
                      java.lang.String uri,
                      int... index)
```
    Sets a namespace declaration for the current item. If the current item has repeating values, the index is used to indicate the specific value.
    
    Parameters:
    
    prefix - the prefix
    
    uri - the namespace URI.
    
    index - the offset index into repeating values
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - setObject
```
void setObject(java.lang.Object object)
```
    Sets the object stored at the current cursor position ( a value or array of repeating values). It is an error if the cursor is unpositioned. The Object must be a String, an IData, a String[], an IData[], or an Object[].
    
    Parameters:
    
    object - the offset to be stored at the current element.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - setNamespaceDecls
```
void setNamespaceDecls(IData nsDecls,
                       int... optionalIndex)
```
    Sets the namespace declarations for the current item.
    
    Parameters:
    
    nsDecls - IData list of prefix/namespace pairs
    
    optionalIndex - the index of the repeating item
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - setAnyTag
```
void setAnyTag(XmlDataContentTag tag,
               int... index)
```
    Sets the *ncName and *namespace fields of an any-item. This is a specialized method. More typically setValueTag(XmlDataContentTag, int...) is used. This method sets the any-item tag directly even if the value of the any-item is a substitution-item. This method is typically used in conjunction with getAnyTag(int...)
    
    Parameters:
    
    tag - the tag used to set ncName and namespace in the any-item.
    
    index - offset into list of repeating values
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
  - setTag
```
void setTag(XmlDataContentTag tag)
```
    Sets the tag of the current tag-object pair. The tag must be either an XmlDataElementTag, an XmlDataAnyTag, an XmlDataGroupTag, or an XmlDataSubstitutionTag. The tag must be compatible with the current value. A group tag can only be assigned to an item with IData content. An any tag can only be assigned to an item with content in the any format. An element tag may not be assigned to content that is in the any or substitution head format.
    
    Parameters:
    
    tag - is one of the XmlDataContentTags mentioned above.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - setValue
```
void setValue(java.lang.Object value,
              int... index)
```
    Sets the value at the current cursor position (and index if repeating values are present). For element and group tags, the value (simple, group, or complex) is stored directly at the current position (and index). For any and substitution tags, the value tag is stored in the indirect-item value. (substitution-item or any-item). For XmlDataElementTags, the item must be a String or IData object. For XmlDataGroupTags, it must be an IData. If there is an existing object and it is an array, an index must be specified. For an XmlDataAnyTag, the object is stored indirectly; it is stored in the *value field of the any-item Document object. For an XmlDataSubstitutionTag, the item is stored indirectly; it is stored as the object of a single child which contains group content representing the substituted tag/object.
    
    Parameters:
    
    value - the IData or String object that ia assigned as the value of the current cursor position.
    
    index - the offset into the repeating values if the current item is an array.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values are present
    
    XmlDataException.FormatError - when the current element's value is not compatible with the current, making it impossible to properly set the current value
  - setValueTag
```
void setValueTag(XmlDataContentTag tag,
                 int... index)
```
    Sets the tag of the value stored at the current cursor. If the current tag is an element or a group tag, the new tag is stored directly in the tag/value pair. In this case, setValueTag() behaves exactly like setTag(XmlDataContentTag). However, if the current value is an indirect-item, the tag is stored in the indirect-item. If the indirect-item is an any-item, the tag is decomposed and stored in the *ncName and *namespace fields of the any-item. The current tag remains unchanged. If the current tag is a substitution-tag, the value tag is stored as the tag of the first and only child in the substitution-item. The index parameter only has meaning for substitution and any objects (names of repeated elements and groups are identical for all entries).
    
    Parameters:
    
    tag - the tag assigned to the current value
    
    index - the offset into the repeating value array.
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
    
    XmlDataException.IndexOutOfRange - when the indexed item does not exist
    
    XmlDataException.IndexRequired - when an index is not specified and repeating values present
    
    XmlDataException.FormatError - when the current element's value is not compatible with the current tag, making it impossible to properly set the current value

Interface XmlDataCursor

Introduction

See glossary of terms

Tag creation

Three modes of access: value, item, and object.

Namespace declarations and instance properties

XmlDataCursor method summary:

Glossary of terms:

Method Summary

Method Detail

copyCursor

count

data

deleteItem

deleteObject

destroy

first

first

firstPartial

getAnyTag

getAttributeNames

getAttributes

getAttributeValue

getContent

getComplexValueContent

getInstanceProp

getItem

getNamespaceDecl

getNamespaceDecls

getObject

getTag

getValue

getValueCursor

getValueTag

hasAttributes

home

insertItemAfter

insertItemBefore

insertObjectAfter

insertObjectBefore

insertValueAfter

insertValueBefore

isAny

isComplexValue

isEmpty

isGroup

isGroupValue

isHome

isRecast

isRepeating

isSimpleValue

isSubstitution

last

last

lastPartial

newCursor

next

next

nextPartial

previous

previous

previousPartial

removeAttribute

recast

setAttributes

setAttributeValue

setComplexValueContent

setContent

setInstanceProp

setItem

setNamespaceDecl

setObject

setNamespaceDecls

setAnyTag

setTag

setValue

setValueTag