XmlDataTreeCursor (webMethods Java API Reference)

All Superinterfaces:: XmlDataCursor

All Known Implementing Classes:: XmlDataTreeCursorImpl

public interface XmlDataTreeCursor
extends XmlDataCursor

An extension of XmlDataCursor that facilitates navigation through multiple levels in an XmlData infoset.

Overview

The XmlDataTreeCursor provides additional capabilities beyond those of the XmlDataCursor. In particular, repeating values can be navigated as if they were flattened scalar values rather than arrays so that additional methods such as nextItem() and previousItem() position to next or previous individual item in the array. This is achieved by internally maintaining a current-index in this cursor that specifies an offset within repeating-values.

There are also additional methods such as firstItem() and lastItem() that position on the very first and very last items in a group-value by setting the current-index as appropriate. There are also the deleteForward() and deleteBackward() methods that are index-aware and update the current-index after deleting an individual item. Indexed XmlDataCursor accessors such as getValue(), getItem, getContent(), setItem(), setValue(), and setContent() behave slightly differently for XmlDataTreeCursor. When the index is omitted, the item at the current-index is referenced (contrasted to an XmlDataCursor for which an omitted index implies that there is only one item).

Finally, the XmlDataTreeCursor "object" methods have the same basic behavior as the XmlDataCursor "object" methods except that any method call that changes the current-position also resets the current-index to zero. The XmlDataCursor concepts such as current-position, current-object, and current-tag are exactly the same for XmlDataTreeCursor. When cursors are stacked during tree traversal, these concepts apply to the cursor most recently pushed onto the cursor stack. Other concepts such as current-tree-position are unique to XmlDataTreeCursor.

XmlDataTreeCursor also supports navigation through a hierarchy of XmlData objects using the parent(), firstChild(), and lastChild() methods. These methods maintain a stack of cursors. Invoking lastChild() or firstChild() pushes the current cursor onto a stack and creates a new cursor for the child content. The parent() method pops the top of the cursor stack and restores the parent as the current XmlData object. It is also possible to navigate through nested XmlData structures in document order using the methods nextInOrder() and previousInOrder().

See glossary of terms

XmlDataTreeCursor method summary by functional group:

Methods	Operation
`getItem()`, `setItem()`, `deleteItem()`, `insertItemAfter()`, `insertItemBefore()`	Similar to the XmlDataCursor "item" methods with the additional behavior of defaulting to the current-item when no index is specified even though the current-object represents repeating values. This is in contrast to XmlDataCursor "item" methods which have no current-index and throw an exception when no index is specified and repeating values are present.
`currentIndex()`, `deleteBackward()`, `deleteForward()`, `firstItem()`, `lastItem()`, `nextItem()`, `lastItem()`, `previousItem()`, `setIndex()`	Additional "item" methods that maintain the current-item after as operation.
`firstChild()`, `lastChild()`, `parent()`, `nextInOrder()`, `previousInOrder()`, `top()`, `depth()`	Additional "item" methods that facilitate navigation through multiple levels of the XmlData infoset tree.
`getValue()`, `setValue()` `getValueTag()`, `setValueTag()`, `insertValueAfter()`, `insertValueBefore()`, `getValueTag()`, `setValueTag()` `getComplexValueContent()`, `setComplexValueContent()`, `getContent()`, `setContent()`, `isEmpty()`, `isSimpleValue()`, `isGroupValue()`, `isComplexValue()`, `getValueCursor()`	Similar to the XmlDataCursor value" methods with the additional behavior of defaulting to the current-item when no index is specified even though the current-object represent repeating values. This in contrast to XmlDataCursor "item" methods which throw an exception when no index is specified when repeating values are present.
`getAttributes()`, `setAttributes()`, `getAttributeValue()`, `setAttributeValue()`, `hasAttributes()`, `getAttributeNames()`, `removeAttribute()`	Similar to the XmlDataCursor "attribute" methods with the additional behavior of defaulting to the current-index when no index is specified even though the current-object represent repeating values. This in contrast to XmlDataCursor "attribute" methods which throw an exception when no index is specified when repeating values are present.
`getNamespaceDecl`, `setNamespaceDecl()`, `getNamespaceDecls()`, `setNamespaceDecls()`, `getInstanceProp()`, `setInstanceProp()`	Similar to the XmlDataCursor "namespace" methods with the additional behavior of defaulting to the current-index when no index is specified even though the current-object represent repeating values. This in contrast to XmlDataCursor "attribute" methods which throw an exception when no index is specified when repeating values are present.
`setObjec()`, `deleteObjec()`, `next()`, `first()`, `previous()`, `last()`, `insertObjectBefore()`, `insertObjectAfter()`, `count()`, `firs()`, `next()`, `previous()`, `firstPartial()`, `nextPartial()`, `previousPartial()`, `lastPartial()`	Similar to the XmlDataCursor "object" methods except that explicitly positioning to a tag-object-pair causes the current-index to be reset to zero.
`copyCursor()`, `data()`	Methods similar to XmlDtaCursor methods but only operate on current-cursor. Previously pushed cursors along the navigation path are not affected.

Glossary of terms:

current-cursor -- the cursor navigating the current level of the tree. Methods such as firstChild() push the current-cursor onto a stack and allocate a new cursor in order to navigate the child content of the current-value. The newly created cursor becomes the current-cursor. Methods such as parent() pop the top cursor from the internal cursor stack and the popped cursor then becomes the current-cursor.
child -- a child is a member of the current-value. Only group-values or a complex-values can have children. group-values with no members or complex-values with no group-value content are defined to have no children
current-index -- an index into the current-object of repeating values. The current-index is maintained by this cursor. If repeating values are not present, the current-index is zero. When initially positioned on an object, the current-index is set to zero (the first or only item). Subsequent calls to nextItem() and similar methods cause the index to be incremented. Subsequents calls to previousItem() and similar methods cause the index to be decremented. When the current-index is positioned on the last item in the current-object, a subsequent call to nextItem() resets the current index to zero and points to the first item in the next tag-object-pair. When the current-index is positioned on the first item in the current-object, a subsequent call to previousItem() sets the current-index to point at the last item in the previous tag-object-pair. The combination of current-object and current-index uniquely identify the current-item
current-item -- the item stored at the current-tree-position. If the current-tag is an element-tag or a group-tag, the current-item is the same as the current-value and will be either a simple-value, group-value, or complex-value. If the current-tag is an indirect-tag, then the current-item is an indirect-item.
current-value -- the value stored at the current-tree-position. If the current-tag is an element-tags or a group-tag, the current-value is the same as the current-item and will be either a simple-value, group-value, or complex-value. If the current-tag is an any-tag or substitution-tag, the current-value is the value stored indirectly in the indirect-item that is the current-item.
current-tree-position -- the combination of the current-object and the current-index from the current-cursor.
in-order -- the same as DOM document order. The natural order in which XML element nodes are traversed in a document. It is essentially the order in which element tags are encountered during a sequential scan of an XML document. The nextInOrder() and previousInOrder() methods navigate through an XMlData infoset using in-order traversal.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`currentIndex()` Returns the index of the current-item when the current-object is an object containing repeating values.
`boolean`	`deleteBackward()` Deletes the current-item and positions the cursor on the previous item.
`boolean`	`deleteForward()` Deletes the current-item and positions the cursor on the next item.
`boolean`	`deleteItem(int... index)` Delete the specified item.
`int`	`depth()` Returns the stacked cursor depth.
`boolean`	`firstChild()` Positions this cursor on the first child of the current-value.
`boolean`	`firstItem()` Positions this cursor on the first item.
`XmlDataContentTag`	`getAnyTag(int... index)` The behavior is similar to `XmlDataCursor.getAnyTag(int...)` except that an omitted index references the current-item rather than the first and only item content.
`XmlDataAttributeTag[]`	`getAttributeNames(int... index)` The behavior is similar to `XmlDataCursor.getAttributeNames(int...)` except that an omitted index references the current-item rather than the first and only item content.
`IData`	`getAttributes(int... index)` The behavior is similar to `XmlDataCursor.getAttributes(int...)` except that an omitted index references the current-item rather than the first and only item content.
`java.lang.String`	`getAttributeValue(XmlDataAttributeTag attribute, int... index)` The behavior is similar to `XmlDataCursor.getAttributeValue(XmlDataAttributeTag, int...)` except that an omitted index references the current-item rather than the first and only item content.
`java.lang.Object`	`getComplexValueContent(int... index)` The behavior is similar to `XmlDataCursor.getComplexValueContent(int...)` except that an omitted index references the current-item content rather than the first and only item content.
`java.lang.Object`	`getContent(int... index)` The behavior is similar to `XmlDataCursor.getContent(int...)` except that an omitted index references the current-item content rather than the first and only item content.
`java.lang.String`	`getInstanceProp(java.lang.String name, int... index)` The behavior is similar to `XmlDataCursor.getInstanceProp(String, int...)` except that an omitted index references the current-item rather than the first and only item content.
`java.lang.Object`	`getItem(int... index)` The behavior is similar to `XmlDataCursor.getItem(int...)` except that an omitted index references the current-item rather than the first and only item.
`java.lang.String`	`getNamespaceDecl(java.lang.String prefix, int... index)` The behavior is similar to `XmlDataCursor.getNamespaceDecl(String, int...)` except that an omitted index references the current-item rather than the first and only item content.
`IData`	`getNamespaceDecls(int... index)` The behavior is similar to `XmlDataCursor.getNamespaceDecls(int...)` except that an omitted index references the current-item rather than the first and only item content.
`java.lang.Object`	`getValue(int... index)` The behavior is similar to `XmlDataCursor.getValue(int...)` except that an omitted index references the current-item value rather than the first and only item value.
`XmlDataContentTag`	`getValueTag(int... index)` The behavior is similar to `XmlDataCursor.getValueTag(int...)` except that an omitted index references the current-item value-tag rather than the first and only item's value-tag.
`boolean`	`hasAttributes(int... index)` The behavior is exactly like `XmlDataCursor.hasAttributes(int...)` except that an omitted index references the current-item value rather than the first and only item value.
`void`	`insertItemAfter(java.lang.Object item)` Inserts an item after the current-item in a repeating value.
`void`	`insertItemBefore(java.lang.Object item)` Inserts an item before the current-item in a repeating value.
`void`	`insertValueAfter(XmlDataContentTag valueTag, java.lang.Object value)` Inserts a value and value-tag after the current-item.
`void`	`insertValueBefore(XmlDataContentTag valueTag, java.lang.Object value)` Inserts a value and value-tag before the current-item.
`boolean`	`isComplexValue(int... index)` The behavior is similar to `XmlDataCursor.isComplexValue(int...)` except that an omitted index references the current-item.
`boolean`	`isEmpty(int... index)` The behavior is similar to `XmlDataCursor.isEmpty(int...)` except that an omitted index references the current-item.
`boolean`	`isGroupValue(int... index)` The behavior is similar to `XmlDataCursor.isGroupValue(int...)` except that an omitted index references the current-item.
`boolean`	`isSimpleValue(int... index)` The behavior is similar to `XmlDataCursor.isSimpleValue(int...)` except that an omitted index references the current-item.
`boolean`	`isTop()` Determines if the XmlDataTreeCursor is positioned somewhere in the top level.
`boolean`	`lastChild()` Positions this cursor on the last child value of the current-value.
`boolean`	`lastItem()` Positions this cursor on the last item.
`java.lang.Integer`	`nextInOrder()` Positions this cursor to the next in-order item.
`boolean`	`nextItem()` Positions this cursor on the next item.
`boolean`	`nextItem(XmlDataContentTag tag)` Positions this cursor on the next item with the specified tag.
`boolean`	`nextValueTag(XmlDataContentTag tag)` Positions this cursor on the next item with a value-tag that matches the search tag.
`boolean`	`parent()` Moves the XmlDataTreeCursor up one level by popping the top-level cursor from the internal stack of cursor.
`java.lang.Integer`	`previousInOrder()` Positions the cursor to the previous in-order item.
`boolean`	`previousItem()` Positions this cursor on the previous item.
`boolean`	`previousItem(XmlDataContentTag tag)` Positions this cursor on the previous item with the specified tag.
`boolean`	`previousValueTag(XmlDataContentTag tag)` Positions this cursor the previous item with a value-tag that matches the search tag.
`boolean`	`removeAttribute(XmlDataAttributeTag attribute, int... index)` Removes the specified attribute.
`void`	`setAnyTag(XmlDataContentTag tag, int... index)` The behavior is similar to `XmlDataCursor.setAnyTag(XmlDataContentTag, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setAttributes(IData attributes, int... index)` The behavior is similar to `XmlDataCursor.setAttributes(IData, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setAttributeValue(XmlDataAttributeTag attribute, java.lang.String value, int... index)` The behavior is similar to `XmlDataCursor.setAttributeValue(XmlDataAttributeTag, String, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setComplexValueContent(java.lang.Object item, int... index)` The behavior is exactly the same `XmlDataCursor.setComplexValueContent(java.lang.Object, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setContent(java.lang.Object item, int... index)` The behavior is exactly the same `XmlDataCursor.setContent(java.lang.Object, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setIndex(int index)` Establishes the current-item in repeating values.
`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 item, int... index)` The behavior is similar to `XmlDataCursor.setItem(java.lang.Object, int...)` except that an omitted index always accesses the current-item rather than the first and only item.
`void`	`setNamespaceDecl(java.lang.String prefix, java.lang.String uri, int... index)` The behavior is similar to `XmlDataCursor.setNamespaceDecl(String, String, int...)` except that an omitted index always references the current-item rather the first and only item.
`void`	`setNamespaceDecls(IData nsDecls, int... index)` The behavior is similar to `XmlDataCursor.setNamespaceDecls(IData, int...)` except that an omitted index always references the current-item rather the first and only item.
`void`	`setValue(java.lang.Object item, int... index)` The behavior is similar to `XmlDataCursor.setValue(java.lang.Object, int...)` except that an omitted index always accesses the current-item value rather than the first and only item value.
`void`	`setValueTag(XmlDataContentTag tag, int... index)` The behavior is similar to `XmlDataCursor.setValueTag(com.wm.xmldata.XmlDataContentTag, int...)` except that an omitted index always accesses the current-item;s value-tag rather than the first and only item's value-tag.
`void`	`top()` Positions the TreeCursor on the top-level and destroys all intervening cursors.

