com.wm.data

Interface XmlDataCursor

public interface XmlDataCursor

XmlDataCursor defines the behavior for manipulating the XmlData infoset. There is only one implementation of this interface. The XmlData concrete class is used to obtain an XmlDataCursor on an IData object. XmlData infoset is a convention for encoding an XML infoset using IData. It is similar to the legacy XML encoding of past implementations, but is more comprehensive. When using XmlData, the namespace is an integral part of a qualified name rather than being defined externally. Also, there is explicit support for repeating model groups, substitution groups, and 'any' wildcards.

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().

See Also:

XmlData

Method Summary

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.

Method Detail

copyCursor

XmlDataCursor copyCursor()

Returns:

a copy of this cursor

count

int count()

Returns the number of values stored at the current cursor position. For a tag with repeating values (an array value), 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.

delete

boolean delete(int... index)

Removes a single value from the list of values stored at the current cursor position. If only one value is stored at the current cursor, then the entire current entry is deleted (both tag and value). If only one values is present, the index must be zero, or omitted. This true whether the current value is a single value or an array containing one value. If an index is specified, it must be less than the number of values present (zero is the index of the first item). An index of -1 is interpreted as the index of the last value (i.e. count() - 1). It is an error if the cursor is unpositioned, or the index is outside of the range of values, of if repeating values are present and an index is not specified. If one or more values remain after the specified value is deleted, false is returned and the cursor remains unpositioned. If the last or only remaining value at the current position is deleted, the entire entry is deleted. When this happens, the cursor is positioned on the next item, and true is returned. If there is no next item, the cursor is positioned on the previous item and false is returned. If there are no reaming items, the cursor is unpositioned. In other words, true is only returned when the cursor is moved forward to the next item. because all values have been removed from the current item. This behavior is similar to legacy IDataCursor delete() behavior.

Parameters:

index - - optional offset (starting at zero) into the array if repeating content is 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 content is present

deleteObject

boolean deleteObject()

Removes the entire current item (tag and and all values). If there are values following the current position, the cursor is positioned on the next item and true is returned. If there is no next value, the cursor is positioned on the previous item and false is returned. If there are no remaining values, 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; returns false if there is no next value after deletion; returns false if there are no remaining values

Throws:

XmlDataException.UnpositionedCursor - - when cursor is not positioned

destroy

void destroy()

Releases 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 item. Items are either elements, element wildcards, groups, or substitution heads. If there is no first item, the cursor remains unpositioned.

Returns:

true if there is a first item

first

boolean first(XmlDataContentTag tag)

Positions the cursor on the first occurrence of the specified tag and returns true. Otherwise, return false and leave the cursor unpositioned. For purposes of first(), the particle ID portion of the tag is 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 XmlDataContentTag to be searched

Returns:

true if item is found

get

java.lang.Object get(int... index)

Returns the item stored at the cursor. 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 value is a scalar and 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 nulls.

Parameters:

index - - offset into the repeating content array (if repeating content is present)

Returns:

the requested value

getAnyTag

XmlDataContentTag getAnyTag(int... index)

Returns the content tag present in the *any Document. The returned tag will be an instance of XmlDataElementTag or XmlDataSubstitutionTag. This is a very specialized method. More typically, getValueTag() is used to return the tag associated with the content. However, if the *any document references a substitution group, the getValueTag() method returns the element tag present in the substitution group. This specialized method returns the tag stored in the *any document which will be either be a element tag or a substitution tag. This method is used only when it in=s necessary to distinguish between substitution tags and element tags in a *any document. Normally, getTagValue() will be sufficient, and more general.

Parameters:

index - - offset into the repeating content array (if repeating content is present)

Returns:

The tag present in the *any Document.

Throws:

TagConflict - if the cursor is not positioned on an any tag.

getAttributeNames

XmlDataAttributeTag[] getAttributeNames(int... index)

Returns a list of attribute names for the current element. If the current element has repeating content, it is necessary to specify an index to select a specific member of the array

Parameters:

index - - offset into the repeating content array (if repeating content is present)

Returns:

An array of XmlDataAttributeTgas, 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 content is present

getAttributes

IData getAttributes(int... index)

