Projecting Objects to XML
Specifying Namespaces for Elements and Attributes
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

XML elements and attributes can belong to different namespaces, and the XML Schema specification provides for multiple ways of controlling and representing namespace assignment. The %XML.Adaptor class provides the corresponding support for your XML documents.

This section discusses the following topics:
Also see Specifying the Namespaces for Types,” later in this book.
The XML examples in this chapter are in literal format.
Class and Property Parameters Discussed in This Chapter
Overview
This section provides a refresher on XML namespaces and an overview of how Caché objects are assigned to XML namespaces.
Namespace Refresher
The general assumption in this book is that the reader is familiar with XML. It may be worthwhile, however, to review how to determine the namespace, if any, to which an element or attribute is assigned in an XML document.
First, unless the XML document includes a default namespace or a namespace prefix for every element and attribute that it includes, it is necessary to see the corresponding XML schema. Apart from any imported elements or attributes, any element or attribute is one of the following:
For each element and attribute that it defines, a schema indicates whether that item is qualified or unqualified. The schema does this by a combination of the following pieces:
Consider the following XML document:
<?xml version="1.0" encoding="UTF-8"?>
<ClassA xmlns="mynamespace" xmlns:s01="mynamespace" s01:String1="abcdef">
  <s01:ClassB xmlns="">
    <String3>qrstuv</String3>
    <String4>wxyz</String4>
  </s01:ClassB>
  <String2>ghijkl</String2>
</ClassA>
For simplicity, we assume that the corresponding schema document uses the default values of elementFormDefault and attributeFormDefault, and does not specify the form attribute for any items it defines. Then the items in this document are in namespaces as follows:
XML Namespaces and Classes
In Caché XML support, you specify namespaces on a class-by-class basis. You use the NAMESPACE class parameter to specify the namespace for instances of that class, as well as its immediate child objects. Also, you use the ELEMENTQUALIFIED and ATTRIBUTEQUALIFIED parameters to specify whether properties of its object-valued properties are global (and belong to the same namespace as the parent) or local.
Note:
You can also specify ELEMENTQUALIFIED as a property parameter, if needed for unusual scenarios, not discussed in this book.
Namespaces and Context
Particularly with namespaces, it is important to remember that an XML-enabled object is handled differently depending on the context. For example, if you export an Address object at the top level, it is a global element. If you export a Person object that includes a reference to an Address object, then Address is a local element (as are all other properties of Person). Global and local elements are assigned to namespaces differently.
Specifying the Namespaces for Objects Treated as Global Elements
If you import or export an XML-enabled object at the top level, that object becomes a global element and is assigned to a namespace as follows:
For example, consider the following class definition:
Class MyApp.Person Extends (%Persistent, %XML.Adaptor)
{
Parameter NAMESPACE = "http://www.person.org";

Property Name As %Name [ Required ];

Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h") [ Required ];
}
If you export or import an object of this class, the projection might look as follows:
<Person xmlns="http://www.person.org">
  <Name>Isaacs,Rob G.</Name>
  <DOB>1981-01-29</DOB>
</Person>
Specifying the Namespaces for Properties Projected as Elements
This section describes how to specify the namespace for a property that is projected as an element.
Case 1: Property Is Treated as Local Element
If you import or export an XML-enabled object at the top level, any property that is projected as an element becomes a local element by default. There are two possible namespace assignments for these local elements:
Notice that in both cases, the namespace in the child class is ignored.
Note:
The default for ELEMENTQUALIFIED depends on whether the input or output is in literal format or encoded format. Literal format is the default and the most common.
For literal format, ELEMENTQUALIFIED defaults to 1. For encoded format, ELEMENTQUALIFIED defaults to 0.
For information on these formats, see Specifying Format Options for the XML Document,” earlier in this book.
Case 2: Property Is Treated as Global Element
You can make a property into a global element and assign it to a namespace. To do so, you set the XMLREF property parameter to 1. The following describes how the corresponding element is assigned to a namespace:
  1. If the REFNAMESPACE property parameter is specified, the element is in that namespace.
  2. Otherwise the element is assigned to a namespace as follows:
    1. If the property is a type and specifies the XSDTYPE class parameter, the element is in the namespace of the parent class.
    2. Otherwise, if the property class defines the NAMESPACE class parameter, the element is in the namespace of the property class.
    3. If the property class does not define either of these class parameters, the element is in no namespace.
Note:
The XMLREF property parameter replaces the XMLELEMENTREF property parameter. The XMLELEMENTREF parameter, however, will be supported indefinitely.
Specifying the Namespaces for Properties Projected as Attributes
This section describes how to specify the namespace for a property that is projected as an attribute. The ATTRIBUTEQUALIFIED parameter specifies whether attributes are qualified by a namespace prefix; the possible values are as follows:
The XMLREF and REFNAMESPACE property parameters are also supported for properties that you project as attributes.
For a property projected as an attribute, if you set the XMLREF property parameter to 1, the corresponding attribute is assigned to a namespace as follows:
  1. If the REFNAMESPACE property parameter is specified, the attribute is in that namespace.
  2. Otherwise:
    1. If the property is a type and specifies the XSDTYPE class parameter, the attribute is in the namespace of the parent class.
    2. Otherwise, if the property class defines the NAMESPACE class parameter, the attribute is in the namespace of the property class.
    3. If the property class does not define either of these class parameters, the attribute is in no namespace.
Specifying Custom Prefixes for Namespaces
When you generate XML output for an object, the system generates namespace prefixes as needed. The first namespace prefix is s01, the next is s02, and so on. You can specify different prefixes. To do so, set the XMLPREFIX parameter in the class definitions for the XML-enabled objects themselves. This parameter has two effects:
For example, suppose your class definition is as follows:
Class GXML.Person Extends (%Persistent, %XML.Adaptor)
{

Parameter XMLPREFIX = "p";

Parameter NAMESPACE = "http://www.person.com";

Parameter XMLNAME = "Person";

Property Name As %Name;

}
For this class, XML output looks like the following:
<?xml version="1.0" encoding="UTF-8"?>
<Person xmlns="http://www.person.com" xmlns:p="http://www.person.com">
  <Name>Umansky,Jocelyn O.</Name>
</Person>
For information on exporting to XML, see Using Caché XML Tools.
Recommendations
To simplify development, debugging, and troubleshooting, InterSystems recommends the following practices: