XmlData (webMethods Java API Reference)

java.lang.Object
- com.wm.data.XmlData

```
public class XmlData
extends java.lang.Object
```
The XmlData feature encodes the XML Infoset as IData structures using a format similar to, but more advanced than, the legacy format of prior implementations. The structure of IData itself is completely unaffected by this feature. Rather, this feature adds a layer of formalism to the way in which XML infosets are represented using IData. This new format is independent of the legacy implementation; the legacy implementation, services, and applications that use the legacy format will continue to function without change. The new format is exploited using a separate set of public services and helper classes. The two formats cannot be intermixed. The XmlData content should not reference legacy content, and legacy XML content should not reference XmlData content. However, either or both types of content can be referenced from an IData that does not represent XML encoded data (for example the Integration Server pipeline).
The encoding format also conforms to the format of the new XML document types, though it is possible to use XmlData without using XML document types. The new XML document types more fully represent the capabilities of XML and XML Schema.
This new format is created from XML and converted back to XML using new services in the pub.xmldata folder in the WmPublic package. The new format may also be created and updated using the facilities of this XmlData helper class and the XmlDataCursor class. The new content is defined using hierarchies of Document Types. This makes it possible for Flow Map manipulate the new format in ways very similar to the legacy format.
Like the legacy approach, XMlData uses IData objects to represent complex content as key/value pairs. Likewise, it uses Strings to represents simple content. Repeating elements (schema minOCcurs > 1) are represented as arrays. However, the XmlData format allows no other object type, not even Java null. Empty simple content must be represented as empty Strings and empty complex content must be represented as empty IData objects.
In a more obvious departure from the legacy format, the XmlData feature encodes QNames as ncname#url rather than prefix:ncname. This eliminates the need for and complexity of a secondary definition of the namespace elsewhere such as in a document type or in an instance nsdecls map.
Using a simple example, the XML content:
```
    <inv:address xmlns:inv="www.invoice.com">555 Mockingbird Lane</inv:address>
 
```
is represented in the legacy format using IData as key/value pair:
```
    "inv:address" :: "555 Mockingbird Lane"
 
```
with the prefix "inv" being defined externally. While in the new XmlData format, it is represented as an IData key/value pair:
```
    "address#www.invoice.com" :: "555 Mockingbird Lane"
 
```
When creating XML document types from schemas, model groups (sequence, choice, and all) are represented using a field named *group with a content type of Document. The Document contains the child content definition of the group. When complex content has attributes, the attributes are encoded under a separate Document containing the attributes. This separate IData value has a key named *attributes. If simple content is present with attributes, it is encoded using the key *simple. If a schema contains an "any" element wildcard, that particle is represented as a field with name *any and a content of Document. The Document content is a very specialized any object format, which is described later. If a schema contains substitution groups, the head of a substitution group is encoded as field with name *substitution-name with a very specialized IData content, which is described later.
The members of model groups are further qualified by a leading prefix of the form {1}, {2}, ... etc. This prefix uniquely identifies particles in a group since more than one particle with the same name can appear throughout a content model. This qualification is necessary because more than one particle with the same name can appear throughout a content model. Such qualification * applies to ordinary elements as well as particles with reserved names: *group, *any, and particle that starts with *substitution-. This qualification is present even when the names are not repeated. This qualification is in addition to element repetition. For example, an element named "student" might have a maxOccurs property of 5 in one part of a content model and a maxOccurs property of 1 at some later point in the model. Thus, the first occurrence {1}student is defined as an array while the second occurrence {2}student is a scalar. In similar fashion, a content model might contain two choice groups. The first choice group is defined by a field with name {1}*group while the second choice group is defined by a field named {2}*group.
These examples illustrate the encoding. For clarity, unqualified names are used, though the same layout is used for qualified names.
Simple String content such as:
```
     <name>kilroy</name>
 
```
is encoded as a single IData key/value pair with the value being a simple String:
```
    IData
      "{1}name" :: "kilroy"
```
Note that the name field has been prefixed with {1} to denote the first occurrence of the element in the content. More complex content such as
```
     <people xmlns:family>
        <brother>Sam</brother>
        <sister>Karen</sister>
        <brother>Bill</brother>
     </people>
 
```
is encoded in a similar way with multiple kye/value pairs:
```
     "{1}people#family" :: IData
        "{1}brother#family" :: "Sam"
        "{1}sister#family"  :: "Karen"    
        "{2}brother#family" :: "Bill"
 
```
Note that field names such as {1}brother#family include the XML namespace. Also note that there are distinct occurrences of the * brother#family element each with a unique prefix. However, if content contains adjacent repeating elements, the content is represented as an array.
```
     <people xmlns:family>
        <brother>Sam</brother>
        <brother>Bill</brother>
        <sister>Karen</sister>
     </people>
 
```
is encoded in a somewhat similar way, but uses a String[] for the repeated value
```
     "{1}people#family" :: IData
        "{1}brother#family" :: String[]
           "Sam"
           "Bill"
        "{1}sister#family"  :: "Karen"    
 
```
Content with attributes such as:
```
       
     <item size="medium" color="blue">
        <supplier>ABC Inc.</supplier>
        <distributor> XYZ Inc.</distributor>
     </item>
 
```
is encoded as two separate sub-documents named *attributes and *group
```
    "item" :: IData
       "*attributes" :: IData
          "size" :: "medium"
          "color" :: "blue"
       "{1}*group" :: IData
          "{1}supplier" :: "ABC Inc."
          "{1}distributor" :: "XYZ Inc."
 
```
When an element has attributes but only simple content, such as
```
  
     <item size="medium" color="blue">shoe</item>
 
```
the simple content is encoded as a *simple key/value pair rather than a *group sub-document
```
    "item :: IData
       "*attributes" :: IData
          "size" :: "medium"
       "*simple" :: "shoe"
 
```
In the preceding examples, the *group item was present only because attributes were also present. Otherwise, the *group items are not typically needed when only child elements are present. However, if an element has maxOccurs > 1 and its top level model group also has maxOccurs > 1, it is necessary that the *group item be present because both the element and the group have repeating values stored as arrays. For example, given this XML document,
```
     <emplyees>
        <name>Sam</name>
        <address>Mars</address>
        <name>Mary</name>
        <address>Venus</address>
     </employees>
     <employees>
        <name>George</name>
        <address>Pluto</address>
        <name>Sally</name>
        <address>Saturn</address>
     </employees>
 
```
If employees is defined as a particle with maxOccurs > 1 and its content model is defined as multiple repetitions of name and address, then the IData representation of the XML is:
```
    "employees" :: IData[]
        [0] IData 
            "*group" :: IData[]
                [0] IData
                    "name" :: "Sam"
                    "address" :: "Mars"
                [1] IData
                    "name" :: "Mary"
                    "address" :: "Venus"
        [1] IData       
            "*group" :: IData[]
                [0] IData
                    "name" :: "George"
                    "address" :: "Pluto"
                [1] IData
                    "name" :: "Sally"
                    "address" :: "Saturn"
 
```
It is possible to use XmlData without following the document type model. When no XML document types are in use, it is not possible to manipulate XmlData from Flow. It is also not possible to validate the content. When XML document types are not used, there are no wildcards, substitution heads, or model groups. Therefore, it is not necessary, or even desirable to create wildcard, group, or substitution content when not using XML documnet types. In addition, the public services always represent repeating content as Object[] when XML document types are not in use. This greatly simplifies the use of XmlData when XML document types are not used.