Returns an IData list of attributes and values at the current cursor location. This is the content of the *attributes child. If the current item is not complex content, or does not have *attributes child, a null is returned.

Parameters:

index - - the offset of the item if repeating values are present

Returns:

An IData object containing the attributes. Returns null if the current item is not complex content or does not have an *attributes child.

getAttributeValue

java.lang.String getAttributeValue(XmlDataAttributeTag attribute,
                                   int... index)

Returns the value of an attribute for the current item. 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 content is present

getContent

java.lang.Object getContent(int... index)

Returns the content associated with the current item. If repeating values are present, an index must be specified. This method may be thought of as a logical operator that returns the content of the current cursor position regardless of the format: complex content, group content, or simple content) .

For an element, content is one of:

• the simple String content directly associated with the tag
• When there are no attributes or top-level groups, the IData content directly associated with the tag
• when attributes are present, the String content associated with the *simple tag
• When attributes are present, the highest level *group Document.

In other words, content always excludes any structure that might contain the *attributes Document.

Parameters:

index - - the index of the repeating 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 content is present

getInstanceProp

java.lang.String getInstanceProp(java.lang.String name,
                                 int... optionalIndex)

Retrieves the value of an instance (xsi) attribute specified for the current item. 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

getKey

XmlDataContentTag getKey()

Deprecated. Use getTag instead.

Returns the tag of the content item. 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

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 item.

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 item does not exist

XmlDataException.IndexRequired - - when an index is not specified and repeating content is present

getObject

java.lang.Object getObject()

Returns the Object stored at the current cursor position. If repeating values are present, then the entire array is returned. It is an error if the cursor is unpositioned. getObject will return a String, String[], IData, IData[], or Object[].

Returns:

object stored at current cursor position

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

getTag

XmlDataContentTag getTag()

Returns the tag of the current item. 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 (XmlDataElementTag, an XmlDataAnyTag, an XmlDataGroupTag, or XmlDataSubstitutionTag)

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

getValue

java.lang.Object getValue(int... index)

Returns the value of the item at the current cursor position. For items with tags other than XmlDataAnyTag or XmlDataSubstitutionTag, this method returns the same result as get(). For XmlDataAnyTags, the content stored in the *content field is returned. For XmlDataSubstitutionTags, the content of the substituted child is returned. In general terms, get() can be thought of as returning the physical content at a position, while getValue() returns the logical content (it essentially evaluates the *any or *substitution object to determine the value it contains). Most application programmers will find it simpler to use getValue() and setValue() rather than get() and set(). Get() and set() are used when detailed knowledge of the instance data is needed.

Parameters:

index - - the offset into repeating content

Returns:

The value stored at the current cursor position. It will be either complex content, group content, or a simple string.

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 content is present

getValueKey

XmlDataElementTag getValueKey(int... index)

Deprecated. Use getValueTag instead.

Returns the key associated with the current item.

Parameters:

index - - the index offset into repeating content

Returns:

an XmlDataElementTag

getValueTag

XmlDataElementTag getValueTag(int... index)

Returns the tag associated with the current item. If the current item is an element or a group, the current item tag is returned. The behavior is the same as that of getTag(). If the current item is an element wildcard, an XmlDataElemntTag is constructed from the ncname and namespace fields of the any content. If the current item is a substitution head, the XmlDataElementTag of the first and only content child is returned. If the content is repeating, the index is used to select a particular member of the array of repeating values.

Parameters:

index - - the index of the repeating value

Returns:

an instance of a subclass of XmlDataTag

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 content is present

hasAttributes

boolean hasAttributes(int... index)

Determines if the current entry 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 content

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.

insertAfter

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. The tag and content must be compatible.

Parameters:

tag - - the tag of the tag/value pair to be inserted after the current cursor position

value - - the value. Must be String, String[], IData, IData[], or Object[]

insertAfter

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. 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. When the current tag is a substitution tag, the value object must be an IData object in substitution format (e..g created by XmlData.createSubstitution). When the content tag is a *any wildcard tag, the value object must be an IData object in *any format (e.g. created by XmData.createAny).

Parameters:

value - the value inserted (must be String or IData)

index - The insert position after which the item is inserted

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

XmlDataException.IndexOutOfRange - - when the indexed item does not exist

