com.wm.xmldata

Class XmlDataMap

java.lang.Object

com.wm.xmldata.XmlDataMap

public class XmlDataMap
extends java.lang.Object

The XmlDataMap class allows direct manipulation of fields in an XmlData object without the use of cursors. Instead, an NSRecord is used as a template to provide positional context. In this regard, the facilities of XmlDataMap loosely emulate those of Flow Map operations such as set and drop. An XmlDataMap is created using the XmlDataMap create method, specifying a source XmlData instance, and a reference to an NSRecord that maps (describes) the data. It is possible to map nested children as well. Not all functions of the XmlDataCursor are implemented for maps. Primarily, the get, set, drop, and map families of methods are provided. In order to perform other operations, obtain an XmlDataCursor for the desired item getXmlDataCursorAt(XmlDataContentTag).

Method Summary

Modifier and Type	Method and Description
static XmlDataMap	create(IData data, NSRecord record) Creates an XmlDataMap using the specified input data and NSRecord.
boolean	drop(XmlDataContentTag memberTag, int... index) Removes the item at the specified tag and index.
boolean	dropObject(XmlDataContentTag memberTag) Removes the object at the specified tag.
java.lang.Object	getContent(XmlDataContentTag memberTag, int... index) Returns the content at the specified tag as if the XmlDataCursor.getContent(int...) method was invoked.
IData	getData() Returns the data mapped by this XmlDataMap.
XmlNamespaceMap	getDefaultNamespaceMap() Gets the default XnlNamespaceMap.
NSField	getDefinedField(XmlDataContentTag tag) Retrieves the NSField corresponding to the specified tag.
NSField	getField(XmlDataContentTag tag) Retrieves the NSField corresponding to the specified tag.
java.lang.Object	getItem(java.lang.String path) Gets the item specified by a String path.
java.lang.Object	getItem(XmlDataContentTag[] tags) Returns the item specified by a path using a list of XmlDataContentTags.
java.lang.Object	getItem(XmlDataContentTag memberTag, int... index) Retrieves a single item stored at the specified tag.
java.lang.Object	getObject(XmlDataContentTag memberTag) Retrieves the entire object stored at the specified tag.
XmlDataContentTag	getParentTag() Returns the tag that is currently mapped in the parent.
XmlDataContentTag	getParentValueTag() Returns the tag associated with the currently mapped parent.
XmlDataContentTag[]	getPath() Creates an XmlData path (an array of XmlDataContentTags) from the current map.
java.lang.String	getPathAsString() Returns the path as a String using the default namespace map.
java.lang.String	getPathAsStringWithMap() Returns part as a String (including the namespace prefixes) using the default Namespace map.
java.lang.Object	getValue(java.lang.String path) Gets the value of an item specified using a String path.
java.lang.Object	getValue(XmlDataContentTag[] tags) Gets the value of an item using a list of XmlDataContentTags as the path.
java.lang.Object	getValue(XmlDataContentTag memberTag, int... index) Returns the value at the specified tag.
XmlDataContentTag	getValueTag(XmlDataContentTag memberTag, int... index) Retrieves the value-tag from the item with the specified tag.
XmlDataCursor	getXmlDataCursorAt(XmlDataContentTag memberTag) Returns an XmlDataCursor positioned on the specified tag.
void	insertItemAfter(XmlDataContentTag memberTag, java.lang.Object item, int index) Inserts an item into the repeating value list at the specified tag.
void	insertItemBefore(XmlDataContentTag memberTag, java.lang.Object item, int index) Inserts an item into a repeating value list at the specified tag.
void	insertValueAndTagAfter(XmlDataContentTag memberTag, XmlDataElementTag valueTag, java.lang.Object value, int index) Inserts a value and value-tag into a repeating value list at the specified tag, If the specified tag is an any-tag or a substitution-tag, the appropriate indirect-item is created from the value and value-tag and inserted into the array at the specified tag and index.
void	insertValueAndTagBefore(XmlDataContentTag memberTag, XmlDataElementTag valueTag, java.lang.Object value, int index) Inserts a value and value-tag into a repeating value list at the specified tag.
boolean	isChildMapable(XmlDataContentTag memberTag) Indicates whether the specified field is mappable.
int	map(java.lang.String path) Performs a nested map by navigating from the current map to the specified child along a path specified by a String.
int	map(XmlDataContentTag[] tags) Performs a nested map for each tag in the list, effectively navigating to a lower level in the tree.
boolean	map(XmlDataContentTag memberTag, int... index) Creates a new XmlDataMap of the specified child, pushing the current map onto an internal stack.
boolean	map(XmlDataContentTag memberTag, XmlDataContentTag qualifierTag, int... index) Creates a new XmlDataMap of the specified child (memberTag), pushing the current map onto an internal stack.
int	mapExisting(boolean allowPartial, java.lang.String path) Only maps a field that exists in the instance.
int	mapExisting(boolean allowPartial, XmlDataContentTag[] tags) Performs a nested map for each tag in the list, effectively navigating to a lower level in the tree.
boolean	mapExisting(XmlDataContentTag memberTag, int... index) Performs a map of the specified tag and index if it exists.
boolean	mapExisting(XmlDataContentTag memberTag, XmlDataContentTag qualifierTag, int... index) Performs a map of the specified tag, index, and indirect-qualifier.
boolean	parent(int... num) Returns to a parent map by popping the current XMlDataMap from the internal stack.
void	setDefaultNamespaceMap(java.lang.String pairs) Sets the namespace map used to resolve namespace-qualified String paths.
void	setDefaultNamespaceMap(XmlNamespaceMap map) Sets the namespace map used by namespace-qualified String paths.
void	setItem(java.lang.String path, java.lang.Object value) Performs a setItem() of formatted value by navigating from the current map to the specified child along a path specified by a String.
void	setItem(XmlDataContentTag[] tags, java.lang.Object value) Performs a setItem() of a formatted value by navigating from the current map to the specified child along a path specified by a list of content tags.
void	setItem(XmlDataContentTag memberTag, java.lang.Object value, int... index) Sets the item associated with the specified member tag.
void	setObject(XmlDataContentTag memberTag, java.lang.Object obj) Sets the object at the specified tag.
void	setValue(java.lang.String path, java.lang.Object value) Performs a setValue() by navigating from the current map to the specified child along a map-path specified as a String.
void	setValue(XmlDataContentTag[] tags, java.lang.Object value) Performs a setValue() by navigating from the current map to the specified child along a map-path specified by a list of content-tags.
void	setValue(XmlDataContentTag memberTag, java.lang.Object value, int... index) Sets the value stored at the specified tag.
void	setValueAndTag(XmlDataContentTag memberTag, XmlDataContentTag valueTag, java.lang.Object value, int... index) Sets the value and value-tag of the specified indirect-item.
void	setValueTag(XmlDataContentTag memberTag, XmlDataElementTag valueTag, int... index) Sets the value-tag of the specified indirect-item.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static XmlDataMap create(IData data,
                                NSRecord record)