Constructor Summary

Constructors
Constructor and Description

XmlData()

Constructors
Constructor and Description
`XmlData()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static IData`	`createAnyObject(XmlDataElementTag tag, java.lang.Object content)` Creates an IData object in the form of a *any value.
`static IData`	`createAttributes(java.lang.Object... pairs)` Creates the attribute content for a complex type.
`static IData`	`createComplexValue()` Creates new empty complex value.
`static IData`	`createComplexValue(IData attributes, java.lang.Object content)` Creates a new populated complex value.
`static IData`	`createGroupValue(java.lang.Object... pairs)` Creates new group content.
`static IData`	`createSubstitutionObject(XmlDataElementTag tag, java.lang.Object content)` Creates an IData object in the form of *substitution content.
`static boolean`	`equalTo(java.lang.Object objA, java.lang.Object objB)` Tests equality of two XmlData formatted objects.
`static java.lang.Object`	`getAnyValue(IData anyContent)` Returns the content of a *any formatted IData object
`static XmlDataElementTag`	`getAnyValueKey(IData anyContent)` Returns the XmlDataElementTag from the *any formatted IData object
`static java.lang.Object`	`getContent(java.lang.Object parent)` Finds the content of an Object that was retrieved using XmlDataCursor.getValue().
`static java.lang.String`	`getInstanceProp(IData data, XmlDataElementTag tag, java.lang.String prop, int... index)` Retrieves an xsi property on an element
`static IData`	`getNamespacePrefixes(IData data, XmlDataElementTag tag, int... index)` Gets all prefix/URI pairs for a an element
`static java.lang.String`	`getNamespacePrefixValue(IData data, XmlDataElementTag tag, java.lang.String prefix, int... index)` Gets the namespace URI for the specified prefix
`static java.lang.Object`	`getSubstitutionValue(IData substitutionContent)` Returns the value of the substituted element in the *substitution formatted content
`static XmlDataElementTag`	`getSubstitutionValueKey(IData substitutionContent)` Returns the XmlDataTag of the substitution content.
`static XmlDataCursor`	`getXmlDataCursor(IData root)` Returns an XmlDataCursor on the specified IData object.
`static void`	`setAnyValue(IData anyContent, java.lang.Object value)` Sets the value in the *any content
`static void`	`setAnyValueKey(IData anyContent, XmlDataElementTag name)` Sets the XmlDataElementTag in the specified *any content
`static void`	`setInstanceProp(IData data, XmlDataElementTag tag, int index, java.lang.String xsitag, java.lang.String xsivalue)` Sets the xsi prop declaration for a given XmlData element with repeating values.
`static void`	`setInstanceProp(IData data, XmlDataElementTag tag, java.lang.String xsitag, java.lang.String xsivalue)` Sets the xsi prop declaration for a given XmlData element with a non-repeating value.
`static void`	`setNamespacePrefix(IData data, XmlDataElementTag tag, int index, java.lang.String prefix, java.lang.String namespace)` Sets the prefix/namespace declaration for a given XmlData element with a repeating values.
`static void`	`setNamespacePrefix(IData data, XmlDataElementTag tag, java.lang.String prefix, java.lang.String namespace)` Sets the prefix/namespace declaration for a given XmlData element with a non-repeating value.
`static void`	`setSubstitutionValue(IData substitutionContent, java.lang.Object value)` Sets the value of the substituted element in *substitution content
`static void`	`setSubstitutionValueKey(IData substitutionContent, XmlDataElementTag tag)` Sets the XmlDataElementTag for the substituted element in *substitution content

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - XmlData
```
public XmlData()
```
- Method Detail
  - createAnyObject