XmlDataException.UnsupportedType - - when the inserted value is not an IData or String instance

XmlDataException.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)

insertBefore

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. The tag and content must be compatible.

Parameters:

tag - - the tag of the tag/value pair to be inserted before the current cursor position

value - - the value. Must be String, String[], IData, IData[], or Object[].

insertBefore

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. An index == array.length adds to end. An index of -1 inserts the values before the last value. When the current tag is a substitution tag, the value object must be an IData object in substitution format (e.g., created by XmlData.createSubstitution). When the current tag is a *any wildcard tag, the value object must be an IData object in *any format (e.g., created by XmData.createAny).

Parameters:

value - - he value inserted (must be String or IData)

index - - the index position before which the value is inserted

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

XmlDataException.IndexOutOfRange - - when the indexed item does not exist

XmlDataException.UnsupportedType - - when the inserted value is not an IData or String instance

XmlDataException.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)

insertValueAfter

void insertValueAfter(XmlDataContentTag tag,
                      java.lang.Object value,
                      int index)

Inserts a repeating value with tag after the current tag. 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. The primary use for this method is for updating repeating content for *any wildcards or substitution groups. The tag is necessary when updating such content because each instance may have a unique tag. Normal element content has the same tag for all repeating values.

Parameters:

tag - - the name of the repeating content

value - - the value of the repeating content

index - - the index of the repeating value

Throws:

XmlDataException.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 XmlDataSubstitutionTag

XmlDataException.IndexOutOfRange - - when the indexed item does not exist

insertValueBefore

void insertValueBefore(XmlDataContentTag tag,
                       java.lang.Object value,
                       int index)

Inserts a repeating value with tag before the current tag. 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. The primary use for this method is to update repeating content for *any wildcards or substitution groups. The tag is necessary when updating such content because each instance may have a unique tag. Normal element content has the same tag for all repeating values.

Parameters:

tag - - the name of the repeating content

value - - the value of the repeating content

index - - the index of the repeating value

Throws:

XmlDataException.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 XmlDataSubstitutionTag

XmlDataException.IndexOutOfRange - - when the indexed item does not exist

isAny

boolean isAny()

Determines if the cursor is positioned on an element wildcard item

Returns:

true if the current item has an XmlDataAnyTag tag

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

isGroup

boolean isGroup()

Determines if the cursor is positioned on a *group item

Returns:

true if the current item has an XmlDataGroupTag tag

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

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()

Indicates if the current item is a repeating tag. Returns true if the value is an array (by convention, zero-length arrays are not allowed). Returns false if the value is not an array.

Returns:

true if item contains a repeating value

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

isSubstitution

boolean isSubstitution()

Determines if the cursor is positioned on a substitution head item

Returns:

true if the current item has an XmlDataSubstitutionTag tag

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

last

boolean last()

Positions the cursor at the last item. Items are either elements, element wildcards, groups, or substitution heads. If there is no last item, the cursor remains unpositioned.

Returns:

true if there is a last item

last

boolean last(XmlDataContentTag tag)

Position the cursor on the last occurrence of the specified tag and return true. Otherwise return false and leave the cursor unpositioned. For purpose of last, the particle IDs of the input tag and content items are ignored so as to find the last occurrence. 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 item is found

newCursor

XmlDataCursor newCursor(IData data)

Creates a new XmlDataCursor instance using the same factory that created another cursor.

Parameters:

data - - an existing IData whose cursor factory is used to create a new XmlDataCursor instance.

Returns:

a new XmlDataCursor instance

next

boolean next()

Positions the cursor on the next content item. Returns false if there is no next item and the cursor remained unchanged.

Returns:

true if there is a next item

next

boolean next(XmlDataContentTag tag)

Positions the cursor on the next occurrence of the specified tag and return true. Otherwise return false and leave the cursor unpositioned. For purpose of next, the particle IDs of the input tag and content items are ignored so as to find the next occurrence. It is as if the next() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.

Parameters:

tag - = the tag to search for

Returns:

true if item is found

previous

boolean previous()

