public interface XmlDataCursor
An XMlDataCursor allows a program to navigate over the infoset of an XmlData-formatted IData document. The contents of XmlData-formated IData is a collection of tag/value pairs. Repeating tags (maxOccurs > 1) are represented as single tag/value pair with the value being a array.
The tag has a very specialized format. The tag is comprised of several components: a particle ID, a local name, and an optional namespace. There are four different types of tags depending on content model: - element tags - wildcard (any) tags - group tags - substitution group tags On a historical note, the legacy form of IData encoding for XML only had element tags.
The values also have specialized structures. - Element tags have String, String[], IData, IData[], or Object[] values. The values directly represent the corresponding XML content. - Wildcard (any) tags have values with a specialized structure that contains the NCName, Namespaces,and content for the instance value. This indirect representation allows Flow Maps to manipulate both wildcard name and content. - Substitution tags contain an IData that contains the actual instance tag/value pair. - Group tags contain nested complex content that mirrors the model groups of schema. Groups always contain an IData (or IData[] for repeating values).
Retrieving and updating the content of XmlData infoset is very similar to that of the legacy approach, but rather than obtaining an IDataCursor, the XmlData class is used to obtain an XmlDataCursor on an IData object. The XmlDataCursor is used to navigate through the element content. 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 element content. The attributes are not accessible as "peers" of the elements. Instead, there are explicit methods to get and set attributes values for the element at the current cursor position.
There are three different ways of accessing the content using the XmlDataCursor: object, value, or content. - For object access, the get(), set(), delete() access individual items in repeating value arrays, while getObject(), setObject(), and deleteObject() methods access the entire array. All of these methods directly access the content associated with the current item. - For plain Element tags, this behavior is similar to the behavior of the legacy approach. - For substitution group and wildcard (any) tags, the object-level methods access the specialized value structure. For example, when an 'any' tag object is present, getObject() returns the complete *any object. To simplify access, there is value access. The getValue() and setValue() methods can be used to access the values represented by the specialized wildcard (any) structure or the *substitution group structure. - When accessing normal element tag content. getValue() and setValue() behave exactly like get()and set(). Therefore, when a program is only interested in the tag/value at a logical level and is not concerned with the specialized representation, getValue() and setValue() are perfectly adequate and will typically be used. When using the value interface, there is still complexity because the value may be simple or complex, with or without attributes. The content methods, getContent() and setContent() 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.
The getTag() method returns the name of the current item. However, when using wildcard (any) or substitution groups, the current tag is a specialized tag, not the actual XML element name as present in the instance data. To obtain the actual tag, the getValueTag() and setValueTag() methods are used. These methods extract the tag from the specialized wildcard (any) or substitution group structure. For normal element tags, getValueTag() and setValueTag() behave exactly like getTag() and setTag().
XmlData
Modifier and Type | Method and Description |
---|---|
XmlDataCursor |
copyCursor() |
int |
count()
Returns the number of values stored at the current cursor position.
|
boolean |
delete(int... index)
Removes a single value from the list of values stored at the current cursor position.
|
boolean |
deleteObject()
Removes the entire current item (tag and and all values).
|
void |
destroy()
Releases any resources associated with the current cursor.
|
boolean |
first()
Positions the cursor at the first item.
|
boolean |
first(XmlDataContentTag tag)
Positions the cursor on the first occurrence of the specified tag and returns true.
|
java.lang.Object |
get(int... index)
Returns the item stored at the cursor.
|
XmlDataContentTag |
getAnyTag(int... index)
Returns the content tag present in the *any Document.
|
XmlDataAttributeTag[] |
getAttributeNames(int... index)
Returns a list of attribute names for the current element.
|
IData |
getAttributes(int... index)
Returns an IData list of attributes and values at the current cursor location.
|
java.lang.String |
getAttributeValue(XmlDataAttributeTag attribute,
int... index)
Returns the value of an attribute for the current item.
|
java.lang.Object |
getContent(int... index)
Returns the content associated with the current item.
|
java.lang.String |
getInstanceProp(java.lang.String name,
int... optionalIndex)
Retrieves the value of an instance (xsi) attribute specified for the current item.
|
XmlDataContentTag |
getKey()
Deprecated.
Use getTag instead.
|
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 item.
|
java.lang.Object |
getObject()
Returns the Object stored at the current cursor position.
|
XmlDataContentTag |
getTag()
Returns the tag of the current item.
|
java.lang.Object |
getValue(int... index)
Returns the value of the item at the current cursor position.
|
XmlDataElementTag |
getValueKey(int... index)
Deprecated.
Use getValueTag instead.
|
XmlDataElementTag |
getValueTag(int... index)
Returns the tag associated with the current item.
|
boolean |
hasAttributes(int... index)
Determines if the current entry has attributes.
|
void |
home()
The cursor becomes unpositioned as if newly created.
|
void |
insertAfter(java.lang.Object value,
int index)
Inserts a repeating value for the current tag in the array of recurring values after the specified index.
|
void |
insertAfter(XmlDataContentTag tag,
java.lang.Object value)
A content item (a tag and value pair) is inserted into the content after the current cursor position.
|
void |
insertBefore(java.lang.Object value,
int index)
Inserts a repeating value for the current tag in the array of repeating values before the specified index.
|
void |
insertBefore(XmlDataContentTag tag,
java.lang.Object value)
Inserts a content item (a tag and value pair) into the content before the current cursor position.
|
void |
insertValueAfter(XmlDataContentTag tag,
java.lang.Object value,
int index)
Inserts a repeating value with tag after the current tag.
|
void |
insertValueBefore(XmlDataContentTag tag,
java.lang.Object value,
int index)
Inserts a repeating value with tag before the current tag.
|
boolean |
isAny()
Determines if the cursor is positioned on an element wildcard item
|
boolean |
isGroup()
Determines if the cursor is positioned on a *group item
|
boolean |
isHome()
Indicates whether the cursor is unpositioned.
|
boolean |
isRecast()
Indicates if automatic recast is in effect
|
boolean |
isRepeating()
Indicates if the current item is a repeating tag.
|
boolean |
isSubstitution()
Determines if the cursor is positioned on a substitution head item
|
boolean |
last()
Positions the cursor at the last item.
|
boolean |
last(XmlDataContentTag tag)
Position the cursor on the last occurrence of the specified tag and return true.
|
XmlDataCursor |
newCursor(IData data)
Creates a new XmlDataCursor instance using the same factory that created another cursor.
|
boolean |
next()
Positions the cursor on the next content item.
|
boolean |
next(XmlDataContentTag tag)
Positions the cursor on the next occurrence of the specified tag and return true.
|
boolean |
previous()
Positions the cursor on the previous item.
|
boolean |
previous(XmlDataContentTag tag)
Positions the cursor on the previous occurrence of the specified tag and returns true.
|
void |
recast(boolean mode)
Indicates whether existing String[] or IData[] arrays should be automatically recast as Object[] when value of insert() or set() type does not match.
|
boolean |
removeAttribute(XmlDataAttributeTag attribute,
int... index)
Removes the specified attribute from the current element.
|
void |
set(java.lang.Object object,
int... index)
Sets the value stored at the current cursor position.
|
void |
setAttributes(IData attributes,
int... index)
Sets the attributes for the current element
|
void |
setAttributeValue(XmlDataAttributeTag attribute,
java.lang.String value,
int... index)
Sets the value for the specified attribute.
|
void |
setContent(java.lang.Object data,
int... index)
Replaces the value of the current element while preserving any original associated attributes.
|
void |
setInstanceProp(java.lang.String name,
java.lang.String value,
int... index)
Sets an XML instance property (xsi attribute) on the current item.
|
void |
setKey(XmlDataContentTag tag)
Deprecated.
Use setTag instead.
|
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.
|
void |
setTag(XmlDataContentTag tag)
Sets the tag of the current item.
|
void |
setValue(java.lang.Object object,
int... index)
Sets the value stored at the current cursor.
|
void |
setValueKey(XmlDataContentTag tag,
int... index)
Deprecated.
Use setValueTag()
|
void |
setValueTag(XmlDataContentTag tag,
int... index)
Sets the value at the current cursor.
|
XmlDataCursor copyCursor()
int count()
boolean delete(int... index)
index
- - optional offset (starting at zero) into the array if repeating content is presentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentboolean deleteObject()
XmlDataException.UnpositionedCursor
- - when cursor is not positionedvoid destroy()
boolean first()
boolean first(XmlDataContentTag tag)
tag
- - the XmlDataContentTag to be searchedjava.lang.Object get(int... index)
index
- - offset into the repeating content array (if repeating content is present)XmlDataContentTag getAnyTag(int... index)
index
- - offset into the repeating content array (if repeating content is present)TagConflict
- if the cursor is not positioned on an any tag.XmlDataAttributeTag[] getAttributeNames(int... index)
index
- - offset into the repeating content array (if repeating content is present)XmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentIData getAttributes(int... index)
index
- - the offset of the item if repeating values are presentjava.lang.String getAttributeValue(XmlDataAttributeTag attribute, int... index)
attribute
- - the tag of the attribute XmlDataAttributeTag)index
- - offset into the list of repeating values (starting at 0)XmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentjava.lang.Object getContent(int... index)
For an element, content is one of:
index
- - the index of the repeating valueXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentjava.lang.String getInstanceProp(java.lang.String name, int... optionalIndex)
name
- - the name of the xsi property (e.g. nil, type)optionalIndex
- - offset into the repeating valuesXmlDataContentTag getKey()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedjava.lang.String getNamespaceDecl(java.lang.String prefix, int... optionalIndex)
prefix
- - the prefixoptionalIndex
- - the namespace URI associated with the prefixIData getNamespaceDecls(int... optionalIndex)
optionalIndex
- - the index of the repeating value for which prefixes are returnedXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentjava.lang.Object getObject()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataContentTag getTag()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedjava.lang.Object getValue(int... index)
index
- - the offset into repeating contentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentXmlDataElementTag getValueKey(int... index)
index
- - the index offset into repeating contentXmlDataElementTag getValueTag(int... index)
index
- - the index of the repeating valueXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentboolean hasAttributes(int... index)
index
- - the index offset into repeating contentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existvoid home()
void insertAfter(XmlDataContentTag tag, java.lang.Object value)
tag
- - the tag of the tag/value pair to be inserted after the current cursor positionvalue
- - the value. Must be String, String[], IData, IData[], or Object[]void insertAfter(java.lang.Object value, int index)
value
- the value inserted (must be String or IData)index
- The insert position after which the item is insertedXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.UnsupportedType
- - when the inserted value is not an IData or String instanceXmlDataException.TagAndContentConflict
- - when the inserted value is incompatible with the current tag (for example inserting a String when
the current tag is a substitution group tag)void insertBefore(XmlDataContentTag tag, java.lang.Object value)
tag
- - the tag of the tag/value pair to be inserted before the current cursor positionvalue
- - the value. Must be String, String[], IData, IData[], or Object[].void insertBefore(java.lang.Object value, int index)
value
- - he value inserted (must be String or IData)index
- - the index position before which the value is insertedXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.UnsupportedType
- - when the inserted value is not an IData or String instanceXmlDataException.TagAndContentConflict
- - when the inserted content is incompatible with the current tag (for example inserting a String when
the current tag is a substitution group tag)void insertValueAfter(XmlDataContentTag tag, java.lang.Object value, int index)
tag
- - the name of the repeating contentvalue
- - the value of the repeating contentindex
- - the index of the repeating valueXmlDataException.TagAndContentConflict
- - when the value is inappropriate for the current tag (for substitution group values,
the content tag should be an XmlDataElementTag, and for *any wildcard values, the content tag should be an
XmDataElementTag or an XmlDataSubstitutionTagXmlDataException.IndexOutOfRange
- - when the indexed item does not existvoid insertValueBefore(XmlDataContentTag tag, java.lang.Object value, int index)
tag
- - the name of the repeating contentvalue
- - the value of the repeating contentindex
- - the index of the repeating valueXmlDataException.TagAndContentConflict
- - when the value is inappropriate for the current tag (for substitution group values,
the content tag should be an XmlDataElementTag, and for *any wildcard values, the content tag should be an
XmDataElementTag or an XmlDataSubstitutionTagXmlDataException.IndexOutOfRange
- - when the indexed item does not existboolean isAny()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedboolean isGroup()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedboolean isHome()
boolean isRecast()
boolean isRepeating()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedboolean isSubstitution()
XmlDataException.UnpositionedCursor
- - when the cursor is not positionedboolean last()
boolean last(XmlDataContentTag tag)
tag
- - the XmlDataContentTag to be searchedXmlDataCursor newCursor(IData data)
data
- - an existing IData whose cursor factory is used to create a new XmlDataCursor instance.boolean next()
boolean next(XmlDataContentTag tag)
tag
- = the tag to search forboolean previous()
boolean previous(XmlDataContentTag tag)
tag
- = the tag to search forboolean removeAttribute(XmlDataAttributeTag attribute, int... index)
attribute
- - an XmlDataATtrubteTag naming the attributeindex
- - the offset if the element is a repeating valueXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentvoid recast(boolean mode)
mode
- - true causes automatic recast; default is falsevoid set(java.lang.Object object, int... index)
It is always preferable to use of the XmlData methods to construct the value if it is not a String or String[]. Use createGroupValue() if the content does not contain attributes and the top-level group does not contain repeating values. Otherwise using createComplexValue().
When the current value is an array, it is an error if the index is not specified. 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, *group, and *any tags only accept an IData as value. If tag and content are not compatible, the TagAndContentConflict exception is thrown.
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.XmlDataException.UnsupportedType
- - when content other than a String or an IData instance is passedXmlDataException.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 positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentvoid setAttributes(IData attributes, int... index)
attributes
- - IData list of attributesindex
- - position in repeating valuevoid setAttributeValue(XmlDataAttributeTag attribute, java.lang.String value, int... index)
attribute
- - an XmlDqtaAttributeTag naming the attributevalue
- - the value to set (must be a String)index
- - optional offset into array of repeating valuesXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentXmlDataException.UnsupportedType
- - when a value other than a String is passedvoid setContent(java.lang.Object data, int... index)
data
- - the value that replaces the current contentindex
- - optional offset when repeating values are presentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentvoid setInstanceProp(java.lang.String name, java.lang.String value, int... index)
name
- - the name of the property(e.g., 'nil')value
- - the value of the property (e.g., 'true')index
- - the offset index into repeating contentvoid setKey(XmlDataContentTag tag)
tag
- is one of the XmlDataContentTags mentioned above.XmlDataException.UnpositionedCursor
- - when the cursor is not positionedvoid setNamespaceDecl(java.lang.String prefix, java.lang.String uri, int... index)
prefix
- - the prefixuri
- - the namespace URI.index
- - the offset index into repeating contentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentvoid setObject(java.lang.Object object)
object
- - the object to be stored at the current element.XmlDataException.UnpositionedCursor
- - when the cursor is not positionedvoid setNamespaceDecls(IData nsDecls, int... optionalIndex)
nsDecls
- - set the namespace declarations for the current itemoptionalIndex
- - the index of the repeating contentXmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentvoid setTag(XmlDataContentTag tag)
tag
- is one of the XmlDataContentTag mentioned above.XmlDataException.UnpositionedCursor
- - when the cursor is not positionedvoid setValue(java.lang.Object object, int... index)
object
- - the IData or String object that is assigned as the value of the current cursor position.index
- - the offset into the repeating values if the current item is an array.XmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentXmlDataException.FormatError
- - when the value of the current element is not compatible with the current, making it impossible to properly
set the current valuevoid setValueTag(XmlDataContentTag tag, int... index)
tag
- - the tag assigned to the current valueindex
- - the offset into the repeating value array.XmlDataException.UnpositionedCursor
- - when the cursor is not positionedXmlDataException.IndexOutOfRange
- - when the indexed item does not existXmlDataException.IndexRequired
- - when an index is not specified and repeating content is presentXmlDataException.FormatError
- - when the current element's value is not compatible with the current tag, making it impossible to properly
set the current valuevoid setValueKey(XmlDataContentTag tag, int... index)
tag
- - the tag assigned to the current valueindex
- - the offset into the repeating value array.