```
public static IData createAnyObject(XmlDataElementTag tag,
                                    java.lang.Object content)
```
    Creates an IData object in the form of a *any value. An IData is created with *ncName and *namespace keys with values derived from the supplied XmlDataElementTag argument , and a *content key with value specified by the Object content argument.
    
    Parameters:
    
    tag - the XMlDataTag for the content
    
    content - the content value
    
    Returns:
    
    an IData in the *any content format
  - createAttributes
```
public static IData createAttributes(java.lang.Object... pairs)
```
    Creates the attribute content for a complex type. This content is typically used as an argument to the createComplexValue method. The created content is an IData with member items that are XmlDataAttrubuteTag keys with String values.
    
    Parameters:
    
    pairs - pairs of alternating XmlDataAttributeTags and Strings.
    
    Returns:
    
    IData collection of attribute/value items
  - createComplexValue
```
public static IData createComplexValue()
```
    Creates new empty complex value. A complex value is an IData object. Its content may be one of the following:
    - an IData object with no *attributes, *groups, or *simple children
    - a single *attributes child with optionally either a *simple or single {1}*group child
    - a single *group child with array content
    The content may be set using the XmlDataCursor.setContent() and XmlDataCursor.setAttribute() methods. Complex content should be used only as element values, never as attribute values. This method creates an empty IData. However, it is preferable to use this method to create the empty IData rather than using an IData factory because future XmlData implementations may impose additional constraints on complex content.
    Returns:
    
    an empty IData object
    
    See Also:
    
    XmlDatCursor#setContent, XmlDatCursor#setAttributes
  - createComplexValue