Creates an XmlDataMap using the specified input data and NSRecord.

Parameters:

data - an IData in XmlData format

record - an NSRecord

Returns:

a new XmlDataMap

Throws:

XmlDataException.ImproperDocumentType - the NSRecord is not an XmlData record or does not content any content

drop

public boolean drop(XmlDataContentTag memberTag,
                    int... index)

Removes the item at the specified tag and index. If repeating values are present, an index must be specified. If the item is a scalar the index must be zero or not specified.

Parameters:

memberTag - the content-tag to be removed

index - the offset into repeating values. If the last repeating value is removed, the entire entry (including the tag) is removed.

Returns:

true if the tag was present and the specified item was removed; false if the tag was not present

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

dropObject

public boolean dropObject(XmlDataContentTag memberTag)

Removes the object at the specified tag. The entire object is removed whether it is a scalar or an array.

Parameters:

memberTag - the content-tag of the item to be removed

Returns:

true if the tag was present and the specified object was removed; false if the tag was not present

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

getItem

public java.lang.Object getItem(XmlDataContentTag memberTag,
                                int... index)

Retrieves a single item stored at the specified tag. A null is returned if the tag is not present. If repeating values are present, an index must be specified. If an indirect item is present, the entire any-item or substitution-item is returned. Use the getValue(XmlDataContentTag, int...) method to obtain the value of an indirect-item.

Parameters:

memberTag - the tag for which data is retrieved. This must be an element-tag, a substitution-tag, an any-tag, or a group-tag.

index - the index if repeating items are present

Returns:

the value or null if the tag is not found

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

getItem

public java.lang.Object getItem(XmlDataContentTag[] tags)

Returns the item specified by a path using a list of XmlDataContentTags.

Parameters:

tags - the list of XmlDataContentTags

Returns:

the value stored at the path item

getItem

public java.lang.Object getItem(java.lang.String path)

Gets the item specified by a String path.

Parameters:

path - the path

Returns:

the item stored at the specified path

getContent

public java.lang.Object getContent(XmlDataContentTag memberTag,
                                   int... index)

Returns the content at the specified tag as if the XmlDataCursor.getContent(int...) method was invoked. For complex-values, content does not include attributes.

Parameters:

memberTag - the tag of the member item for which content is returned

index - the offset into the list of repeating values

Returns:

the value at the specified tag; null if the tag is not found

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.FormatError - when the value is not in complex-value format

getData

public IData getData()

Returns the data mapped by this XmlDataMap. Normally this will be the same value passed into the create() method. However, if a null value is passed into create, this method will create a new IData instance in the appropriate XmlData format.

Returns:

the IData or null if none has been created.

getDefaultNamespaceMap

public XmlNamespaceMap getDefaultNamespaceMap()

Gets the default XnlNamespaceMap.

Returns:

XmlNamespaceMap

getDefinedField

public NSField getDefinedField(XmlDataContentTag tag)

Retrieves the NSField corresponding to the specified tag. Returns null if it does not exist.

Parameters:

tag - the XmlDataContentTag identifying the NSField to retrieve

Returns:

the identified NSField

getField

public NSField getField(XmlDataContentTag tag)

Retrieves the NSField corresponding to the specified tag.

Parameters:

tag - the XmlDataContentTag identifying the NSField to retrieve

Returns:

the identified NSField

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

getParentValueTag

public XmlDataContentTag getParentValueTag()

Returns the tag associated with the currently mapped parent. Normally, this is the same name as the parent that is mapped. However, if the parent is a substitution tag or an any tag, the returned tag is the actual tag that is present in the instance data.

Returns:

the tag present in the instance data.

getParentTag

public XmlDataContentTag getParentTag()

Returns the tag that is currently mapped in the parent.

Returns:

XmlDataContentTag

getObject

public java.lang.Object getObject(XmlDataContentTag memberTag)

Retrieves the entire object stored at the specified tag. A null is returned if the tag is not present. If repeating values are present, the entire array is returned.

Parameters:

memberTag - the tag for which data is retrieved. This must be an element-tag, a substitution-tag, an any-tag, or a group-tag.

Returns:

the value or null if the tag is not found.

Throws:

XmlDataException.UnknownField - the specified tag is not defined in the mapping record

getPath

public XmlDataContentTag[] getPath()

Creates an XmlData path (an array of XmlDataContentTags) from the current map. If no children have been mapped at the time of invocation, an empty array is returned.

Returns:

an XmlDataContentTag[] of indicating the path from the root to the current child

getPathAsString

public java.lang.String getPathAsString()

Returns the path as a String using the default namespace map.

Returns:

the path specified as a String

getPathAsStringWithMap

public java.lang.String getPathAsStringWithMap()

Returns part as a String (including the namespace prefixes) using the default Namespace map.

Returns:

path as String with a preamble map

getValue

public java.lang.Object getValue(XmlDataContentTag memberTag,
                                 int... index)

Returns the value at the specified tag. The value is returned as if the XmlDataCursor getValue() method was invoked. Consequently, the effective value of substitution-items and any-items is transparently extracted from the indirect-item stored at the tag. Use the getItem() method to retrieve the entire item rather than the effective value of the any-item. For element-tags and group-tags, getItem() and getValue() behave identically.

Parameters:

memberTag - the tag for which the value is returned.

index - the offset into the list of repeating values.

Returns:

the value at the specified tag; null if the tag is not found

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

getValue

public java.lang.Object getValue(XmlDataContentTag[] tags)

Gets the value of an item using a list of XmlDataContentTags as the path.

Parameters:

tags - the list of XmlDataContentTags

Returns:

the value of the item

getValue

public java.lang.Object getValue(java.lang.String path)

Gets the value of an item specified using a String path.

Parameters:

path - the patch

Returns:

the value of the path item

getValueTag

public XmlDataContentTag getValueTag(XmlDataContentTag memberTag,
                                     int... index)

Retrieves the value-tag from the item with the specified tag. When the specified tag is an element-tag or a group-tag, the value-tag is the same as the specified tag. When the specified tag is an any-tag or a substitution-tag, the value-tag of the associated indirect-item is returned.

Parameters:

memberTag - the content-tag for which the search is performed

