Chapter 6 controlling the use of namespaces

Controls the use of namespaces

As described in projecting an object into XML, you can assign a class to a namespace so that the corresponding XML element belongs to the namespace, and you can also control whether the attributes of the class also belong to the namespace.

When exporting objects in a class to XML,% XML Write provides other options, such as specifying whether an element is a local element of its parent. This section includes the following topics:

• By default,% XML How does writer handle namespaces
• How to specify whether a local element is qualified
• How to specify whether an element is a local element of its parent element
• How to specify whether the attribute is qualified
• Summary of namespace assignments

Note: in InterSystems IRIS XML support, namespaces can be specified by class. Typically, each class has its own namespace declaration; However, usually only one or a few namespaces are required. You can also specify relevant information on a class by class basis (rather than in some global way). This includes settings that control whether an element is a local element of its parent element and whether child elements qualify. For simplicity, a consistent approach is recommended.

Default handling of namespaces

To assign an XML enabled class to a Namespace, set the Namespace parameter of the class, as described in projecting objects into XML. In% XML The writer will automatically insert the Namespace declaration, generate the Namespace prefix, and apply the prefix where appropriate. For example, the following class definitions:

Class GXML.Objects.WithNamespaces.Person Extends (%Persistent, %Populate, %XML.Adaptor)
{
Parameter NAMESPACE = "http://www.person.com";
Property Name As %Name [ Required ];
Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h") [ Required ];
Property GroupID As %Integer(MAXVAL=10,MINVAL=1,XMLPROJECTION="ATTRIBUTE");
}

<Person xmlns="http://www.person.com" GroupID="4">
  <Name>Uberoth,Amanda Q.</Name>
  <DOB>1952-01-13</DOB>
</Person>

Please note the following:

• Namespace declarations are added to every < person > element.
• By default, the local elements (< name > and < DOB >) of the < person > element are qualified.
  This namespace is added as the default namespace and therefore applies to these elements.
• The attribute (GroupID) of the < person > element is unlimited by default.
  This attribute has no prefix and is therefore considered unqualified.
• The prefixes shown here are automatically generated.
  (remember that when an object is assigned to a namespace, only the namespace is specified, not the prefix.)
• This output does not set any namespace related properties in the writer, nor does it use any namespace related methods in the writer.

Context effect of namespace allocation

The namespace assigned to an object that supports xml depends on whether the object is exported at the top level or as an attribute of another object.

A class named Address.
Suppose you use the NAMESPACE parameter to assign the Address class to a NAMESPACE“ http://www.address.org ”.
If you directly export an object of the Address class, you may receive the following output:

<Address xmlns="http://www.address.org">
  <Street>8280 Main Avenue</Street>
  <City>Washington</City>
  <State>VT</State>
  <Zip>15355</Zip>
</Address>