```
public static IData createComplexValue(IData attributes,
                                       java.lang.Object content)
```
    Creates a new populated complex value. A complex value is an IData object. Its content may be one of the following:
    - an IData object with no *attributes, *groups, or *simple children
    - a single *attributes child with optionally either a *simple or single {1}*group child
    - a single *group child with array content
    The content may also be changed using the XmlDataCursor.setContent() and XmlDataCursor.setAttribute() methods. Complex content should be used only as element values, never as attribute values. When no attributes are present and the model does not repeat, a group value should be used. The complex value is populated with the specified attributes value (if not null) and is populated with a group value if content is an IData, or a *simple value if content is a String.
    Parameters:
    
    attributes - - the attribute values, typically constructed by a call to XmlData.createAttributes
    
    content - - the complex value content (either a String for simple, or an IData for group)
    
    Returns:
    
    an IData formatted as a complex value
    
    Throws:
    
    XMLDataException.UnsupportedType - if attributes content is not IData or if the content is not a String or IData
    
    See Also:
    
    createAttributes(java.lang.Object...), XmlDatCursor#setContent, XmlDatCursor#setAttributes
  - createGroupValue
```
public static IData createGroupValue(java.lang.Object... pairs)
```
    Creates new group content. Group content may contain any number of elements, specifically *any, *substitution, or other *group content. This method returns an empty IData if no argument pairs are specified. However, it is preferable to use this method to create the empty IData rather than using an IData factory because future XmlData implementations may impose additional constraints on group content. This method accepts a list of alternating XmlDataContentTags and content objects. The returned IData is initialized with those key/value pairs. Suitable classes of XmlDataContentTags are XmlDataElementTag, XmlDataAnyTag, XMlDataGroupTag, and XmlDataSUbstitutionTag. Group content should be used only as element values, never as attribute values.
    
    Parameters:
    
    pairs - possibly empty Object[] where even members are instances of XmlDataContentTag subclasses and odd members are content objects suitable for their corresponding tag that immediately precedes them.
    
    Returns:
    
    IData document optionally populated with name/value pairs
    
    Throws:
    
    XmlDataException.TagAndContentConflict - if an odd number of arguments is specified
    
    XmlDataException.TagAndContentConflict - if one of even-number arguments is an XmlDataTag
  - createSubstitutionObject
```
public static IData createSubstitutionObject(XmlDataElementTag tag,
                                             java.lang.Object content)
```
    Creates an IData object in the form of *substitution content. The content is an IData with a single child with the tag and content specified.
    
    Parameters:
    
    tag - the XmlDataElementTag of the substituted element
    
    content - the content
    
    Returns:
    
    a new IData formatted with the specified substitution group content
  - equalTo
```
public static boolean equalTo(java.lang.Object objA,
                              java.lang.Object objB)
```
    Tests equality of two XmlData formatted objects. This method will check the equality of Strings, IDatas, String[], IData[], Object[], and any nested IDatas.
    
    Parameters:
    
    objA - the first Object
    
    objB - the second Object
    
    Returns:
    
    true if they are equal
  - getContent