index - the offset into the list of repeating values

Returns:

the value-tag of the specified item

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the the specified tag is not defined in the mapping record

getXmlDataCursorAt

public XmlDataCursor getXmlDataCursorAt(XmlDataContentTag memberTag)

Returns an XmlDataCursor positioned on the specified tag. If the tag is not present, the cursor is unpositioned. Note that the cursor is obtained from the currently mapped IData. If the specified tag exists in the mapped IData, a positioned cursor is returned regardless of the type of data stored at the tag. Contrast this behavior with map() which can only succeed if the specified tag contains complex content. If this Map is in effect for a parent that does not yet exist (i.e., a non-existing field was mapped from the parent), a null is returned.

Parameters:

memberTag - the XmlDataContentTag

Returns:

a positioned cursor if tag is present; an unpositioned cursor if tag doesn't exist; null if parent not yet created

insertItemAfter

public void insertItemAfter(XmlDataContentTag memberTag,
                            java.lang.Object item,
                            int index)

Inserts an item into the repeating value list at the specified tag. Because the item is new, in must be a properly formatted item and must be compatible with the memberTag (e.g. if the memberTag is an any-tag, the item must be an any-item, if the memberTag is an element-tag the item may be any value, etc.)

Parameters:

memberTag - the tag at which a repeating value is inserted

item - the item that is inserted

index - the offset into the repeating values list

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - if the specified field is not defined in the current map.

insertItemBefore

public void insertItemBefore(XmlDataContentTag memberTag,
                             java.lang.Object item,
                             int index)

Inserts an item into a repeating value list at the specified tag. Because the item is new, in must be a properly formatted item and must be compatible with the memberTag (e.g. if the memberTag is an any-tag, the item must be an any-item, if the memberTag is an element-tag the item may be any value, etc.)

Parameters:

memberTag - the tag at which a repeating value is inserted

item - the item that is inserted

index - the offset into the list

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - if the specified field is not defined in the current map

insertValueAndTagAfter

public void insertValueAndTagAfter(XmlDataContentTag memberTag,
                                   XmlDataElementTag valueTag,
                                   java.lang.Object value,
                                   int index)

Inserts a value and value-tag into a repeating value list at the specified tag, If the specified tag is an any-tag or a substitution-tag, the appropriate indirect-item is created from the value and value-tag and inserted into the array at the specified tag and index. For element-tags and group-tags, the value-tag must be identical to the specified tag or specified as null.

Parameters:

memberTag - the tag for which a repeating value is inserted

value - the value inserted

valueTag - the tag of the value

index - the offset into the repeating value list

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - the specified tag is not defined in the mapping record

insertValueAndTagBefore

public void insertValueAndTagBefore(XmlDataContentTag memberTag,
                                    XmlDataElementTag valueTag,
                                    java.lang.Object value,
                                    int index)

Inserts a value and value-tag into a repeating value list at the specified tag. If the specified tag is an any-tag or a substitution-tag, the appropriate indirect-item is created from the value and value-tag and inserted into the array at the specified tag and index. For element-tags and group-tags, the value-tag must be identical to the specified tag or specified as null.

Parameters:

memberTag - the tag for which a repeating value is inserted

valueTag - the tag of the value

value - the value inserted

index - the offset into the list of repeating values

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

isChildMapable

public boolean isChildMapable(XmlDataContentTag memberTag)

Indicates whether the specified field is mappable. This is based on the field definition in the associated NSRecord, not the actual content.

Parameters:

memberTag - the tag to be tested

Returns:

true if field is mappable

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

map

public boolean map(XmlDataContentTag memberTag,
                   int... index)

Creates a new XmlDataMap of the specified child, pushing the current map onto an internal stack. The map succeeds even if the mapped tag is not yet present in the input, thus making it possible to create a new item and add members to it.

Parameters:

memberTag - the tag of the child that is mapped

index - the offset into repeating child values; if the content tgg has an index, this value overrides it.

Returns:

true if the mapped child already exists in the pipeline, false if it has not yet been created

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.ImproperDocumentType - the NSRecord is not an XmlData record or does not content any content

map

public boolean map(XmlDataContentTag memberTag,
                   XmlDataContentTag qualifierTag,
                   int... index)

Creates a new XmlDataMap of the specified child (memberTag), pushing the current map onto an internal stack. The map succeeds even if the memberTag is not yet present in the mapped group, thus making it possible to create a new member and manipulate it. If the child is an indirect-item and does not yet exist, an indirect-qualifier must be specified.

