Projecting Objects to XML
Controlling the XML Tag Names
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

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

Note that Caché also supports the case in which an XML document contains multiple tags with the same name. See the chapter Special Topics.”
The XML examples in this chapter are in literal format.
Class and Property Parameters Discussed in This Chapter
Default XML Tag Names
The default correspondence between Caché names and XML tags is as follows:
Controlling the Tag of an Object Projected as a Top-Level Element
When you project a class instance as a top-level element, its XML tag 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 chapter Controlling the Projection to XML Types,” later in this book.
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>
Suppose that you specify the XMLNAME parameter of the Sample.Address class. For example:
Parameter XMLNAME = "HomeAddress";
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>
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 corresponds to an element tag or an attribute tag, depending on how it is mapped. In either case, by default, the Caché property name is used as the XML tag. To provide a different XML tag for a property, you specify the XMLNAME parameter of that property.
For example:
Property Zip As %String (XMLNAME = "PostalCode");
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>
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>
The tag for 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 tag by specifying theXMLNAME parameter for the property. For example:
Property Address As MyApp.Address (XMLNAME = "EmployeeAddress");
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>
Controlling the Tags 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,” earlier in this book.
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>
This shows the ColorOptionsItem subelement, which corresponds to an item in the list. The tag for this subelement is chosen as follows:
Tag for List Items (or Array 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 Property name with Item concatenated to the end
The same logic applies to the items of an array. The keys of an array are treated separately; see the next topic.
Controlling the Tags 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,” earlier in this book.
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;
For example, suppose that (for some object instance) this property consists of an array as follows:
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>
This shows the ToolsKey attribute, which corresponds to the key of an array. The tag for this attribute is chosen 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 Item 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");
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>