Methods inherited from interface com.wm.xmldata.XmlDataCursor
copyCursor, count, data, deleteObject, destroy, first, first, firstPartial, getObject, getTag, getValueCursor, home, insertItemAfter, insertItemBefore, insertObjectAfter, insertObjectBefore, insertValueAfter, insertValueBefore, isAny, isGroup, isHome, isRecast, isRepeating, isSubstitution, last, last, lastPartial, newCursor, next, next, nextPartial, previous, previous, previousPartial, recast, setObject, setTag

- Method Detail
  - currentIndex
```
int currentIndex()
```
    Returns the index of the current-item when the current-object is an object containing repeating values. For a non-repeating value, the index is always zero (because there is only 1 item).
    
    Returns:
    
    int value of the current-index. An unpositioned cursor returns -1.
  - deleteBackward
```
boolean deleteBackward()
```
    Deletes the current-item and positions the cursor on the previous item. If the first item of the current-object is being deleted, the cursor is positioned on the last or only item of the previous object. If there is no previous object, the cursor becomes unpositioned. Returns false if there are no more previous items and leaves the cursor unpositioned.
    
    Returns:
    
    true if more items remain in the backward direction
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - deleteForward
```
boolean deleteForward()
```
    Deletes the current-item and positions the cursor on the next item. If the last item of the current-object is being deleted, the cursor is positioned on the first or only item of the next object. If there is no next object, the cursor becomes unpositioned.
    
    Returns:
    
    true if more items remain in the forward direction
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - deleteItem
```
boolean deleteItem(int... index)
```
    Delete the specified item. This method's behavior is similar to XmlDataCursor.deleteItem(int...) except that an omitted index results in current-item deletion.
    
    Specified by:
    
    deleteItem in interface XmlDataCursor
    
    Parameters:
    
    index - optional offset (starting at zero) into the array of repeating values are 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
  - depth