Parameters:

memberTag - the tag of the child that is mapped

qualifierTag - the indirect-qualifier for the indirect-item

index - the offset into repeating child values; if the content tag has an index, this value overrides it

Returns:

true if the mapped child already exists in the pipeline, false if it has not yet been created

map

public int map(XmlDataContentTag[] tags)

Performs a nested map for each tag in the list, effectively navigating to a lower level in the tree.

Parameters:

tags - a list of XmlDataContentTags

Returns:

the number of levels through which the map has descended

map

public int map(java.lang.String path)

Performs a nested map by navigating from the current map to the specified child along a path specified by a String. If any of the tags correspond to repeating values, an indexed form of the path String must be used. If the path string uses namespace-qualified tags, the path must include the { ... } namespace preamble, or the default namespace may must be set using the setDefaultNamespaceMap.

Parameters:

path - the path specified as a String

Returns:

the number of levels through which the map descends

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.ImproperDocumentType - the NSRecord is not an XmlData record or does not content any content

mapExisting

public boolean mapExisting(XmlDataContentTag memberTag,
                           int... index)

Performs a map of the specified tag and index if it exists. Returns true if the mapped tag exists in the instance.

Parameters:

memberTag - the tag to map

index - the offset into the list if repeating values

Returns:

true if the item exists

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.ImproperDocumentType - the NSRecord is not an XmlData record or does not content any content

mapExisting

public boolean mapExisting(XmlDataContentTag memberTag,
                           XmlDataContentTag qualifierTag,
                           int... index)

Performs a map of the specified tag, index, and indirect-qualifier.

Parameters:

memberTag - the tag to map

qualifierTag - the indirect-qualifier

index - the index

Returns:

true if the item exists

mapExisting

public int mapExisting(boolean allowPartial,
                       XmlDataContentTag[] tags)

Performs a nested map for each tag in the list, effectively navigating to a lower level in the tree. The mapping may be partial if allowPartial is true. When allowPartial is true, the returned integer indicates the number of existing steps that were mapped.

Parameters:

tags - a list of XmlDataContentTags

allowPartial - a value of true indicates that mapping may succeed if part of the path exists. A value of false indicates that entire path must exist

Returns:

the number of levels through which the map has descended.

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.ImproperDocumentType - the NSRecord is not an XmlData record or does not content any content

mapExisting

public int mapExisting(boolean allowPartial,
                       java.lang.String path)

Only maps a field that exists in the instance. This method produces the same results as mapExisting(boolean, XmlDataContentTag[]) but allows the path to be expressed in String form.

Parameters:

allowPartial - indicates that a partially existing path is acceptable

path - the path expressed as a String

Returns:

the number of steps mapped

parent

public boolean parent(int... num)

Returns to a parent map by popping the current XMlDataMap from the internal stack.

Parameters:

num - the number of levels to pop. The default is 1.

Returns:

true if the number of specified levels has been popped.

setItem

public void setItem(XmlDataContentTag memberTag,
                    java.lang.Object value,
                    int... index)

Sets the item associated with the specified member tag. When repeating values are present at the member tag, an index must be specified. For element-tags and group-tags the values are the typical values: IDatas and Strings. setItem() and setValue() behave identically for group-tags and element-tag. For substitution-tags, the value must be a substitution-tem such as the object constructed using the convenience method XmlData.createSubstitutionItem(XmlDataElementTag, Object). For any-tags, the value must be an any-item, such as the object constructed using the convenience method XmlData.createAnyItem(XmlDataContentTag, Object).

Parameters:

memberTag - the tag for which a formatted values is set

value - the formatted value assigned (must match the tag usage)

index - offset into the repeating value list

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

setItem

public void setItem(XmlDataContentTag[] tags,
                    java.lang.Object value)

Performs a setItem() of a formatted value by navigating from the current map to the specified child along a path specified by a list of content tags. If any of the tags correspond to repeating values, an indexed form of the content tag must be used.

Parameters:

tags - the list of tags that defines the path to the item that is set

value - the formatted value that is set

setItem

public void setItem(java.lang.String path,
                    java.lang.Object value)

Performs a setItem() of formatted value by navigating from the current map to the specified child along a path specified by a String. If any of the tags correspond to repeating values, an indexed form of the path String must be used. If the path string uses namespace-qualified tags, the path must include the { ... } namespace preamble, or the default namespace must be set using the setDefaultNamespaceMap.