Positions the cursor on the previous item. 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 occurrence of the specified tag and returns true. Otherwise return false and leave the cursor unpositioned. For purpose of previous, the particle IDs of the input tag and content items are ignored so as to find the previous occurrence. It is as if the last() method is invoked until the condition tag.getPartialName().equals(cursor.getTag().getPartialName()) is satisfied.

Parameters:

tag - = the tag to search for

Returns:

true if item is found

removeAttribute

boolean removeAttribute(XmlDataAttributeTag attribute,
                        int... index)

Removes the specified attribute from the current element. It is an error if the cursor is not positioned on an element item. It is an error if repeating content is present and an index is not provided.

Parameters:

attribute - - an XmlDataATtrubteTag 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 content is present

recast

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.

Parameters:

mode - - true causes automatic recast; default is false

set

void set(java.lang.Object object,
         int... index)

Sets the value stored at the current cursor position. It is an error if the cursor is unpositioned. The value must be a String or an IData. Repeating values are stored internally as arrays. 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[], as appropriate. For non-directed conversion, repeating values are always stored as Object[]s.

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.

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 content is present

setAttributes

void setAttributes(IData attributes,
                   int... index)

Sets the attributes for the current element

Parameters:

attributes - - IData list of attributes

index - - position in repeating value

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 XmlDqtaAttributeTag 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 content is present

XmlDataException.UnsupportedType - - when a value other than a String is passed

setContent

void setContent(java.lang.Object data,
                int... index)

Replaces the value of the current element while preserving any original associated attributes. If the current element has repeating values, then the value of the specified entry in the array is replaced but the original attributes are preserved. 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:

data - - the value that replaces the current content

index - - optional offset when repeating values are 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 content is 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 content

setKey

void setKey(XmlDataContentTag tag)

Deprecated. Use setTag instead.

Sets the tag of the current item. The tag must be either an XmlDataElementTag, an XmlDataAnyTag, an XmlDataGroupTag, or an XmlDataSubsttutionTag. The tag must be compatible with the current content. 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

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 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 content is present

setObject

void setObject(java.lang.Object object)

Sets the object stored at the current cursor position. It is an error if the cursor is unpositioned. The value must be a String, an IData, a String[], an IData[], or an Object[].

Parameters:

object - - the object 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 - - set the namespace declarations for the current item

optionalIndex - - the index of the repeating 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 content is present

setTag

void setTag(XmlDataContentTag tag)

Sets the tag of the current item. The tag must be either an XmlDataElementTag, an XmlDataAnyTag, an XmlDataGroupTag, or an XmlDataSubstitutionTag. The tag must be compatible with the current content. 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 XmlDataContentTag mentioned above.

Throws:

XmlDataException.UnpositionedCursor - - when the cursor is not positioned

setValue

void setValue(java.lang.Object object,
              int... index)

Sets the value stored at the current cursor. If the current item is an XmlDataElementTag or an XmlDataGroupTag, the object is stored directly. For XmlDataElementTags, the object must be a String or IData object. For XmlDataGroupTags, it must be an IData. If there is existing content and it is an array, an index must be specified. For an XmlDataAnyTag, the object is stored indirectly; it is stored in the *content field of the any object. For an XmlDataSubstitutionTag, the object is stored indirectly; it is stored as the value of the single child which\ contains a /value pair representing the substituted content.

Parameters:

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.

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 content is present

XmlDataException.FormatError - - when the value of the current element is not compatible with the current, making it impossible to properly set the current value

setValueTag

void setValueTag(XmlDataContentTag tag,
                 int... index)

Sets the value at the current cursor. If the current item is an element or a group , the new is stored directly in the /value pair. In this case, setValue() behaves exactly like set(). However, if the current item is an any object, the tag is stored in the *ncName and *namespace fields of the any object. The *any tag remains unchanged. If the current item is a substitution object, the tag is stored as he tag of the first and only child in the substitution object. 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 content is 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

setValueKey

void setValueKey(XmlDataContentTag tag,
                 int... index)

Deprecated. Use setValueTag()

Sets the key of the value of the current cursor. If the current item key is an element or a *group, the key is stored directly in the key/value pair. If the current item is an any object, the key is stored in the *ncName and *namespace fields of the any object. If the current item is a substitution object, the key is stored as the key of the first and only child in the substitution object. 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.