Chapter 4 adding namespace declaration

Add namespace declaration

Default behavior

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 Sample.Person Extends (%Persistent, %Populate, %XML.Adaptor)
{

Parameter NAMESPACE = "http://www.yaoxin.com";
}

If you export multiple objects of this class, you will see something similar to the following:

DHC-APP> w ##class(Demo.XmlDemo).Obj2Xml(1)
<?xml version="1.0" encoding="UTF-8"?>
<Person xmlns="http://www.yaoxin.com">
  <Name>yaoxin</Name>
  <SSN>111-11-1117</SSN>
  <DOB>1990-04-25</DOB>
  <s01:Home xmlns="" xmlns:s01="http://www.yaoxin.com">
    <Street>889 Clinton Drive</Street>
    <City>St Louis</City>
    <State>WI</State>
    <Zip>78672</Zip>
  </s01:Home>
  <s01:Office xmlns="" xmlns:s01="http://www.yaoxin.com">
    <Street>9619 Ash Avenue</Street>
    <City>Ukiah</City>
    <State>AL</State>
    <Zip>56589</Zip>
  </s01:Office>
  <Spouse>
    <Name>Puyi</Name>
    <SSN>111-11-1115</SSN>
    <FavoriteColors>
      <FavoriteColorsItem>Red</FavoriteColorsItem>
      <FavoriteColorsItem>Orange</FavoriteColorsItem>
      <FavoriteColorsItem>Yellow</FavoriteColorsItem>
      <FavoriteColorsItem>Green</FavoriteColorsItem>
    </FavoriteColors>
  </Spouse>
  <FavoriteColors>
    <FavoriteColorsItem>Red</FavoriteColorsItem>
    <FavoriteColorsItem>Orange</FavoriteColorsItem>
    <FavoriteColorsItem>Yellow</FavoriteColorsItem>
  </FavoriteColors>
  <Age>31</Age>
</Person>

Namespace declarations are automatically added to each < person > element. Only add it to the root directory of the document.

Add declaration manually

You can control when namespaces are introduced into XML output. The following methods affect the next element written (but not any element after that element). For convenience, several of these methods add a standard W3 namespace.

These methods are typically used to add namespace declarations to the root element of a document; That is to say, call one or more methods before calling RootObject() or RootElement().

Note: none of these methods assign any elements to namespaces, and these namespaces will never be added as the default namespace. When generating a specific element, you need to indicate the namespace it uses, as described in "write root element" and "generate XML element" later.

AddNamespace()

method AddNamespace(namespace As %String, 
                    prefix As %String, 
                    schemaLocation As %String) as %Status

Adds the specified Namespace. Here, Namespace is the Namespace to be added, Prefix is the optional Prefix of the Namespace, and schemaLocation is the optional URI indicating the corresponding schema location.

If no prefix is specified, the prefix will be automatically generated (format S01, S02, etc.).

The following example shows the effect of this method. First, assume that the Person class is assigned to a namespace (namespace in the class parameter). If you generate the output of such an instance without first calling the AddNamespace() method, you may receive the following output:

<?xml version="1.0" encoding="UTF-8"?>
<Root>
  <Person xmlns="http://www.person.org">
    <Name>Love,Bart Y.</Name>
...

Alternatively, before writing the root element, call the AddNamespace() method as follows:

 set status=writer.AddNamespace("http:///www.person.org","p")

If the root element is subsequently generated, the output is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:p="http:///www.person.org">
  <Person xmlns="http://www.person.org">
...

Alternatively, suppose a third parameter is specified when calling the AddNamespace() method, which provides the location of the associated schema:

 set status=writer.AddNamespace("http:///www.person.org","p","http://www.MyCompany.com/schemas/person.xsd")

In this case, if the Root element is subsequently generated, the output is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:p="http:///www.person.org" 
xsi:schemaLocation="http:///www.person.org http://www.MyCompany.com/schemas/person.xsd" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Person xmlns="http://www.person.org">
...

AddInstanceNamespace()

method AddInstanceNamespace(prefix As %String) as %Status

Add W3 schema instance namespace. The prefix here is an optional prefix for this namespace. The default prefix is XSI.

<Root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...

AddSchemaNamespace()

method AddSchemaNamespace(prefix As %String) as %Status

Add W3 schema namespace. The prefix here is an optional prefix for this namespace. The default prefix is s.

<Root xmlns:s="http://www.w3.org/2001/XMLSchema">
...

AddSOAPNamespace()

method AddSOAPNamespace(soapPrefix As %String, 
                        schemaPrefix As %String, 
                        xsiPrefix As %String) as %Status

Add W3 SOAP encoding namespace, SOAP schema namespace and SOAP schema instance namespace. This method has three optional parameters: the prefix used for these namespaces. The default prefixes are SOAP enc, s, and XSI.

<Root xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...

AddSOAP12Namespace()

method AddSOAP12Namespace(soapPrefix As %String, 
                          schemaPrefix As %String, 
                          xsiPrefix As %String) as %Status

Add W3 SOAP 1.2 encoding namespace, SOAP schema namespace and SOAP schema instance namespace.

<?xml version="1.0" encoding="UTF-8"?>
<Root xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding" 
xmlns:s="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...

You can use more than one of these methods. If you use more than one of these namespaces, the affected element will contain the declaration of all the specified namespaces.

Write root element

Each XML document must contain exactly one root element. There are two ways to create this element:

• The root element may correspond directly to an object with InterSystems IRIS XML enabled.

In this example, the RootObject() method is used, which writes the specified XML enabled object as the root element. The output includes all object references contained in the object. The root element gets the structure of the object and cannot insert other elements. You can specify the name of the root element or use the default value defined by the XML enabled object.

The previous example uses this technique.

• The root element may be just a wrapper for a set of elements (it may be a set of objects that support XML).

In this case, the RootElement() method is used, which inserts the root level element with the specified name. If this document is indented, this method also increases the indent level of subsequent operations.

It then calls other methods to generate output for one or more elements within the root element. The elements can be included in any desired logical order or root directory. After that, call the EndRootElement() method to close the root element.

In both cases, you can specify the Namespace to use for the root element, which is applied only if the XML enabled class does not have a Namespace parameter value.

Remember that if the document contains a document type declaration, the name of the DTD must be the same as the name of the root element.