Parameters:

path - the String form of the path to the item that is set

value - the formatted value that is set

setDefaultNamespaceMap

public void setDefaultNamespaceMap(XmlNamespaceMap map)

Sets the namespace map used by namespace-qualified String paths.

Parameters:

map - the XmlNamespace map

setDefaultNamespaceMap

public void setDefaultNamespaceMap(java.lang.String pairs)

Sets the namespace map used to resolve namespace-qualified String paths.

Parameters:

pairs - a String in the form "prefix1 namespace1 prefix2 namespace2 ..."

setObject

public void setObject(XmlDataContentTag memberTag,
                      java.lang.Object obj)

Sets the object at the specified tag. The entire object is replaced. This method makes it possible to replace a repeating value with a scalar value, or a scalar value with a repeating value. No index is allowed.

Parameters:

memberTag - the tag for which the value is set. For group-tags, any-tags, and substitution-tags, the content must be IData or IData[]. For element-tags, the content may be String, String[], IData, IData[], or Object[].

obj - the object stored at the tag

Throws:

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

setValue

public void setValue(XmlDataContentTag memberTag,
                     java.lang.Object value,
                     int... index)

Sets the value stored at the specified tag. If repeating values are present, an index must be specified. The value is stored "as is" but must be compatible with the memberTag. A value must be a String or IData for elements tags. It must be an IData for group-tags. For an any-tag, the any-item must already be present unless it can be constructed from an indirect-qualifier tag. For a substitution-tag, a substitution-item must already be present unless it can be constructed from an indirect-qualifier tag. The index must be less than the number of items already present in order to replace an existing item. The index may be equal to the number of repeating items which causes the list to be extended by one value. It is not allowed to specify an index greater than the number of repeating items present, or specify a number greater than or equal to the maxOccurs property of the field.

Parameters:

memberTag - the tag whose value is set

value - the single value stored at the tag

index - offset into the repeating value list

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.FormatError - if the value does not exist (unless it can be constructed from an indirect-qualifier tag)

XmlDataException.UnknownField - when the specified field is not defined in the mapping record.

setValue

public void setValue(XmlDataContentTag[] tags,
                     java.lang.Object value)

Performs a setValue() by navigating from the current map to the specified child along a map-path specified by a list of content-tags. If any of the tags correspond to repeating values, an indexed form of the content-tag must be used.

Parameters:

tags - path expressed as an array of tags

value - the value to be set

setValue

public void setValue(java.lang.String path,
                     java.lang.Object value)

Performs a setValue() by navigating from the current map to the specified child along a map-path specified as a String. If any of the tags correspond to repeating values, an indexed form of the path String must be used. If the path string uses namespace-qualified tags, the path must include the { ... } namespace preamble, or the default namespace may must be set using the setDefaultNamespaceMap.

Parameters:

path - path expressed as String

value - the value to be set

setValueAndTag

public void setValueAndTag(XmlDataContentTag memberTag,
                           XmlDataContentTag valueTag,
                           java.lang.Object value,
                           int... index)

Sets the value and value-tag of the specified indirect-item. If repeating values are present an index must be specified. This method is useful only when the item tag is an any-tag or a substitution-tag, implying that the associated value is an indirect-item.

Parameters:

memberTag - the indirect-tag of the item for which the value and value-tag is set

valueTag - the value-tag that is set for the indirect-item

value - value assigned to the indirect-item

index - index into repeating value

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.TagConflict - when invoked on anything other than an XmlDataSubstitutionTag or XmlDataAnyTag

setValueTag

public void setValueTag(XmlDataContentTag memberTag,
                        XmlDataElementTag valueTag,
                        int... index)

Sets the value-tag of the specified indirect-item. If repeating values are present, an index must be specified. This method is useful only when the item tag is an any-tag or a substitution-tag, and thus has an indirect-item as its value. Unlike many other map operations, the item must exist in order for this operation to succeed because only the value-tag is changing; the value is unchanged.

Parameters:

memberTag - the indirect-tag of the item whose value-tag is changed

valueTag - the new value-tag

index - offset into repeating values

Throws:

XmlDataException.IndexOutOfRange - when the index exceeds the number of repeating elements or the maxOccurs of the mapped field

XmlDataException.UnknownField - when the specified tag is not defined in the mapping record

XmlDataException.TagConflict - when invoked on anything other than an XmlDataSubstitutionTag or XmlDataAnyTag