```
public static java.lang.Object getContent(java.lang.Object parent)
```
    Finds the content of an Object that was retrieved using XmlDataCursor.getValue(). For a String, return the String. For an IData object, return the value associated with the *simple key, the {1}*group key, or the *content key, whichever is present. For IData with no content key (*simple, {1}*group, of *content), return the iData itself. Otherwise, return null. This method is similar to the XmlDataCursor getContent() method, but it operates on a free-standing object, rather than an object that is contained in an IData. Because there is no key available, this method cannot return the content of an object that is the head of a substitution group. For substitution groups values, the user must know to retrieve the value of its first child.
    
    Parameters:
    
    parent - the parent Object
    
    Returns:
    
    the content value
  - getAnyValueKey
```
public static XmlDataElementTag getAnyValueKey(IData anyContent)
```
    Returns the XmlDataElementTag from the *any formatted IData object
    
    Parameters:
    
    anyContent - the IData object in the *any format
    
    Returns:
    
    the XmlDataTag created from the *ncName and *namespace fields of the *any IData object
  - getAnyValue
```
public static java.lang.Object getAnyValue(IData anyContent)
```
    Returns the content of a *any formatted IData object
    
    Parameters:
    
    anyContent - the IData object in the *any format
    
    Returns:
    
    the object stored in *content field of the *any IData object
  - getInstanceProp
```
public static java.lang.String getInstanceProp(IData data,
                                               XmlDataElementTag tag,
                                               java.lang.String prop,
                                               int... index)
```
    Retrieves an xsi property on an element
    
    Parameters:
    
    data - the parent IData
    
    tag - the XMlDataElementTag to be queried
    
    prop - the property queried, for example: type, nil
    
    index - the optional offset into repeating values
    
    Returns:
    
    the String values associated with the specified property
  - getNamespacePrefixValue
```
public static java.lang.String getNamespacePrefixValue(IData data,
                                                       XmlDataElementTag tag,
                                                       java.lang.String prefix,
                                                       int... index)
```
    Gets the namespace URI for the specified prefix
    
    Parameters:
    
    data - the parent IData
    
    tag - the XmlDataElementTag to be queried
    
    prefix - the prefix queried
    
    index - the optional offset index if repeating values are present
    
    Returns:
    
    the String value associated with the specified prefix
  - getNamespacePrefixes
```
public static IData getNamespacePrefixes(IData data,
                                         XmlDataElementTag tag,
                                         int... index)
```
    Gets all prefix/URI pairs for a an element
    
    Parameters:
    
    data - the parent IData object
    
    tag - the XmlDataElementTag for which the pairs are retrieved
    
    index - option offset in array if repeating values are present
    
    Returns:
    
    IData list of prefix/URI pairs
  - getSubstitutionValueKey
```
public static XmlDataElementTag getSubstitutionValueKey(IData substitutionContent)
```
    Returns the XmlDataTag of the substitution content. Substitution content is an IData with a single child whose key is the XmlDataElemenTag of the substituted element. This method returns the key of the only child.
    
    Parameters:
    
    substitutionContent - content that is in substitution group format (must be an IData)
    
    Returns:
    
    the XmlDataElemenTag of the substituted element
  - getSubstitutionValue
```
public static java.lang.Object getSubstitutionValue(IData substitutionContent)
```
    Returns the value of the substituted element in the *substitution formatted content
    
    Parameters:
    
    substitutionContent - the *substitution formatted content
    
    Returns:
    
    The value associated with the substitution element
  - getXmlDataCursor
```
public static XmlDataCursor getXmlDataCursor(IData root)
```
    Returns an XmlDataCursor on the specified IData object. In theory, any IData object can be passed as an argument. However, if the IData object does not conform to the standard XmlData format, errors and unpredictable results are possible. Only IData objects created using the XmlData methods should be passed.
    
    Parameters:
    
    root - the IData object for which an XmlDatCursor is created
    
    Returns:
    
    an XmlDataCursor in the unpositioned state
  - setAnyValueKey
```
public static void setAnyValueKey(IData anyContent,
                                  XmlDataElementTag name)
```
    Sets the XmlDataElementTag in the specified *any content
    
    Parameters:
    
    anyContent - the value of the element wildcard
    
    name - the XmlDataElementTag naming the wildcard element
    
    Throws:
    
    XmlDataException.UnsupportedType - if content is null
  - setAnyValue
```
public static void setAnyValue(IData anyContent,
                               java.lang.Object value)
```
    Sets the value in the *any content
    
    Parameters:
    
    anyContent - the IData object that is formatted as *any content
    
    value - the value to set in the *any content format
    
    Throws:
    
    XmlDataException.UnsupportedType - if content is null
  - setInstanceProp
```
public static void setInstanceProp(IData data,
                                   XmlDataElementTag tag,
                                   java.lang.String xsitag,
                                   java.lang.String xsivalue)
```
    Sets the xsi prop declaration for a given XmlData element with a non-repeating value. A value of null deletes the declaration if it exists.
    
    Parameters:
    
    data - the IData parent of the element
    
    tag - the tag of the element
    
    xsitag - the xsi tag name
    
    xsivalue - the xsi tag value
  - setInstanceProp
```
public static void setInstanceProp(IData data,
                                   XmlDataElementTag tag,
                                   int index,
                                   java.lang.String xsitag,
                                   java.lang.String xsivalue)
```
    Sets the xsi prop declaration for a given XmlData element with repeating values. A value of null deletes the declaration if it exists.
    
    Parameters:
    
    data - the IData parent of the element
    
    tag - the tag of the element
    
    index - the index of the repeated value to which the xsi declaration is applied
    
    xsitag - the xsi tag name
    
    xsivalue - the xsi tag value
  - setNamespacePrefix
```
public static void setNamespacePrefix(IData data,
                                      XmlDataElementTag tag,
                                      java.lang.String prefix,
                                      java.lang.String namespace)
```
    Sets the prefix/namespace declaration for a given XmlData element with a non-repeating value. A namespace value of null deletes the declaration if it exists.
    
    Parameters:
    
    data - the IData parent of the element
    
    tag - the tag of the element
    
    prefix - the prefix for the declaration
    
    namespace - the namespace URI for the declaration
  - setNamespacePrefix
```
public static void setNamespacePrefix(IData data,
                                      XmlDataElementTag tag,
                                      int index,
                                      java.lang.String prefix,
                                      java.lang.String namespace)
```
    Sets the prefix/namespace declaration for a given XmlData element with a repeating values. A namespace value of null deletes the declaration if it exists.
    
    Parameters:
    
    data - the IData parent of the element
    
    tag - the tag of the element
    
    index - the index of the repeated value to which the namespace declaration is appied
    
    prefix - the prefix for the declaration
    
    namespace - the namespace URI for the declaration
  - setSubstitutionValueKey
```
public static void setSubstitutionValueKey(IData substitutionContent,
                                           XmlDataElementTag tag)
```
    Sets the XmlDataElementTag for the substituted element in *substitution content
    
    Parameters:
    
    substitutionContent - the *substitution formatted IData object
    
    tag - the XmlDataELement tag of the substituted element
    
    Throws:
    
    XmlDataException.UnsupportedType - if null content is specified
  - setSubstitutionValue
```
public static void setSubstitutionValue(IData substitutionContent,
                                        java.lang.Object value)
```
    Sets the value of the substituted element in *substitution content
    
    Parameters:
    
    substitutionContent - the IData content of the substitution group
    
    value - the value assigned to the substitution grup
    
    Throws:
    
    XmlDataException.UnsupportedType - if a null content is specified

Class XmlData

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XmlData

Method Detail

createAnyObject

createAttributes

createComplexValue

createComplexValue

createGroupValue

createSubstitutionObject

equalTo

getContent

getAnyValueKey

getAnyValue

getInstanceProp

getNamespacePrefixValue

getNamespacePrefixes

getSubstitutionValueKey

getSubstitutionValue

getXmlDataCursor

setAnyValueKey

setAnyValue

setInstanceProp

setInstanceProp

setNamespacePrefix

setNamespacePrefix

setSubstitutionValueKey

setSubstitutionValue