```
int depth()
```
    Returns the stacked cursor depth. Initially zero. For every invocation of firstChild() or lastChild() that returns true, the depth increases by one. For every invocation of parent() that returns true, the depth decreases by one.
    
    Returns:
    
    the number of stacked cursors (not counting the current cursor)
  - firstChild
```
boolean firstChild()
```
    Positions this cursor on the first child of the current-value. Only group-values and complex-values with group-value content have children. If the current-value does not contain a child, (for example it contains a String or an empty IData), false is returned and the cursor position remains unchanged. If the current-value has one or more children, the current-cursor is pushed onto a stack and a new cursor is positioned on the first child item. If it is necessary to obtain a cursor on empty content, consider method XmlDataCursor.getValueCursor(int...).
    
    Returns:
    
    true if the current-value has children
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - firstItem
```
boolean firstItem()
```
    Positions this cursor on the first item. The current-item becomes the first tag-object-pair. If the first object is an array (repeating values), the cursor is positioned on first item in the array by setting the current-index to zero. In other words, the first item is the first member of a repeating values Object array. If the first object is not an array, then the first item is simply the first object.
    
    Returns:
    
    true if there is a first item.
  - getAnyTag
```
XmlDataContentTag getAnyTag(int... index)
```
    The behavior is similar to XmlDataCursor.getAnyTag(int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getAnyTag in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the content of the complex value
    
    See Also:
    
    XmlDataCursor.getAttributeNames(int...)
  - getAttributeNames
```
XmlDataAttributeTag[] getAttributeNames(int... index)
```
    The behavior is similar to XmlDataCursor.getAttributeNames(int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getAttributeNames in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    array of XmlDataAttributeTags
    
    See Also:
    
    XmlDataCursor.getAttributeNames(int...)
  - getAttributes
```
IData getAttributes(int... index)
```
    The behavior is similar to XmlDataCursor.getAttributes(int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getAttributes in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the IData associated with the *attributes tag, the attribute definitions
    
    See Also:
    
    XmlDataCursor.getAttributes(int...)
  - getAttributeValue
```
java.lang.String getAttributeValue(XmlDataAttributeTag attribute,
                                   int... index)
```
    The behavior is similar to XmlDataCursor.getAttributeValue(XmlDataAttributeTag, int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getAttributeValue in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    attribute - the tag of the attribute XmlDataAttributeTag)
    
    Returns:
    
    the attribute value
    
    See Also:
    
    XmlDataCursor.getAttributeValue(XmlDataAttributeTag, int...)
  - getComplexValueContent
```
java.lang.Object getComplexValueContent(int... index)
```
    The behavior is similar to XmlDataCursor.getComplexValueContent(int...) except that an omitted index references the current-item content rather than the first and only item content.
    
    Specified by:
    
    getComplexValueContent in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the content of the complex value
    
    See Also:
    
    XmlDataCursor.getComplexValueContent(int...)
  - getContent
```
java.lang.Object getContent(int... index)
```
    The behavior is similar to XmlDataCursor.getContent(int...) except that an omitted index references the current-item content rather than the first and only item content.
    
    Specified by:
    
    getContent in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the content of the requested item; content is always either simple content (a String) or group content (i.e. an IData of tag/object pairs)
    
    See Also:
    
    XmlDataCursor.getContent(int...)
  - getInstanceProp
```
java.lang.String getInstanceProp(java.lang.String name,
                                 int... index)
```
    The behavior is similar to XmlDataCursor.getInstanceProp(String, int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getInstanceProp in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    name - the name of the xsi property (e.g. nil, type)
    
    Returns:
    
    the value of the specified instance property
    
    See Also:
    
    XmlDataCursor.getInstanceProp(String, int...)
  - getItem
```
java.lang.Object getItem(int... index)
```
    The behavior is similar to XmlDataCursor.getItem(int...) except that an omitted index references the current-item rather than the first and only item.
    
    Specified by:
    
    getItem in interface XmlDataCursor
    
    Parameters:
    
    index - offset into the repeating content array (if repeating content is present)
    
    Returns:
    
    the requested item
    
    See Also:
    
    XmlDataCursor.getItem(int...)
  - getNamespaceDecl
```
java.lang.String getNamespaceDecl(java.lang.String prefix,
                                  int... index)
```
    The behavior is similar to XmlDataCursor.getNamespaceDecl(String, int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getNamespaceDecl in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    prefix - the prefix
    
    Returns:
    
    the value of the specified prefix
    
    See Also:
    
    XmlDataCursor.getNamespaceDecl(String, int...)
  - getNamespaceDecls
```
IData getNamespaceDecls(int... index)
```
    The behavior is similar to XmlDataCursor.getNamespaceDecls(int...) except that an omitted index references the current-item rather than the first and only item content.
    
    Specified by:
    
    getNamespaceDecls in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the IData containing the namespace declarations
    
    See Also:
    
    XmlDataCursor.getNamespaceDecls(int...)
  - getValue
```
java.lang.Object getValue(int... index)
```
    The behavior is similar to XmlDataCursor.getValue(int...) except that an omitted index references the current-item value rather than the first and only item value.
    
    Specified by:
    
    getValue in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content
    
    Returns:
    
    the requested item value (which is the item itself, or the value if it is an indirect item)
    
    See Also:
    
    XmlDataCursor.getValue(int...)
  - getValueTag
```
XmlDataContentTag getValueTag(int... index)
```
    The behavior is similar to XmlDataCursor.getValueTag(int...) except that an omitted index references the current-item value-tag rather than the first and only item's value-tag.
    
    Specified by:
    
    getValueTag in interface XmlDataCursor
    
    Parameters:
    
    index - the index of the repeating value
    
    Returns:
    
    the item value-tag
    
    See Also:
    
    XmlDataCursor.getValueTag(int...)
  - hasAttributes
```
boolean hasAttributes(int... index)
```
    The behavior is exactly like XmlDataCursor.hasAttributes(int...) except that an omitted index references the current-item value rather than the first and only item value.
    
    Specified by:
    
    hasAttributes in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content (or no index for the current-item)
    
    Returns:
    
    true if the specified item has attributes
    
    See Also:
    
    XmlDataCursor.hasAttributes(int...)
  - insertItemAfter
```
void insertItemAfter(java.lang.Object item)
```
    Inserts an item after the current-item in a repeating value. An item may be either a value or an indirect-item. The item must be compatible with the current-tag. When the current-item is an element or a group, this method behaves exactly like insertValueAfter(XmlDataContentTag, Object) and the item is treated like a value. If the current-tag is a substitution-tag, a properly formatted substitution-item must be provided. If the current-tag is an any-tag, a properly formatted any-item must be provided. This method is unlike insertValueAfter(XmlDataContentTag, Object) because that method creates an indirect-item from a value while this method expects an indirect-item that has already been created. This method differs from XmlDataCursor.insertItemAfter(Object, int) because an index is not required. When no index is specified the current-index is used.
    
    Parameters:
    
    item - the item to insert
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - insertItemBefore
```
void insertItemBefore(java.lang.Object item)
```
    Inserts an item before the current-item in a repeating value. An item may be either a value or an indirect-item. The item must be compatible with the current-tag. When the current-item is an element or a group, this method behaves exactly like insertValueBefore(XmlDataContentTag, Object) and the item is treated like a value. If the current-tag is a substitution-tag, a properly formatted substitution-item must be provided. If the current-tag is an any-tag, a properly formatted any-item must be provided. This method is unlike insertValueBefore(XmlDataContentTag, Object) because that method creates an indirect-item from a value while this method expects an indirect-item that has already been created. This method differs from XmlDataCursor.insertItemBefore(Object, int) because an index is not required. When no index is specified the current-index is used.
    
    Parameters:
    
    item - the item to insert
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - insertValueAfter
```
void insertValueAfter(XmlDataContentTag valueTag,
                      java.lang.Object value)
```
    Inserts a value and value-tag after the current-item. For element-tags and group-tags, this method inserts the value directly into the repeating value array and the value-tag is not used and may be null. If a tag is specified, it must match the current-tag. For substitution-tags and any-tags, an indirect-item is created from the value-tag and value and is inserted into the repeating values after the current-index. This method is an extension beyond XmlDataCursor.insertValueAfter(XmlDataContentTag, Object, int) because this method allows insertion without specifying an index (the current index is used). XmlDataCursor does not support insertAfter without an index.
    
    Parameters:
    
    valueTag - the tag used to construct the indirect-item (or null if not needed)
    
    value - the value used directly for elements and groups or the value used to construct the indirect-item
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - insertValueBefore
```
void insertValueBefore(XmlDataContentTag valueTag,
                       java.lang.Object value)
```
    Inserts a value and value-tag before the current-item. For element-tags and group-tags, this method inserts the value directly into the repeating value array and the value-tag is not used and may be null. If a tag is specified, it must match the current-tag. For substitution-tags and any-tags, an indirect-item is created from the value-tag and value and is inserted into the repeating value before the current-index . This method is an extension beyond XmlDataCursor.insertValueBefore(XmlDataContentTag, Object, int) because this method allows insert without specifying an index (the current index is used). XmlDataCursor does not support insertAfter without an index.
    
    Parameters:
    
    valueTag - the tag used to construct the indirect-item (or null if not needed)
    
    value - the value used directly for elements and groups or the value used to construct the indirect-item
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - isComplexValue
```
boolean isComplexValue(int... index)
```
    The behavior is similar to XmlDataCursor.isComplexValue(int...) except that an omitted index references the current-item.
    
    Specified by:
    
    isComplexValue in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content (or no index for the current-item)
    
    Returns:
    
    true if the specified item is a complex-value.
    
    Since:
    
    10.2
  - isEmpty
```
boolean isEmpty(int... index)
```
    The behavior is similar to XmlDataCursor.isEmpty(int...) except that an omitted index references the current-item.
    
    Specified by:
    
    isEmpty in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content (or no index for the current-item)
    
    Returns:
    
    true if the specified item is empty.
    
    Since:
    
    10.2
    
    See Also:
    
    XmlDataCursor.isEmpty(int...)
  - isGroupValue
```
boolean isGroupValue(int... index)
```
    The behavior is similar to XmlDataCursor.isGroupValue(int...) except that an omitted index references the current-item.
    
    Specified by:
    
    isGroupValue in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content (or no index for the current-item)
    
    Returns:
    
    true if the specified item is a group-value.
    
    Since:
    
    10.2
    
    See Also:
    
    XmlData.isGroupValue(Object)
  - isSimpleValue
```
boolean isSimpleValue(int... index)
```
    The behavior is similar to XmlDataCursor.isSimpleValue(int...) except that an omitted index references the current-item.
    
    Specified by:
    
    isSimpleValue in interface XmlDataCursor
    
    Parameters:
    
    index - the offset into repeating content (or no index for the current-item)
    
    Returns:
    
    true if the specified item is a simple-value.
    
    Since:
    
    10.2
  - isTop
```
boolean isTop()
```
    Determines if the XmlDataTreeCursor is positioned somewhere in the top level.
    
    Returns:
    
    true if the TreeCursor is position on a top-level entry
  - lastChild
```
boolean lastChild()
```
    Positions this cursor on the last child value of the current-value. Only group-values and complex-values with group-value content have children. If the current-value does not contain a child, (for example it contains a String or an empty IData), false is returned and cursor position remains unchanged. If the current-value has one or more children, the current-cursor is pushed onto a stack and a new cursor is positioned on the last child item. If it is necessary to obtain a cursor on empty content, consider method XmlDataCursor.getValueCursor(int...).
    
    Returns:
    
    true if the current-value has children
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is not positioned
  - lastItem
```
boolean lastItem()
```
    Positions this cursor on the last item. The current-item becomes the last tag-object-pair. If the last object is an array (repeating values), the cursor is positioned on the last item in the array by setting the current-index to the length of the array minus one.
    
    Returns:
    
    true if positioned to the last item.
  - nextInOrder
```
java.lang.Integer nextInOrder()
```
    Positions this cursor to the next in-order item. If there is no next item (at the current tree level), the cursor is positioned on the first item in the parent's next item. If the cursor is unpositioned, the cursor is positioned on the first item in the XmlData infoset tree.
    
    Returns:
    
    the change in tree depth (or null if there is no next in order)
  - nextItem
```
boolean nextItem()
```
    Positions this cursor on the next item. When more than one item is associated with the current-tag, the current-index is incremented. If the current-index is at the last repeating value or here are no repeating values, the cursor is positioned on the next tag-object-pair. If the new tag-value-pair contains repeating values, the current-index is set to zero. If there is no next item, the cursor remains unchanged.
    
    Returns:
    
    true if there is a next item
  - nextItem
```
boolean nextItem(XmlDataContentTag tag)
```
    Positions this cursor on the next item with the specified tag. The match is based on the current-tag. For example, if a substitution-item is present, the match comparison is performed against the substitution-tag. When repeating values are present and the search tag matches the current-tag, only the current-index is advanced and the current-position remains unchanged (unless already positioned on the last item of a repeating value). In order to find the next item based on the item's value-tag, which is probably more typical, use the nextValueTag(XmlDataContentTag) method. The tag match is based on the partial-name (it does not include the particle-id).
    
    Parameters:
    
    tag - the tag that is compared to item tags
    
    Returns:
    
    true if the item is found
  - nextValueTag
```
boolean nextValueTag(XmlDataContentTag tag)
```
    Positions this cursor on the next item with a value-tag that matches the search tag. For normal elements, this is the same as nextItem(XmlDataContentTag). However, for any-items and substitution-items, the nextItem()'s value-tag is used for comparison. This method is more easily used for a general search than the nextItem(XmlDataContentTag) method because the user can search without concern for whether the items are normal elements or indirect-items. The tag match is based on the partial-name (it does not include the particle-id).
    
    Parameters:
    
    tag - the tag which is compared to item value-tags
    
    Returns:
    
    true if the the next matching item is found
  - parent
```
boolean parent()
```
    Moves the XmlDataTreeCursor up one level by popping the top-level cursor from the internal stack of cursor. Returns false if already at the top level. Destroys the current cursor before moving up one level. If firstChild() or lastChild() had never been invoked on this cursor, the parent() method will always return false.
    
    Returns:
    
    true if the current-item has a parent. If already at top, no action is performed and false is returned.
  - previousInOrder
```
java.lang.Integer previousInOrder()
```
    Positions the cursor to the previous in-order item. If there is no previous item, the cursor is positioned on the last child in the parent's previous item. If the cursor is unpositioned, the cursor is positioned on the last item in the XmlData infoset tree.
    
    Returns:
    
    the change in tree depth (or null if there is no previous item)
  - previousItem
```
boolean previousItem()
```
    Positions this cursor on the previous item. When more than one item is associated with the current-tag, the current-index is decremented. If the current-index is already zero or here are no repeating values, the cursor is positioned on the previous tag-object pair. If the new tag-value-pair contains repeating values, the current-index is set to the index of the last value. If there are no repeating values, the current-index is set to zero. If there is no previous item, the cursor remains unchanged.
    
    Returns:
    
    true if there is a previous value
  - previousItem
```
boolean previousItem(XmlDataContentTag tag)
```
    Positions this cursor on the previous item with the specified tag. The match is based on the current-tag. For example, if a substitution-item is present, the match comparison is performed against the substitution-tag. When repeating values are present and the search tag matches the current-tag, only the current-index is advanced and the current-position remains unchanged (unless already positioned on the first item of a repeating value). In order to find the previous item based on the item's value-tag, which is probably more typical, use the previousValueTag(XmlDataContentTag) method. The tag match is based on the partial-name (it does not include the particle-id).
    
    Parameters:
    
    tag - the raw tag
    
    Returns:
    
    true if the item is found
  - previousValueTag
```
boolean previousValueTag(XmlDataContentTag tag)
```
    Positions this cursor the previous item with a value-tag that matches the search tag. For normal elements, this is the same as previousItem(XmlDataContentTag). However, for any-items and substitution-items the previousItem()'s value-tag is used for comparison. This method is more easily used for a general search than previousItem(XmlDataContentTag) because the user can search without concern for whether the items are normal elements or indirect-items. The tag match is based on the partial-name (it does not include the particle-id).
    
    Parameters:
    
    tag - the tag which is compared
    
    Returns:
    
    true if the the previous matching item is found
  - removeAttribute
```
boolean removeAttribute(XmlDataAttributeTag attribute,
                        int... index)
```
    Removes the specified attribute. The behavior is similar to XmlDataCursor.removeAttribute(XmlDataAttributeTag, int...) except that an omitted index references the current-item.
    
    Specified by:
    
    removeAttribute in interface XmlDataCursor
    
    Parameters:
    
    attribute - an XmlDataAttributeTag naming the attribute
    
    index - the offset of the element is a repeating value; an omitted index references the current-item
    
    Returns:
    
    true if the attribute existed
    
    See Also:
    
    XmlDataCursor.removeAttribute(XmlDataAttributeTag, int...)
  - setAnyTag
```
void setAnyTag(XmlDataContentTag tag,
               int... index)
```
    The behavior is similar to XmlDataCursor.setAnyTag(XmlDataContentTag, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setAnyTag in interface XmlDataCursor
    
    Parameters:
    
    tag - the tag used to set the ncName and namespace of the anyItem at the current cursor.
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    See Also:
    
    XmlDataCursor.setAnyTag(XmlDataContentTag, int...), XmlDataCursor.setAnyTag(XmlDataContentTag, int...)
  - setAttributes
```
void setAttributes(IData attributes,
                   int... index)
```
    The behavior is similar to XmlDataCursor.setAttributes(IData, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setAttributes in interface XmlDataCursor
    
    Parameters:
    
    attributes - an IData containing attribute-tag/value pairs.
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    See Also:
    
    XmlDataCursor.setAnyTag(XmlDataContentTag, int...), XmlDataCursor.setAttributes(IData, int...)
  - setAttributeValue
```
void setAttributeValue(XmlDataAttributeTag attribute,
                       java.lang.String value,
                       int... index)
```
    The behavior is similar to XmlDataCursor.setAttributeValue(XmlDataAttributeTag, String, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setAttributeValue in interface XmlDataCursor
    
    Parameters:
    
    attribute - an XmlDataAttributeTag
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    value - the value to set (must be a String)
    
    See Also:
    
    XmlDataCursor.setAnyTag(XmlDataContentTag, int...), XmlDataCursor.setAttributeValue(XmlDataAttributeTag, String, int...)
  - setContent
```
void setContent(java.lang.Object item,
                int... index)
```
    The behavior is exactly the same XmlDataCursor.setContent(java.lang.Object, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setContent in interface XmlDataCursor
    
    Parameters:
    
    item - the item content
    
    index - optional offset when repeating values are present
    
    See Also:
    
    XmlDataCursor.setContent(Object, int...)
  - setComplexValueContent
```
void setComplexValueContent(java.lang.Object item,
                            int... index)
```
    The behavior is exactly the same XmlDataCursor.setComplexValueContent(java.lang.Object, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setComplexValueContent in interface XmlDataCursor
    
    Parameters:
    
    item - the item content
    
    index - optional offset when repeating values are present
    
    See Also:
    
    XmlDataCursor.setComplexValueContent(Object, int...)
  - setIndex
```
void setIndex(int index)
```
    Establishes the current-item in repeating values. The cursor must be positioned. It is an error to set the index when the cursor is unpositioned.
    
    Parameters:
    
    index - the index specifying the current-item
    
    Throws:
    
    XmlDataException.UnpositionedCursor - when the cursor is unpositioned
    
    XmlDataException.IndexOutOfRange - the position in the list of repeating item values to be set. When index is not specified, the current-item is replaced.
  - setInstanceProp
```
void setInstanceProp(java.lang.String name,
                     java.lang.String value,
                     int... index)
```
    Description copied from interface: XmlDataCursor
    
    Sets an XML instance property (xsi attribute) on the current item. If the current item has repeating values, an index is required.
    
    Specified by:
    
    setInstanceProp in interface XmlDataCursor
    
    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
  - setItem
```
void setItem(java.lang.Object item,
             int... index)
```
    The behavior is similar to XmlDataCursor.setItem(java.lang.Object, int...) except that an omitted index always accesses the current-item rather than the first and only item.
    
    Specified by:
    
    setItem in interface XmlDataCursor
    
    Parameters:
    
    item - the item that replaces the current-item
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    See Also:
    
    XmlDataCursor, XmlDataCursor.setItem(Object, int...)
  - setNamespaceDecl
```
void setNamespaceDecl(java.lang.String prefix,
                      java.lang.String uri,
                      int... index)
```
    The behavior is similar to XmlDataCursor.setNamespaceDecl(String, String, int...) except that an omitted index always references the current-item rather the first and only item.
    
    Specified by:
    
    setNamespaceDecl in interface XmlDataCursor
    
    Parameters:
    
    prefix - the prefix for which the namespace is established
    
    uri - the uri assigned to the prefix
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    See Also:
    
    XmlDataCursor, XmlDataCursor.setNamespaceDecls(IData, int...)
  - setNamespaceDecls
```
void setNamespaceDecls(IData nsDecls,
                       int... index)
```
    The behavior is similar to XmlDataCursor.setNamespaceDecls(IData, int...) except that an omitted index always references the current-item rather the first and only item.
    
    Specified by:
    
    setNamespaceDecls in interface XmlDataCursor
    
    Parameters:
    
    nsDecls - an IData containing prefixes and URIs
    
    index - the position in the list of repeating values to be set. When index is not specified, the current-item is replaced.
    
    See Also:
    
    XmlDataCursor, XmlDataCursor.setNamespaceDecls(IData, int...)
  - setValue
```
void setValue(java.lang.Object item,
              int... index)
```
    The behavior is similar to XmlDataCursor.setValue(java.lang.Object, int...) except that an omitted index always accesses the current-item value rather than the first and only item value.
    
    Specified by:
    
    setValue in interface XmlDataCursor
    
    Parameters:
    
    item - the item value that replaces the current-item value
    
    index - the position in the list of repeating item values to be set. When index is not specified, the current-item value is replaced.
    
    See Also:
    
    XmlDataCursor.setValue(Object, int...)
  - setValueTag
```
void setValueTag(XmlDataContentTag tag,
                 int... index)
```
    The behavior is similar to XmlDataCursor.setValueTag(com.wm.xmldata.XmlDataContentTag, int...) except that an omitted index always accesses the current-item;s value-tag rather than the first and only item's value-tag.
    
    Specified by:
    
    setValueTag in interface XmlDataCursor
    
    Parameters:
    
    tag - the tag assigned to the current value
    
    index - the offset into the repeating value array
    
    See Also:
    
    XmlDataCursor.setValueTag(XmlDataContentTag, int...)
  - top
```
void top()
```
    Positions the TreeCursor on the top-level and destroys all intervening cursors.

Interface XmlDataTreeCursor

Overview

See glossary of terms

XmlDataTreeCursor method summary by functional group:

Glossary of terms:

Method Summary

Methods inherited from interface com.wm.xmldata.XmlDataCursor

Method Detail

currentIndex

deleteBackward

deleteForward

deleteItem

depth

firstChild

firstItem

getAnyTag

getAttributeNames

getAttributes

getAttributeValue

getComplexValueContent

getContent

getInstanceProp

getItem

getNamespaceDecl

getNamespaceDecls

getValue

getValueTag

hasAttributes

insertItemAfter

insertItemBefore

insertValueAfter

insertValueBefore

isComplexValue

isEmpty

isGroupValue

isSimpleValue

isTop

lastChild

lastItem

nextInOrder

nextItem

nextItem

nextValueTag

parent

previousInOrder

previousItem

previousItem

previousValueTag

removeAttribute

setAnyTag

setAttributes

setAttributeValue

setContent

setComplexValueContent

setIndex

setInstanceProp

setItem

setNamespaceDecl

setNamespaceDecls

setValue

setValueTag

top