Notice that the < address > element and all its elements are in the same namespace(“ http://www.address.org ”)Yes.

Instead, assume that the attribute of the Person class is an Address object.
Assign the Person class to the NAMESPACE using the NAMESPACE parameter“ http://www.person.org ”.
If you export an object of the Person class, you will receive the following output:

<Person xmlns="http://www.person.org">
  <Name>Zevon,Samantha H.</Name>
  <DOB>1964-05-24</DOB>
  <Address xmlns="http://www.address.org">
     <Street>8280 Main Avenue</Street>
     <City>Washington</City>
     <State>VT</State>
     <Zip>15355</Zip>
  </Address>
</Person>

Notice that the < address > element is in its parent object(“ http://www.person.org ”)In the namespace of.
However, the element of < address > is in the namespace“ http://www.address.org ”Yes.

Controls whether local elements are qualified

When exporting objects at the top level, they are usually treated as global elements. The local elements of XML enabled objects are then processed according to the setting of the elementqualified parameter. If such parameters are not set, the value of the writer property elementqualified is used instead; By default, the text format is 1 and the encoding format is 0.

The following example shows an object whose default setting is ElementQualified, i.e. 1:

<?xml version="1.0" encoding="UTF-8"?>
<PersonNS xmlns="http://www.person.com" GroupID="M9301">
  <Name>Pybus,Gertrude X.</Name>
  <DOB>1986-10-19</DOB>
</PersonNS>

This namespace is added to the < persons > element as the default namespace and therefore applies to the < name > and < DOB > child elements of the element.

We modified the writer definition and set the ElementQualified property to 0.
In this example, the same object is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<s01:PersonNS xmlns:s01="http://www.person.com" GroupID="M9301">
  <Name>Pybus,Gertrude X.</Name>
  <DOB>1986-10-19</DOB>
</s01:PersonNS>

In this case, the namespace is added to the < personns > element with a prefix that is used for the < personns > element, but not for its child elements.

Controls whether an element is local to its parent element

By default, when an element is generated using the object() method and the element has a namespace, the element is not a local element of its parent element. Instead, you can force an element to belong to the namespace of its parent element. To do this, you can use the optional local parameter of the object() method; This is the fourth parameter.

The local parameter is 0 (default)

In the example here, the NAMESPACE class parameter is specified as“ http://www.person.com ”Person class.

If you open the root element and use Object() to generate Person, the < Person > element is located in the“ http://www.person.com ”In the namespace.
The following examples:

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="http://www.rootns.org">
   <Person xmlns="http://www.person.com">
      <Name>Adam,George L.</Name>
      <DOB>1947-06-29</DOB>
   </Person>
</Root>

If we nest the < person > element deeper into other elements, a similar result will appear.

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="www.rootns.org">
   <GlobalEl xmlns="globalns">
      <Inner xmlns="innerns">
         <Person xmlns="http://www.person.com">
            <Name>Adam,George L.</Name>
            <DOB>1947-06-29</DOB>
         </Person>
      </Inner>
   </GlobalEl>
</Root>

The local parameter is set to 1

To force the < person > element to be the local element of its parent element, we set the local parameter to 1.
If we do this and generate the previous output again, we will receive the following less nested version of the output:

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="http://www.rootns.org">
   <s01:Person xmlns="http://www.person.com" 
xmlns:s01="http://www.rootns.org">
      <Name>Adam,George L.</Name>
      <DOB>1947-06-29</DOB>
   </s01:Person>
</Root>

Notice that the < person > element is now“ http://www.rootns.org ”In the namespace, this is the namespace of its parent element.
Similarly, a more nested version should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns="www.rootns.org">
   <GlobalEl xmlns="globalns">
      <Inner xmlns="innerns">
         <s01:Person xmlns="http://www.person.com" xmlns:s01="innerns">
            <Name>Adam,George L.</Name>
            <DOB>1947-06-29</DOB>
         </s01:Person>
      </Inner>
   </GlobalEl>
</Root>

Control whether the attribute is qualified

When exporting objects, their properties are unqualified by default. To qualify them, set the writer attribute AttributeQualified to 1. The following example shows the output generated by a writer whose AttributeQualified is equal to 0 (or has not been set):

<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <s01:Person xmlns:s01="http://www.person.com" GroupID="E8401">
      <Name>Leiberman,Amanda E.</Name>
      <DOB>1988-10-28</DOB>
   </s01:Person>
</Root>

Instead, the following example shows the same object generated using a writer with AttributeQualified equal to 1:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
   <s01:Person xmlns:s01="http://www.person.com" s01:GroupID="E8401">
      <Name>Leiberman,Amanda E.</Name>
      <DOB>1988-10-28</DOB>
   </s01:Person>
</Root>

In both cases, the element is unqualified.

Namespace assignment summary

This section describes how to determine the namespace for any given element in the XML output.

Top level element

For elements corresponding to the InterSystems IRIS class exported at the top level, the following rules apply:

1. If a Namespace parameter is specified for a class, the element is in that Namespace.
2. If this parameter is not specified, the element is in the namespace specified in the output method of the generated element (RootObject(), RootElement(), Object(), or Element()).
3. If no namespace is specified in the output method, the element is in the namespace specified by the DefaultNamespace attribute of the writer.
4. If the DefaultNamespace attribute is empty, the element is not in any namespace.

Low level elements

The child elements of the class to be exported are affected by the elementqualified parameter of the class. If elementqualified is not set, the value of the writer attribute elementqualified is used instead; By default, the text format is 1 and the encoding format is 0.

If the element meets the conditions of a given class, the child elements of that class will be assigned to the namespace as follows:

1. If the Namespace parameter is specified for the parent object, the child element is explicitly assigned to the Namespace.
2. If this parameter is not specified, the child element is explicitly assigned to the namespace specified in the output method of the generated element (RootObject(), RootElement(), Object(), or Element()).
3. If no namespace is specified in the output method, the child elements are explicitly assigned to the namespace specified by the writer's DefaultNamespace attribute.
4. If the DefaultNamespace attribute is empty, child elements are not explicitly assigned to any namespace.