Skip to main content
Previous sectionNext section

Controlling the XML Element and Attribute Names

There is a default correspondence between Caché class and property names and the names of the XML elements and attributes. This topic describes how to override these defaults. It discusses the following items:

Note that Caché also supports the case in which an XML document contains multiple elements with the same name. See the topic “Special Topics.”

The XML examples in this topic are in literal format.

Class and Property Parameters Discussed in This Topic
  • XMLNAME
  • XMLTYPE
  • XMLITEMNAME
  • XMLKEYNAME

Default XML Element and Attribute Names

The default correspondence between Caché names and XML element and attribute name is as follows:

  • For a class, the corresponding XML element or attribute name is the same as the short class name.

  • For a property in this class, the corresponding XML element or attribute name is the same as the property name.

    (Note that the property definition determines whether it is projected as an XML element or attribute. See “Controlling the Projection for Simple Properties.”)

    If the property name includes quotes, the quote marks are not included in the XML element or attribute name. For example, consider the following property:

    Property "Quoted Property" As %String;
    Copy code to clipboard

    This property is projected as the element <Quoted Property> or the attribute Quoted Property, depending on how this property is mapped.

  • If the property is a list or an array, it automatically consists of subelements, each of which is one item in that list or array. By default, the name of the subelement is the property name with Item appended to it.

  • If a property is an array, the subelement also has an attribute to indicate the corresponding key. By default, the name of that attribute is the property name with Key appended to it.

Controlling the Name of the Element or Attribute for an Object Projected as a Top-Level Element

When you project a class instance as a top-level element, its XML name is determined as follows:

Tag for Object Projected as Top-Level Element
XMLNAME Parameter of Class XMLType Parameter of Class Tag (Element or Attribute)
Specified Ignored Value of XMLNAME
Not specified Specified Value of XMLTYPE
Not specified Short class name

For information on XMLTYPE, see the topic “Controlling the Projection to XML Schemas.”

For example, if you export objects of the Sample.Address class, each of those objects would be shown something like the following, by default:

<Address>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <Zip>27621</Zip>
</Address>
Copy code to clipboard

Suppose that you specify the XMLNAME parameter of the Sample.Address class. For example:

Parameter XMLNAME = "HomeAddress";
Copy code to clipboard

In this case, the output would be as follows instead:

<HomeAddress>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <Zip>27621</Zip>
</HomeAddress>
Copy code to clipboard

You can override these parameters when you export objects to XML, as described in Using Caché XML Tools.

Controlling the Tags for Simple Properties

In an XML-enabled object, each simple property is projected as an XML element or attribute, depending on how it is mapped. In either case, by default, the Caché property name is used as the XML element or attribute name. To provide a different XML name for a property, you specify the XMLNAME parameter of that property.

For example:

Property Zip As %String (XMLNAME = "PostalCode");
Copy code to clipboard

The output for the previous example would be as follows instead:

<HomeAddress>
  <Street>5064 Elm Street</Street>
  <City>Jackson</City>
  <State>PA</State>
  <PostalCode>27621</PostalCode>
</HomeAddress>
Copy code to clipboard

Note that if a property is in turn another Caché object class, the XML projection ignores the class name and the XMLNAME parameter of that class. For example, suppose that the Person class has a property named Address which is a reference to the Address class. The projection for a Person object would look something like the following:

<Person>
 <Name>Zevon,Juanita Q.</Name>
 <DOB>1986-08-18</DOB>
 <Address>
   <Street>5064 Elm Street</Street>
   <City>Jackson</City>
   <State>PA</State>
   <Zip>27621</Zip>
 </Address>
</Person>
Copy code to clipboard

The name of the <Address> element is determined by the name of the corresponding property in the Person object. This is because the address object is a property of the object that is being imported or exported (instead of being an object that is being imported or exported directly).

As with any other property, you can override this name by specifying theXMLNAME parameter for the property. For example:

Property Address As MyApp.Address (XMLNAME = "EmployeeAddress");
Copy code to clipboard

The output for the previous example would be as follows instead:

<Person>
 <Name>Zevon,Juanita Q.</Name>
 <DOB>1986-08-18</DOB>
 <EmployeeAddress>
   <Street>5064 Elm Street</Street>
   <City>Jackson</City>
   <State>PA</State>
   <Zip>27621</Zip>
 </EmployeeAddress>
</Person>
Copy code to clipboard

Controlling the Element and Attribute Names for List-Type Properties

Note:

This section does not apply to a collection property that specifies XMLPROJECTION as "ELEMENT". For such a property, each list item is treated as a separate property of the class. See “Controlling the Projection for Collection Properties.”

In an XML-enabled object, a list-type property is projected to an element with subelements, each of which is one item in that list. Suppose that a Caché object property named ColorOptions equals a list of three strings: "Red", "Green", "Blue". By default, this property corresponds to the following XML fragment:

<ColorOptions>
  <ColorOptionsItem>Red</ColorOptionsItem>
  <ColorOptionsItem>Green</ColorOptionsItem>
  <ColorOptionsItem>Blue</ColorOptionsItem>
</ColorOptions>
Copy code to clipboard

This shows the ColorOptionsItem subelement, which corresponds to an item in the list. The name for this subelement is determined as follows:

Tag for List Items
XMLITEMNAME Parameter of Property XMLNAME Parameter of Property Tag (Element or Attribute)
Specified Ignored Value of XMLITEMNAME
Not specified Specified Value of XMLNAME with Item concatenated to the end
Not specified If the list item corresponds to a data type property, the tag is the property name with Item concatenated to the end. If the list item corresponds to an object class, the tag is the short class name.

The same logic applies to the items of an array. The keys of an array are treated separately; see the next topic.

Controlling the Element and Attribute Names for Array-Type Properties

Note:

This section does not apply to a collection property that specifies XMLPROJECTION as "ELEMENT". For such a property, each array item is treated as a separate property of the class. See the section “Controlling the Projection for Collection Properties.”

In an XML-enabled object, an array-type property is projected to an element with subelements, each of which is one item in that array, in the same basic way that a list property is projected; see the previous section.

Each subelement has an additional attribute that indicates the key associated with the item. You can control the name of this attribute.

Consider the following example property:

Property Tools As %ArrayOfDataTypes;
Copy code to clipboard

For example, suppose that (for some object instance) this property consists of an array as follows:

  • The value Hammer is stored with the key 845.

  • The value Monkey wrench is stored with the key 1009.

  • The value Screwdriver is stored with the key 3762.

By default, this property corresponds to the following XML fragment:

<Tools>
  <ToolsItem ToolsKey="845">Hammer</ToolsItem>
  <ToolsItem ToolsKey="1009">Monkey Wrench</ToolsItem>
  <ToolsItem ToolsKey="3762">Screwdriver</ToolsItem>
</Tools>
Copy code to clipboard

This shows the ToolsKey attribute, which corresponds to the key of an array. The name of this attribute is determined as follows:

Tag for List Item
XMLKEYNAME Parameter of Property XMLNAME Parameter of Property Name of Attribute That Contains the Key
Specified Ignored Value of XMLKEYNAME
Not specified Specified Value of XMLNAME with Key concatenated to the end
Not specified Property name with Key concatenated to the end

Notice that the XMLITEMNAME property parameter does not affect the attribute name; this parameter is discussed in the previous section.

For example, suppose you do not set XMLKEYNAME and you set XMLNAME equal to MyXMLName, as follows:

Property Tools As %ArrayOfDataTypes(XMLNAME = "MyXMLName");
Copy code to clipboard

Then the same property would correspond to the following XML fragment:

<MyXMLName>
  <MyXMLNameItem MyXMLNameKey="845">Hammer</MyXMLNameItem>
  <MyXMLNameItem MyXMLNameKey="1009">Monkey Wrench</MyXMLNameItem>
  <MyXMLNameItem MyXMLNameKey="3762">Screwdriver</MyXMLNameItem>
</MyXMLName>
Copy code to clipboard