# Projecting Objects to XML Table 4–2: Exporting Empty Strings and Null Values for a Property Projected to XML as an Element Table 4–3: Exporting Empty Strings and Null Values for a Property Projected to XML as an Attribute Introduction to Object-XML Projections This topic introduces how to project objects to XML and explains why you might want to do this. For information on XML standards supported in InterSystems IRIS® data platform, see XML Standards Supported by InterSystems IRIS. ### 1.1 The Basics The phrase projecting an object to XML means defining ho w that object can be used as an XML document. To project an object to XML, you add %XML.Adaptor to the superclass list of the class that defines the object, as well as an y other object classes used by that class, with minor exceptions. This activity is also called defining the XML pr ojection of the class that defines the object or XML-enabling that class. ### 1.2 How It Works When you define the XML projection for a class: - The system generates additional INT code for the class that enables you to use class instances as XML documents. (This code is generated when you compile the class, and you should not edit it.) - Each property of your class automatically inherits from %XML.PropertyParameters. - %XML.Adaptor adds XML-related class parameters to your class. - %XML.PropertyParameters adds XML-related property parameters to properties in your class. - Data type properties define the LogicalToXSD() and XSDToLogical() methods, which control how data is transformed when output to XML or input from XML. Then, if the default projection is not suitable for your needs, you edit the XML-related parameters in your class as needed. Introduction to Object-XML Projections ### 1.3 Projection Options The XML projection for a given class determines how instances of that class correspond to XML documents and vice versa. For example: You can control the XML projection in many ways, including the following: - Controlling the structure to which a property is projected. For example, simple properties can be projected as either elements or attributes — or they cannot be projected at all, as shown in the preceding example. - Controlling the XML element and attribute names. - Controlling the XML namespaces to which elements and attributes are assigned. - Controlling the details of how the InterSystems IRIS class is mapped to an XML schema. Most of these parameters affect all the scenarios in which you use the XML-enabled class. A few parameters apply only in certain scenarios, noted within this documentation. ### 1.4 Related Tools in InterSystems IRIS When you define the XML projection for a class, you ha ve access to a large set of InterSystems IRIS tools, which are suitable for many practical applications. You can use these tools to work with your class in any of the following ways: - Export objects of that class to XML documents. - Import XML documents into InterSystems IRIS, which creates new instances of that class, which you can then save. - Use objects of that class as arguments for web services and web clients. - Generate XML schemas. InterSystems IRIS implicitly defines an XML type for the class and uses that for v alidation when using objects of that class in any of the preceding ways. InterSystems IRIS provides additional tools for working with XML documents, including arbitrary XML documents that do not correspond to InterSystems IRIS classes. These tools include support for DOM, XPath, and XSLT. InterSystems IRIS uses the InterSystems IRIS SAX Parser to validate and parse inbound and outbound XML documents (SAX means Simple API for XML). The InterSystems IRIS SAX Parser is a built-in SAX XML validating parser using the standard Xerces library. InterSystems IRIS SAX communicates with an InterSystems IRIS process using a high-performance, in-process call-in mechanism. You can fine-tune the parser or pro vide your own custom SAX interface classes. For information on using any of the XML tools described here, see Using XML Tools. For information on web services and clients, see Creating Web Services and Web Clients. ObjectsXMLDocuments...EmployeeClass FirstName SSN Salary Title LastName Possible Applications for XML Documents ### 1.5 Possible Applications for XML Documents You can use XML documents in a variety of practical applications, including: - As a standard format in messaging applications. This includes industry-standard protocols as well as homegrown solutions. - As a standard format for data exchange between applications and users. - As a standard representation for external data storage. This may include traditional database records or it may include more complex content such as documentation. - As the payload of SOAP messages sent between web services and web clients. - As the contents of an XData block in a class definition. See XData Blocks. This topic describes how to project InterSystems IRIS® data platform objects as XML documents. Class and Property Parameters Discussed on This Page - ELEMENTTYPE - XMLPROJECTION - XMLFORMAT - XMLENABLED - XMLSUMMARY - XMLDEFAULTREFERENCE - GUIDENABLED - XMLIO To project an object to XML (alternatively, to define the XML projection of that object), do the follo wing: 1. Add %XML.Adaptor to the superclass list of the class that defines the object. For example: Class Definition Class MyApp.MyClass Extends (%Persistent, %XML.Adaptor) { \/\/class details } This step XML-enables the class. Alternatively, if the object you are projecting is an instance of a system class, create and use a subclass instead. In the subclass, add %XML.Adaptor to the superclass list. Also, InterSystems IRIS provides many specialized XML-enabled classes in its class library. These include classes in the %Net, %SOAP, and other packages. All these XML-enabled classes inherit from %XML.Adaptor. 2. If you are creating an XML-enabled subclass of %ListOfDataTypes, %ArrayOfDataTypes, %ListOfObjects, or %ArrayOfObjects, then in the subclass, specify the ELEMENTTYPE class parameter. For example: Class Definition Class MyApp.MyIntegerCollection Extends %ListOfDataTypes { Parameter ELEMENTTYPE="%Library.Integer"; } For ELEMENTTYPE, specify the complete package and class name of the class used in the collection. If you do not specify this parameter, the type is assumed to be a string. This step is necessary only if you need a complete XML schema. 3. Ensure that each property of the XML-enabled class has an XML projection if suitable, as described in the next section. In most cases, if the property has an object value, you must XML-enable the class that defines the property . The exceptions are collections and streams when used as properties, as described in the next section. No work is necessary for data type classes. 4. Recompile the changed classes. Now you can, for example, write the object to an XML document, as described in Using XML Tools. #### 2.1.1 Exceptions for Objects Used with Web Methods If you use %ListOfDataTypes, %ListOfObjects, %ArrayOfDataTypes, %ArrayOfObjects as input or output for a web method, it is not necessary to create an XML-enabled subclass. It is necessary to specify ELEMENTTYPE, but you can do this in the method signature. If you use a stream class as input or output for a web method, it is not necessary to create an XML-enabled subclass. For further information, see Creating Web Services and Web Clients. To ensure that each property of the object has an XML projection: - For each simple (non-object) property of this object, no work is necessary. Each InterSystems IRIS data type already has an XML projection. - For each stream property, no work is necessary. The XML tools treat stream objects specially when used as properties of an XML-enabled class. - For object-valued properties other than collections, add %XML.Adaptor to the superclass list of the referenced class. - This includes relationship properties. For information on collections, see the following subsections. For information on how InterSystems IRIS XML tools handle property values of different types, see Controlling Transformations of Values. For information on how property types are projected to XML types, see Controlling the Projection to XML Schemas. Ensuring That Properties Have Projections to XML #### 2.2.1 Properties Defined with List of or Array of For each property that is defined with the syntax Property PropName As List of classname or Property PropName As Array of classname, do the following: - If classname is an object class, XML-enable that class. That is, add %XML.Adaptor to the superclass list of classname. - If classname is a datatype class, no work is needed. - If classname is a stream class, and if the property is a list, no work is needed. The streams are projected to XML as strings. Note: InterSystems IRIS does not support projecting arrays of streams to XML. If your object has a property that is defined as an array of streams, include XMLPROJECTION="none" for that property. For example: Class Definition Class MyApp.MyXMLObject Extends (%RegisteredObject, %XML.Adaptor) { Property MyListOfObjects As list Of MyApp.OtherXMLObject; Property MyArrayOfObjects As array Of MyApp.OtherXMLObject; Property MyListOfDT As list Of %String; Property MyArrayOfDT As array Of %String; Property MyListOfStreams As list Of %GlobalCharacterStream; Property MyArrayOfStreams As array Of %GlobalCharacterStream(XMLPROJECTION = "NONE"); } #### 2.2.2 Properties of Type %ListOfDataTypes or %ArrayOfDataTypes The XML tools automatically project properties of type %ListOfDataTypes or %ArrayOfDataTypes as containers. By default, the container includes string elements. If you need a correct XML schema, and if it is inappropriate to assume that the elements are strings, then create and use a subclass of the collection class. In the subclass, specify the ELEMENTTYPE class parameter. For example: Class Definition Class MyApp.MyIntegerCollection Extends %ListOfDataTypes { Parameter ELEMENTTYPE="%Library.Integer"; } For ELEMENTTYPE, specify the complete package and class name of the class used in the collection. #### 2.2.3 Properties of Type %ListOfObjects or %ArrayOfObjects The XML tools automatically project properties of the type %ListOfObjects or %ArrayOfObjects as containers. It is necessary, however, to XML-enable the class used in the collection. For a property of type %ArrayOfObjects, the class used in the collection cannot be a stream class. If you need a complete XML schema, then you must specify the element type for the collection. To do so, create and use a subclass of the collection class. In the subclass, specify the ELEMENTTYPE class parameter, as shown in the previous section. #### 2.2.4 Exceptions If a given property is not projected to XML, there is no need to XML-enable the class to which it refers. The following properties are not projected to XML: - Private properties - Multidimensional properties - Properties that specify the XMLPROJECTION parameter as "NONE" You can project private and multidimensional properties if you set the XMLPROJECTION property parameter to "ELEMENT" or some other appropriate value. Note that for a multidimensional property, only the top node can be included in the projection. ### 2.3 Summary of the Default Projection The default XML projection is as follows: - An object instance corresponds to a top-level XML element. - Only properties are projected. No other class members are projected. - Also, private properties and multidimensional properties are ignored. - Properties are projected to XML in the same order in which they appear within the class definition. - Any property without a specified type is assumed to be a string. - Each object-valued property corresponds to an XML element within the enclosing top-level XML element. - Its properties are nested within this element. - Collections are projected as nested elements. This is true for both collections of data types and collections of objects. - The lower-level details are slightly different for lists and arrays. Relationships are treated in the same way as list properties. The XML projection contains only one side of the relationship; an error occurs if you attempt to project both sides. Character streams are projected as strings. Binary streams are projected using strings with base–64 encoding. ### 2.4 Example XML Projection This section shows an XML-enabled class and its XML projection. #### 2.4.1 Example XML-Enabled Class The following shows an XML-enabled class that includes the major structural property variations: Example XML Projection Class Definition Class Basics.BasicDemo Extends (%RegisteredObject, %XML.Adaptor) { Parameter XMLTYPENAMESPACE = "mytypes"; Property SimpleProp As %String; Property ObjProp As SimpleObject; Property Collection1 As list Of %String; Property Collection2 As list Of SimpleObject; Property MultiDimProp As %String [ MultiDimensional ]; Property PrivateProp As %String [ Private ]; } The XMLTYPENAMESPACE parameter specifies the tar get namespace for types defined in this class. The SimpleObject class is also XML-enabled: Class Definition Class Basics.SimpleObject Extends (%RegisteredObject, %XML.Adaptor) { Parameter XMLTYPENAMESPACE = "mytypes"; Property MyProp As %String; Property AnotherProp As %String; } #### 2.4.2 Example XML Document The following shows an XML document generated from an instance of the BasicDemo class: XML abc<\/SimpleProp> 12345<\/MyProp> 67890<\/AnotherProp> <\/ObjProp> list item 1<\/Collection1Item> list item 2<\/Collection1Item> <\/Collection1> 12345<\/MyProp> 67890<\/AnotherProp> <\/SimpleObject> 12345<\/MyProp> 67890<\/AnotherProp> <\/SimpleObject> <\/Collection2> <\/BasicDemo> #### 2.4.3 Example Schema The following shows the schema for the XML type namespace used in the two sample classes: XML <\/sequence> <\/complexType> <\/sequence> <\/complexType> <\/sequence> <\/complexType> <\/sequence> <\/complexType> <\/schema> Document There are two basic formats of XML documents, literal and encoded (SOAP-encoded). For examples of these formats, see Introduction to InterSystems XML Tools. You specify one of these formats when you export data from or import data into an XML-enabled class. When you add %XML.Adaptor to a class and compile it, InterSystems IRIS writes additional code to the generated routines. By default, this additional code supports both formats. If you need only one format, you can suppress the other format and reduce the amount of generated code. To do so, specify the XMLFORMAT parameter for that class. Use one of the following values (not case-sensitive): - "LITERAL" — The class supports only literal format. - "ENCODED" — The class supports only encoded format. (It does support both SOAP 1.1 and SOAP 1.2 versions). - Null (the default) — The class supports both literal and encoded formats. ### 2.6 Controlling the Form of the Projection for Simple Properties A simple property is a property whose type is a data type class or whose type is undeclared (any property without a specified type is assumed to be a string). To control the form of the XML projection for a simple property, set the XMLPROJECTION parameter for that property. Use one of the following values (not case-sensitive): Controlling the Form of the Projection for Simple Properties Table 2–1: Effect of XMLPROJECTION on Simple Properties Value of XMLPROJECTION Effect on Non-collection Properties "ELEMENT" The property is projected as an element.This is the default for non-collection properties. "ATTRIBUTE" The property is projected as an attribute. "XMLATTRIBUTE" The property is projected as an attribute with the prefix xml. "WRAPPED" "CONTENT" The property is projected as an element with a subelement; the name of the subelement is based on the data type of the property. The property is projected as the primary content for this class (that is, the contents of the property are written without any enclosing element). In any class, you cannot specify this value for more than one property. "NONE" The property is not projected to XML. The XMLPROJECTION parameter also accepts the values "COLLECTION" or "ELEMENTREF", but those values are deprecated and are not documented here; for details, see the class documentation for %XML.PropertyParameters. #### 2.6.1 Basic XMLPROJECTION Variations The following class defines simple properties that use all v ariations of XMLPROJECTION except for "CONTENT": Class Definition Class xmlproj.SimpleProps Extends (%RegisteredObject, %XML.Adaptor) { Property Simple1 As %String (XMLPROJECTION="attribute"); Property Simple2 As %String (XMLPROJECTION="xmlattribute"); Property Simple3 As %String; Property Simple4 As %String (XMLPROJECTION="element"); Property Simple5 As %String (XMLPROJECTION="wrapped"); Property Simple6 As %String (XMLPROJECTION="none"); } The following shows an example of the XML representation of an instance of this class: XML jumps<\/Simple3> over<\/Simple4> the lazy<\/string> <\/Simple5> <\/SimpleProps> #### 2.6.2 Projecting a Property as Content The "CONTENT" value enables you to project the class as a simple element with some text content and possibly some attributes, but no subelements. The following shows an example class that uses this value: Class Definition Class xmlproj.SimpleContentProp Extends (%RegisteredObject, %XML.Adaptor) { Property Simple1 As %String(XMLPROJECTION = "content"); Property Simple2 As %String(XMLPROJECTION = "attribute"); Property Simple3 As %String(XMLPROJECTION = "element"); } When you export an instance of such a class: - If the property marked with "CONTENT" has a value, this value is exported as the content of the class. Any properties that are projected as attributes are also exported. Other properties are ignored. For example: - XML The quick brown fox jumps over the lazy dog<\/SimpleContentProp> If the property marked with "CONTENT" is null, then it is ignored, and the other properties are all exported as specified by their values for XMLPROJECTION. For example: XML yet another value<\/Simple3> <\/SimpleContentProp> You cannot specify XMLPROJECTION as "CONTENT" for more than one property in any class. Also, you can use this value only for a property that contains simple, literal value, not a collection or other type of object. ### 2.7 Controlling the Form of the Projection for Object-Valued Properties For each object-valued property, the default XML projection consists of an XML element (to represent the object itself) with subelements or attributes to represent the properties of that object, as controlled by the XML projection options in that object class. For an example, see Example XML Projection. Note: Later sections discuss the following special object-valued properties: collections, relationships, and streams. #### 2.7.1 Specifying the Form of the Projection for an Object-Valued Property To control how a object property is projected, set the XMLPROJECTION parameter for that property, as follows: Table 2–2: Effect of XMLPROJECTION on Object Properties Effect on Collection Properties "WRAPPED" "ELEMENT" "NONE" The property is projected as an element with subelements. The element corresponds to the object class. Each subelement corresponds to a property of that class. This is the default for object properties (other than streams). Each property of the object class is projected as an element, without being wrapped in a parent element. The property is not projected to XML. "ATTRIBUTE", "XMLATTRIBUTE", or "CONTENT" Compile-time error. For example, consider the following class: Class Definition Class Basics.ObjectPropsDemo Extends (%RegisteredObject, %XML.Adaptor) { Property Object1 As SimpleObject(XMLPROJECTION = "wrapped"); Property Object2 As SimpleObject(XMLPROJECTION = "element"); } The following shows an example of the XML representation of an instance of this class: XML abcdef<\/MyProp> qrstuv<\/AnotherProp> <\/SimpleObject> <\/Object1> abcdef<\/MyProp> qrstuv<\/AnotherProp> <\/Object2> <\/ObjectPropsDemo> #### 2.7.2 Specifying an XML Summary You can easily specify which properties of a class to project to XML when that class is used as a property: - In the class, specify the XMLSUMMARY class parameter as a comma-separated list of the properties to project to XML, in the exact case used in the class definition. Note that XMLSUMMARY cannot include the pseudo-properties ID and OID. - This parameter has no effect unless you also specify either or both of the following parameters. In the same class, optionally specify the XMLDEFAULTREFERENCE as "SUMMARY" or "COMPLETE" (the default); these values are not case-sensitive. The option "SUMMARY" means that only the properties listed in XMLSUMMARY should be used in the projection when this class is used as a property. The option "COMPLETE" means that all properties that have XML projections should be used. These values are not case-sensitive. - In a class that uses this class as a property, optionally specify the XMLREFERENCE property parameter as "SUMMARY" or "COMPLETE" (the default); these values are not case-sensitive. This overrides the XMLDEFAULTREFERENCE class parameter. You can set this property parameter only for a property whose value is an object. For example, consider the following Address class: Class Definition Class xmlsummary.Address Extends (%RegisteredObject, %XML.Adaptor) { Parameter XMLSUMMARY = "City,ZipCode"; Parameter XMLDEFAULTREFERENCE = "SUMMARY"; Property Street As %String; Property City As %String; Property State As %String; Property ZipCode As %String; } The following shows an example of the XML representation of an instance of this class: XML

47 Winding Way<\/Street> Middlebrook<\/City> GA<\/State> 50291<\/ZipCode> <\/Address> Notice that all properties are included. Now consider another class that uses the Address class as a property: Class Definition Class xmlsummary.Person Extends (%RegisteredObject, %XML.Adaptor) { Property Name As %String; Property Address as Address; } The following shows an example of the XML representation of an instance of this class: XML Penelope Farnsworth<\/Name>

Middlebrook<\/City> 50291<\/ZipCode> <\/Address> <\/Person> Here, because the Address class is a property of this class, the XMLSUMMARY and XMLDEFAULTREFERENCE parameters are used, and only the class properties listed in XMLSUMMARY are used in the projection. You can use the "COMPLETE" option to force an override. For example, the following class also uses the Address class as a property but specifies XMLREFERENCE as "COMPLETE": Class Definition Class xmlsummary.Employee Extends (%RegisteredObject, %XML.Adaptor) { Property Name As %String; Property Address As Address(XMLREFERENCE = "COMPLETE"); } The following shows an example of the XML representation of an instance of this class: XML Malcom Winters<\/Name>

770 Enders Lane<\/Street> Middlebrook<\/City> GA<\/State> 50293<\/ZipCode> <\/Address> <\/Employee> All the properties that have XML projections are included; in this case, this means all properties are included. #### 2.7.3 Projecting Only Object Identifiers Instead of projecting an object-valued property in the default way, you can project only an identifier for the object. To do so, use one of the following values for the XMLDEFAULTREFERENCE class parameter or the XMLREFERENCE property parameter: - The "ID" option projects only the internal ID of the object, as stored on disk. It does not project any properties. For example, consider the following class: Class Definition Class xmlidentifiers.Person Extends (%Persistent, %XML.Adaptor) { Property Name As %String; Property PrimaryCarePhysician As Person (XMLREFERENCE = "ID"); } The following shows an example of the XML representation of an instance of this class: XML 24<\/PrimaryCarePhysician> <\/Person> - The "OID" option projects only the OID of the object (as package.class,ID). It does not project any properties. If we use this option for the PrimaryCarePhysician property, the preceding Person object would be projected as follows: XML xmlidentifiers.Person,24<\/PrimaryCarePhysician> <\/Person> - The "GUID" option projects only the GUID (globally unique ID) of the object, if available. The GUID for an object is null unless the GUIDENABLED class parameter is 1. Suppose that we redefine the Person class as follows: Class Definition Class xmlidentifiers.Person Extends (%Persistent, %XML.Adaptor) { Parameter GUIDENABLED=1; Property Name as %String; Property PrimaryCarePhysician As Person (XMLREFERENCE = "GUID"); } In this case, the XML representation of an instance of this class could be as follows: XML D0F383EB-DB31-4C11-AD56-AA14EB37B734<\/PrimaryCarePhysician> <\/Person> Note: For the property parameter XMLREFERENCE, you can use the "ID", "OID", and "GUID" options only if the value is a persistent object. You receive compile-time errors otherwise. Similarly, if you set the class parameter XMLDEFAULTREFERENCE to "ID", "OID", or "GUID", and if the class has properties whose values are non-persistent objects, you must explicitly set the property parameter XMLREFERENCE to "COMPLETE"" or "SUMMARY" for those properties. ### 2.8 Controlling the Form of the Projection for Collection Properties To control the form of the XML projection for a collection property, set the XMLPROJECTION parameter for that property, as follows: Table 2–3: Effect of XMLPROJECTION on Collection Properties Effect on Collection Properties "WRAPPED" "ELEMENT" "NONE" The property is projected as an element with subelements; each subelement corresponds to an item of the collection.This is the default for collection properties. Each item in the collection is projected as an element, without being wrapped in the parent property. The property is not projected to XML. "ATTRIBUTE", "XMLATTRIBUTE", or "CONTENT" Compile-time error. The following sections show examples with properties that are lists or arrays of data types. For collections of objects, the projected elements can have further structure, recursively, depending on the XML projections of those objects. Controlling the Form of the Projection for Collection Properties #### 2.8.1 Specifying the Form of the Projection for List Properties The following class defines collection properties that use the "WRAPPED" and "ELEMENT" values: Class Definition Class xmlproj.DataTypeColls Extends (%RegisteredObject, %XML.Adaptor) { Property Collection1 As list Of %String; Property Collection2 As list Of %String (XMLPROJECTION="wrapped"); Property Collection3 As list Of %String (XMLPROJECTION="element"); } The following shows an example of the XML representation of an instance of this class: XML list item 1<\/Collection1Item> list item 2<\/Collection1Item> <\/Collection1> list item 1<\/Collection2Item> list item 2<\/Collection2Item> <\/Collection2> list item 1<\/Collection3> list item 2<\/Collection3> <\/DataTypeColls> For the Collection3 property, which uses "ELEMENT", the XML projection disregards the list nature of the property and instead treats each list item as a separate property of the class. #### 2.8.2 Specifying the Form of the Projection for Array Properties For an array, each array item has both a value and a key, and both of these pieces of information must be represented in XML. The key is always projected as an XML attribute within the element. Consider the following class: Class Definition Class xmlproj.DataTypeArray Extends (%RegisteredObject, %XML.Adaptor) { Property ArrayProp As array Of %String; } The following shows an example of the default XML representation of an instance of this class: XML apples<\/ArrayPropItem> bananas<\/ArrayPropItem> chocolate<\/ArrayPropItem> <\/ArrayProp> <\/DataTypeArray> If you specify XMLPROJECTION as "ELEMENT", the XML projection is as follows instead: XML apples<\/ArrayProp> bananas<\/ArrayProp> chocolate<\/ArrayProp> <\/DataTypeArray> ### 2.9 Controlling the Form of the Projection for Relationships Relationships are projected to XML in the same way as other properties, depending on the nature of the collection used in them: - For a parent-child relationship: – – The relationship property in the parent object is a collection property, specifically a list of objects. See Controlling the Projection for Collection Properties. The relationship property in the child object is an object-valued property. This relationship is not projected to XML by default. - For a one-to-many relationship: – – The relationship property in the single object is a collection property, specifically a list of objects. The relationship property in the other object is an object-valued property. This relationship is not projected to XML by default. At any given time, only one side of the relationship can be projected, because otherwise there would be an infinite loop. To reverse the way in which the projection is done, use the XMLPROJECTION property parameter. This principle is best explained by examples. #### 2.9.1 The Default Projection for Relationships First, consider the following pair of classes: Controlling the Form of the Projection for Relationships The class Parent is the parent of the class Child. The class Parent has two properties (ParentPropA and ParentPropB) in addition to the relationship property (Children). Similarly, the class Child has two properties (ChildPropA and ChildPropB) in addition to the relationship property (MyParent). When you project these classes to XML, you get the following results by default: - The XML projection for Parent includes projections for three properties: ParentPropA, ParentPropB, and Children. The Children property is treated like any other collection. That is, by default it is projected as a set of nested elements. For example: XML 12345<\/ParentPropA> 67890<\/ParentPropB> abc<\/ChildPropA> def<\/ChildPropB> <\/Child> ghi<\/ChildPropA> jkl<\/ChildPropB> <\/Child> <\/Children> <\/Parent> - The XML projection for Child includes projections for two properties: ChildPropA and ChildPropB. The property MyParent is ignored. For example: XML abc<\/ChildPropA> def<\/ChildPropB> <\/Child> The same is true for one-to-many relationships. Specifically , the object on the one side includes a projection for the relationship property. The object on the many side does not include a projection for the relationship property. ChildChildPropA...ChildChildPropA...ParentParentPropA...ChildChildPropA... #### 2.9.2 Projecting the Other Side of the Relationship Instead By specifying the XMLPROJECTION parameter in the relationship properties of both classes, you can project the other side of the relationship instead. The following example is a variation of the default example. Class Definition Class Relationships2.Parent Extends (%Persistent, %XML.Adaptor) { Property ParentPropA As %String; Property ParentPropB As %String; Relationship Children As Child(XMLPROJECTION = "NONE") [ Cardinality = children, Inverse = MyParent ]; } Similarly, the Child class is as follows: Class Definition Class Relationships2.Child Extends (%Persistent, %XML.Adaptor) { Property ChildPropA As %String; Property ChildPropB As %String; Relationship MyParent As Parent (XMLPROJECTION="element") [ Cardinality = parent, Inverse = Children ]; } When you project these classes to XML, you get the following results: - The XML projection for Parent ignores the Children property: XML 12345<\/ParentPropA> 67890<\/ParentPropB> <\/Parent> - The XML projection for Child includes projections for all its properties: XML abc<\/ChildPropA> def<\/ChildPropB> 12345<\/ParentPropA> 67890<\/ParentPropB> <\/MyParent> <\/Child> ### 2.10 Controlling the Form of the Projection of a Stream Property For stream properties, the options for the XMLPROJECTION are as follows: Controlling the Availability of Projected Properties Table 2–4: Effect of XMLPROJECTION on Stream Properties Effect on Stream Properties "ELEMENT" "WRAPPED" "CONTENT" "NONE" "ATTRIBUTE" The stream contents are contained in an element. Treated in the same way as "ELEMENT". The stream contents are projected as described in Projecting a Property as Content. For all other properties, the XMLPROJECTION parameter must be "NONE". The property is not projected to XML. The property is projected as an attribute. "XMLATTRIBUTE" The property is projected as an attribute with the prefix xml. This section shows examples of how streams are projected. For example, consider the following class: Class Definition Class Basics.StreamPropDemo Extends (%Persistent, %XML.Adaptor) { Property BinStream As %Library.GlobalBinaryStream; Property CharStream As %Library.GlobalCharacterStream; } The following shows an example of the XML representation of an instance of this class: XML \/9j\/4AAQSkZJRgABAQEASABIAAD\/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEP ERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7\/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4e ... VcE\/wkZ5wGJBH\/joP50UVfQkqaS5dbi34EZtpJgPRlUkf1H402Fy9oIWHHlPj2K\/Nn9cfhRRSGip ZHzbmEPnEwZGGePu5\/nj8qNJcpcrG4DxSuEkToDnPPtRRUyKGhPsuqlAxbypAhJ43A\/y44q5HbNM vmx3U9vuJDLG+ASCQW+pxRRSKP\/Z<\/BinStream> <\/CharStream> <\/StreamPropDemo> ### 2.11 Controlling the Availability of Projected Properties You can specify whether each projected property is used by import, export, or both. To do this, you set the XMLIO parameter, which controls how the export and import methods of %XML.Writer and %XML.Reader classes handle a property. This parameter can take one of the following values (not case-sensitive): - "INOUT" — This property is used by both export and import. This is the default for projected properties. - "IN" — This property is used by import but is ignored by export. - "OUT" — This property is used by export but causes an error on import. If an XML element corresponding to this property is found in an XML document, then import returns an error. - "CALC" — This property is used by export but is ignored by import. If an XML element corresponding to this property is found in an XML document, then import ignores it. Typically, this is used for calculated properties (whose value is based on the value of other properties) so that you can export a document with all values and ignore the calculated values on import. This parameter has no effect on a property that is not projected to XML. ### 2.12 Disabling the Projection If a class is XML-enabled and you want to prevent the class from being projected (perhaps during testing for some reason), you can set the class parameter XMLENABLED to 0. The default is 1. If you use XMLENABLED to prevent a class from being projected, this class cannot be used as a property by any class that is projected to XML. Setting XMLENABLED to 0 is the same as removing %XML.Adaptor from the superclass list. ### 2.13 Methods in %XML.Adaptor The methods in %XML.Adaptor are deprecated and are mostly not documented. You should instead use the more robust classes %XML.Writer and %XML.Schema, which provide greater support for namespaces. For information, see Using XML Tools. This topic discusses how values are transformed as you export objects to XML and import XML into objects, and it discusses your options for controlling those transformations. The XML examples in this topic are in literal format. The following topic discusses null values and missing values. Class and Property Parameters Discussed on This Page - ESCAPE - CONTENT - XMLTIMEZONE - DISPLAYLIST - VALUELIST - XMLDEFAULTVALUE - XMLLISTPARAMETER - XMLSTREAMMODE ### 3.1 Introduction An XML-enabled object typically includes properties defined by InterSystems IRIS® data platform data types. Each data type class defines the LogicalToXSD() and XSDToLogical() methods. Whenever XML output is requested for the object, the InterSystems IRIS XML tools automatically call the LogicalToXSD() method for each property, to convert the data to the appropriate format for use in XML. Similarly, whenever an XML document is used as input, the InterSystems IRIS XML tools call the XSDToLogical() method to convert the data into the correct format for InterSystems IRIS. For example, in the %Binary data type class, the LogicalToXSD() method converts the outbound value using the $SYSTEM.Encryption.Base64Encode() method. Similarly, the XSDToLogical() method converts the inbound value using the $SYSTEM.Encryption.Base64Decode() method. An InterSystems IRIS class can also include stream-valued properties, but the stream classes do not define the LogicalToXSD() and XSDToLogical() methods. Instead, the XML tools treat stream classes specially when they are used as properties of an XML-enabled class. Specifically: - Character streams are treated in the same way as strings. By default, no changes are made apart from the changes that are necessary due to the presence of XML special characters, as described in the next section. - When InterSystems IRIS exports to XML, it converts binary stream properties to strings with base–64 encoding (that is, it encodes the data in that way and then exports it). When InterSystems IRIS imports from XML, it does the reverse. When you use XML-enabled objects, it is sometimes necessary to consider the special cases of values that cannot be directly projected to XML or values that you want to transform for other reasons. ### 3.2 Handling Special XML Characters Depending on the context, InterSystems IRIS XML support escapes the ampersand character (&) and certain other characters, when it finds those characters within a property of type string or character stream. Note: The ESCAPE property parameter controls which characters are recognized as special. This parameter is either "XML" (the default) or "HTML" (not discussed in the documentation). For these special characters, you can control how the escaping is performed by setting the CONTENT property parameter. The details are different for literal and encoded formats, as follows: Table 3–1: Form of Escaping for Literal and SOAP-encoded Formats Value of CONTENT (Case-insensitive) XML Document in Literal Format XML Document in SOAP-encoded Format "STRING" (the default) CData "ESCAPE" "ESCAPE-C14N" XML entity XML entity* CData XML entity XML entity* "MIXED" No escaping is done CData *For "ESCAPE-C14N", the escaping is done in accordance with the XML Canonicalization standard. The main difference is that a carriage return is escaped as #### 3.2.1 Examples Consider the following class: Class Definition Class ResearchXForms.CONTENT Extends (%RegisteredObject, %XML.Adaptor) { Parameter XMLNAME = "Demo"; Property String1 As %String; Property String2 As %String(CONTENT = "STRING"); Property String3 As %String(CONTENT = "ESCAPE"); Property String4 As %String(CONTENT = "MIXED"); } String2 and String1 are always treated in the same way, because String2 uses the default value for CONTENT. Handling the UTC Time Zone Indicator Literal XML output for this class might look like the following: XML <\/String1> <\/String2> value 1 & value 2<\/String3> value 1 & value 2<\/String4> <\/Demo> SOAP-encoded XML output would be as follows instead: XML <\/String1> <\/String2> value 1 & value 2<\/String3> <\/String4> <\/CONTENT> #### 3.2.2 Alternative Way to Prevent the Escaping There is another way to prevent the escaping of special XML characters. You can define the property as one of the special XML types: %XML.String, %XML.FileCharacterStream, or %XML.GlobalCharacterStream. For these data type classes, CONTENT is "MIXED". Note that your application is responsible for ensuring that the property value is valid for the scenario in which it will be used; the %XML.String and other classes do not provide this validation. ### 3.3 Handling the UTC Time Zone Indicator For XML-enabled classes, you can specify whether to use the UTC time zone indicator when importing from XML documents. Similarly, you can specify whether to include the UTC time zone indicator on export. To do so, specify the XMLTIMEZONE parameter. Use one of the following values: - "UTC" — In this case, when you import elements with xsd:time or xsd:dateTime, the data is converted to UTC time. This is the default behavior. - In compliance with the XML Schema specification, InterSystems IRIS XML support treats the time zone indicator as a pure duration and ignores any named time zones such as EDT. "IGNORE" — In this case, the UTC time zone indicator is ignored when you import elements with xsd:time or xsd:dateTime. On export, UTC time is always used. The XMLTIMEZONE parameter controls the UTC zone indicator is included. Consider the following class: Class Definition Class ResearchXForms.UTC Extends (%Persistent, %XML.Adaptor) { Parameter XMLNAME = "Demo"; Property Time1 As %Time; Property Time2 As %Time(XMLTIMEZONE = "IGNORE"); Property TimeStamp1 As %TimeStamp; Property TimeStamp2 As %TimeStamp(XMLTIMEZONE = "IGNORE"); } XML output for this class might be as follows: XML 17:52:06Z<\/Time1> 17:52:06<\/Time2> 1976-02-18T17:52:06Z<\/TimeStamp1> 1976-02-18T17:52:06<\/TimeStamp2> <\/Demo> ### 3.4 Projecting the Value in DISPLAYLIST For properties of type %String (or any subclass), the XML projection can use the DISPLAYLIST parameter. Simple properties can specify the DISPLAYLIST and VALUELIST parameters. The VALUELIST parameter specifies a list of possible values for the property; this defines an enumerated property . Often you also specify the DISPLAYLIST parameter, which specifies the corresponding v alues to display. By default, the XML projection uses the value contained in the object, which is one of the values specified by VALUELIST. For properties of type %String, the XMLLISTPARAMETER parameter is meant to indicate which parameter contains the list of alternative values to use in the projection. Typically, you set this equal to "DISPLAYLIST". For example, consider the following data type class: Class Definition Class xmldisplaylist.MyEnumString Extends %String { Parameter VALUELIST = ",a,b,c"; Parameter DISPLAYLIST = ",apples,bananas,chocolate"; Parameter XMLLISTPARAMETER = "DISPLAYLIST"; } Also consider the following class, which uses the preceding data type class: Class Definition Class xmldisplaylist.Demo Extends (%RegisteredObject, %XML.Adaptor) { Property Property1 As MyEnumString; Property Property2 As MyEnumString(DISPLAYLIST = ",red,green,blue", VALUELIST = ",r,g,b"); } The following shows an example of the XML representation of an instance of this class: Controlling the Line Endings of Imported Stream Properties XML chocolate<\/Property1> red<\/Property2> <\/Demo> In contrast, if the data type class did not specify the XMLLISTPARAMETER parameter, the XML representation would be as follows: XML c<\/Property1> r<\/Property2> <\/Demo> ### 3.5 Controlling the Line Endings of Imported Stream Properties For each property that is a character stream, you can control the line endings in the stream when you import from XML. To do so, you set the XMLSTREAMMODE property parameter, which can have either of the following values (not case- sensitive): - If XMLSTREAMMODE equals "block" (the default), the normalized XML data is copied unchanged to the stream. The LineTerminator property of the stream is set to $CHAR(10), which makes the import compatible with any traditional newline sequence ($CHAR(10), $CHAR(13), $CHAR(13,10)). - If XMLSTREAMMODE equals "line", the XML data is broken into lines separated by the character given by the LineTerminator property of the stream; see %Library.AbstractStream. For example, suppose that we have the following data: ... <\/Stream1> ... We import this data into an object that has a Stream1 property of type %Stream.GlobalCharacter. By default, XMLSTREAMMODE is "block" for the property. After we import data, this property will contain the following data: this is a line this is another line this is another line If we set XMLSTREAMMODE equal to "line" for this property, and reimported the data, this property would contain the following data: this is a line this is another line this is another line In this case, the line endings are determined by the LineTerminator property of the stream class. This property equals $char(13,10) for %Stream.GlobalCharacter. ### 3.6 Specifying a Default Date\/Time Value For the %PosixTime, %TimeStamp, and %DateTime data type classes, the XMLDEFAULTVALUE parameter specifies the value to use if the date fails validity check by $zdatetimeh. By default, in such a case, a null string is used, and this results in an error when you import data via XMLImport(). Specify a valid value for the class. For example, for %TimeStamp, and %DateTime, specify a date in YYYY-MM-DD HH:MM:SS.nnnnnnnnn format, starting with any year after 1841. For example: 1841-01-1 00:00:00 XML does not permit nonprinting characters, specifically characters belo w ASCII 32 (except for carriage return, line feed, and tab). If you need to project a property to XML and that property contains any of these nonprinting characters, that property must be of type %Binary or %xsd.base64Binary (which is equivalent). This value is automatically converted to base–64 encoding on export to XML (or automatically converted from base–64 encoding on import). This topic discusses how to handle empty strings and null values. The XML examples in this topic are in literal format. Class and Property Parameters Discussed on This Page - XMLUSEEMPTYELEMENT - XMLIGNORENULL - XMLNILNOOBJECT - XMLNIL ### 4.1 Default Projections of Empty Strings and Null Values The following table summarizes the default XML projections of empty strings and null values. Note that the XML projections are analogous to the SQL projections, which are also shown here for comparison. Table 4–1: Default SQL and XML Projections of Empty Strings and Null Values InterSystems IRIS Value Default Projection to XML Projection to SQL $char(0) Empty element or attribute "" No projection SQL empty string SQL NULL value The following sections describe how these projections work upon export and import, and provide details on your options for controlling these projections. ### 4.2 Exporting Values The following table lists the ways in which empty strings and null values can be exported from XML-enabled objects to XML documents, for a property that is projected to XML as an element: Table 4–2: Exporting Empty Strings and Null Values for a Property Projected to XML as an Element Details of XML-Enabled Class Property equals "" Class specifies default values for XMLIGNORENULL and XMLNIL Exported XML document does not contain an element that corresponds to this property Class specifies XMLIGNORENULL=1 Exported document contains an empty element that corresponds to this property; see the subsection Class specifies XMLNIL=1 (and XMLIGNORENULL is not 1) Exported document contains an empty element that corresponds to this property and this empty element specifies xsi:nil="true" Property equals $char(0) Exported document contains an empty element that corresponds to this property; see the subsection The details are similar for a property projected as an attribute: Table 4–3: Exporting Empty Strings and Null Values for a Property Projected to XML as an Attribute Details of XML-Enabled Class Property equals "" Class specifies default values for the parameters described in this table XMLIGNORENULL=1 XMLNIL=1 (and XMLIGNORENULL is not 1) Exported XML document does not contain an attribute that corresponds to this property Exported document contains an empty attribute that corresponds to this property. For example: PropName="" Exported XML document does not contain an attribute that corresponds to this property (same as the default scenario) Property equals $char(0) Exported document contains an empty attribute that corresponds to this property #### 4.2.1 Controlling the Form of an Empty Element By default, InterSystems IRIS® data platform writes an empty element with an opening tag and a closing tag. For example: XML <\/PropName> You can instead cause InterSystems IRIS to write a self-closing empty element (which is equivalent). For example: XML To do so, specify the XMLUSEEMPTYELEMENT class parameter as 1. The default for this parameter is 0. Importing Values #### 4.2.2 Details for XMLIGNORENULL, XMLNIL, and XMLUSEEMPTYELEMENT XMLIGNORENULL Used during export to XML (and when writing SOAP messages), this parameter controls whether to ignore null strings (rather than exporting them). This parameter is a class parameter in all XML-enabled classes. XMLIGNORENULL can equal 0 (the default), 1, "INPUTONLY", or "RUNTIME" (not case-sensitive). The XMLIGNORENULL class parameter is inherited by subclasses. XMLNIL Used during export to XML (and when writing SOAP messages), this parameter controls the use of the xsi:nil attribute for null strings. This parameter is a class parameter and a property parameter in all XML-enabled classes; the property parameter takes precedence. XMLNIL can equal 0 (the default) or 1. The XMLNIL class parameter is not inherited by subclasses. The XMLNIL property parameter is inherited. XMLUSEEMPTYELEMENT Used during export to XML (and when writing SOAP messages), this parameter controls whether InterSystems IRIS writes self-closing empty tags. This parameter applies in two scenarios: - If XMLUSEEMPTYELEMENT is 1 for a class, the parameter affects any string-valued properties that equal "" and that are projected as elements. Any such property is exported as a self-closing empty element. - If XMLUSEEMPTYELEMENT is 1 for a class, and none of the properties appear as elements in the XML export, then the parameter affects the form of the empty element corresponding to the class instance. This element is exported as a self-closing empty element. If XMLUSEEMPTYELEMENT is 1 in a class, the system generates slightly more code for that class. Also the XML processing for that class is slightly less efficient. ### 4.3 Importing Values The following table lists the ways in which InterSystems IRIS handles empty, null, or missing elements and attributes when it imports from XML into an XML-enabled object: Table 4–4: Importing XML Documents with Empty, Null, or Missing Elements and Attributes Details of XML-Enabled Class Class specifies default value for XMLNILNOOBJECT parameter Imported document does not contain the element or attribute In the imported document, the element or attribute is empty The property is not set The property is set equal to $char(0) Class specifies XMLNILNOOBJECT=1 In the imported document, the element is empty and specifies xsi:nil="true" - If the property is a literal-valued property, the property is not set - If the property is an object-valued property, the property is set to a new instance of the refer- enced class; no properties are set in this instance The property is not set Controlling the XML Element and Attribute Names There is a default correspondence between InterSystems IRIS® data platform class and property names and the names of the XML elements and attributes, and you can override these defaults. Note that InterSystems IRIS also supports the case in which an XML document contains multiple elements with the same name. See Special Topics. The XML examples in this topic are in literal format. Class and Property Parameters Discussed on This Page - XMLNAME - XMLTYPE - XMLITEMNAME - XMLKEYNAME ### 5.1 Default XML Element and Attribute Names The default correspondence between InterSystems IRIS 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 attrib ute. 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: Class Member Property "Quoted Property" As %String; This property is projected as the element 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. ### 5.2 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: Table 5–1:Tag for Object Projected as Top-Level Element XMLNAME Parameter of Class XMLType Parameter of Class Tag (Element or Attribute) Specified Not specified Ignored Specified Not specified Value of XMLNAME Value of XMLTYPE Short class name For information on XMLTYPE, see 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: XML

Jackson<\/City> PA<\/State> 27621<\/Zip> <\/Address> Suppose that you specify the XMLNAME parameter of the Sample.Address class. For example: Class Member Parameter XMLNAME = "HomeAddress"; In this case, the output would be as follows instead: XML Jackson<\/City> PA<\/State> 27621<\/Zip> <\/HomeAddress> You can override these parameters when you export objects to XML, as described in Using XML Tools. Controlling the Tags for Simple Properties ### 5.3 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 InterSystems IRIS 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: Class Member Property Zip As %String (XMLNAME = "PostalCode"); The output for the previous example would be as follows instead: XML Jackson<\/City> PA<\/State> 27621<\/PostalCode> <\/HomeAddress> Note that if a property is in turn another InterSystems IRIS 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: XML Zevon,Juanita Q.<\/Name> 1986-08-18<\/DOB>

Jackson<\/City> PA<\/State> 27621<\/Zip> <\/Address> <\/Person> The name of the

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: Class Member Property Address As MyApp.Address (XMLNAME = "EmployeeAddress"); The output for the previous example would be as follows instead: XML Zevon,Juanita Q.<\/Name> 1986-08-18<\/DOB> Jackson<\/City> PA<\/State> 27621<\/Zip> <\/EmployeeAddress> <\/Person> ### 5.4 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 an InterSystems IRIS object property named ColorOptions equals a list of three strings: "Red", "Green", "Blue". By default, this property corresponds to the following XML fragment: XML Red<\/ColorOptionsItem> Green<\/ColorOptionsItem> Blue<\/ColorOptionsItem> <\/ColorOptions> This shows the ColorOptionsItem subelement, which corresponds to an item in the list. The name for this subelement is determined as follows: Table 5–2:Tag for List Items XMLITEMNAME Parameter of Property XMLNAME Parameter of Property Tag (Element or Attribute) Specified Not specified Ignored Specified Not specified Value of XMLITEMNAME Value of XMLNAME with Item concatenated to the end 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. Controlling the Element and Attribute Names for Array-Type Properties ### 5.5 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 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: Class Member Property Tools As %ArrayOfDataTypes; 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: XML Hammer<\/ToolsItem> Monkey Wrench<\/ToolsItem> Screwdriver<\/ToolsItem> <\/Tools> This shows the ToolsKey attribute, which corresponds to the key of an array. The name of this attribute is determined as follows: Table 5–3:Tag for List Item XMLKEYNAME Parameter of Property XMLNAME Parameter of Property Name of Attribute That Contains the Key Specified Not specified Ignored Specified Value of XMLKEYNAME 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: Class Member Property Tools As %ArrayOfDataTypes(XMLNAME = "MyXMLName"); Then the same property would correspond to the following XML fragment: XML Hammer<\/MyXMLNameItem> Monkey Wrench<\/MyXMLNameItem> Screwdriver<\/MyXMLNameItem> <\/MyXMLName> Specifying Namespaces for Elements and Attributes XML elements and attributes can belong to different namespaces, and the XML Schema specification pro vides for multiple ways of controlling and representing namespace assignment. The %XML.Adaptor class provides the corresponding support for your XML documents. Also see Specifying the Namespaces for Types. The XML examples in this topic are in literal format. Class and Property Parameters Discussed on This Page - NAMESPACE - ELEMENTQUALIFIED - ATTRIBUTEQUALIFIED - XMLREF - REFNAMESPACE - XSDTYPE - XMLPREFIX ### 6.1 Overview This section provides a refresher on XML namespaces and an overview of how InterSystems IRIS® data platform objects are assigned to XML namespaces. #### 6.1.1 Namespace Refresher The general assumption in this documentation 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 e very 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: - Qualified , which means that the element or attribute is in the target namespace of the schema. - Unqualified , which has different meaning for elements and attributes. An unqualified element is in no namespace. An unqualified attrib ute is in the default namespace, if any, of its containing element. For each element and attribute that it defines, a schema indicates whether that item is qualified or unqualified. does this by a combination of the following pieces: The schema - The element can specify the elementFormDefault and attributeFormDefault attributes. This controls the default namespace assignment of any elements and attributes in the schema. The possible values are "qualified" and "unqualified". - These attributes are optional. The default for both of them is "unqualified". That is, by default if a element or attribute is used without a prefix, it is in no namespace. Second, the definition of an element or attrib ute can specify the form attribute, which indicates how that item is assigned to a namespace. The possible values are "qualified" and "unqualified". Consider the following XML document: XML qrstuv<\/String3> wxyz<\/String4> <\/s01:ClassB> 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: - The element is in mynamespace, because of two items: – – That is the namespace given by the default namespace declaration for this element and its immediate children (xmlns="mynamespace"). The element does not have a namespace prefix that w ould indicate some other namespace. - The String1 attribute is in mynamespace, because this attribute uses the s01 prefix, and the xmlns:s01 namespace declaration indicates that the s01 refers to the mynamespace namespace. - Because the schema uses the default for attributeFormDefault ("unqualified"), the String1 attribute would be in mynamespace even if it did not use a namespace prefix. - The element is in mynamespace, because this attribute uses the s01 prefix. - The and elements are not in any namespace, because of two items: – – The namespace declaration for the parent element indicates that the default namespace here is null (xmlns=""). These elements do not have a namespace prefix that w ould indicate some other namespace. The element is the namespace mynamespace, because that is the default namespace specified in its parent element. Specifying the Namespaces for Objects Treated as Global Elements #### 6.1.2 XML Namespaces and Classes In InterSystems IRIS 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 the documentation. #### 6.1.3 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. ### 6.2 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: - If the NAMESPACE parameter of the class is specified, the element is assigned to that namespace. - If the NAMESPACE parameter of the class is not specified, the element does not belong to an y namespace. You can, however, specify a namespace during export. See Writing XML Output from Objects. For example, consider the following class definition: 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: XML Isaacs,Rob G.<\/Name> 1981-01-29<\/DOB> <\/Person> ### 6.3 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. #### 6.3.1 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: - If the ELEMENTQUALIFIED class parameter is 1 for the parent class, the local elements are qualified, and the y are explicitly included in namespace of their parent element. - If the ELEMENTQUALIFIED class parameter is 0 for the parent class, the local elements are unqualified, and the y do not belong to any namespace. (You can, however, specify a namespace during export. See Writing XML Output from Objects.) ...namespaceA...ClassA...ClassB...ClassC...ClassA...ClassB...ClassC......nonamespace nonamespace namespaceA namespaceA Specifying the Namespaces for Properties Projected as 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. #### 6.3.2 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: a. If the property is a type and specifies the XSDTYPE class parameter, the element is in the namespace of the parent class. b. Otherwise, if the property class defines the NAMESPACE class parameter, the element is in the namespace of the property class. c. If the property class does not define either of these class parameters, the element is in no namespace. ClassZ......namespaceZ namespaceR ClassA... Note: The XMLREF property parameter replaces the XMLELEMENTREF property parameter. The XMLELEMENTREF parameter, however, will be supported indefinitely . ### 6.4 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 attrib utes are qualified by a namespace prefix; the possible v are as follows: alues - 0 (the default), which means that no namespace prefix is included. - 1, which means that a namespace prefix is included. 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 attrib ute is in that namespace. 2. Otherwise: a. If the property is a type and specifies the XSDTYPE class parameter, the attribute is in the namespace of the parent class. b. Otherwise, if the property class defines the NAMESPACE class parameter, the attribute is in the namespace of the property class. c. If the property class does not define either of these class parameters, the attrib ute is in no namespace. ClassZZ......ClassA[datatype]...ClassB[datatypeorobject]...ClassC[datatypeorobject]...namespaceZZ...namespaceB nonamespace Specifying Custom Prefixes for Namespaces ### 6.5 Specifying Custom Prefixes for Namespaces When you generate XML output for an object, the system generates namespace prefix es as needed. The first namespace prefix is s01, the next is s02, and so on. You can specify different prefix es. To do so, set the XMLPREFIX parameter in the class definitions for the XML-enabled objects themselv es. This parameter has two effects: - It ensures that the prefix you specify is declared in the XML output. That is, it is declared even if doing so is not necessary. - It uses that prefix rather than the automatically generated prefix that you w ould otherwise see. For example, suppose your class definition is as follo ws: Class Definition 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 Umansky,Jocelyn O.<\/Name> <\/Person> For information on exporting to XML, see Using XML Tools. ### 6.6 Recommendations To simplify development, debugging, and troubleshooting, InterSystems recommends the following practices: - If you need to specify namespaces, specify NAMESPACE in all your XML-enabled classes. Otherwise, the defaulting rules become complex. - If you need to control whether local elements are qualified, also specify the ELEMENTQUALIFIED parameter in all your XML-enabled classes. Controlling the Projection to XML Schemas For any XML-enabled class, there is an implicit XML schema for that class, which you can view. InterSystems IRIS® data platform provides ways to modify that schema. The XML examples in this topic are in literal format. Class and Property Parameters Discussed on This Page - CONTENT - DISPLAYLIST - VALUELIST - ESCAPE - MAXLEN - MINLEN - MINVAL - XMLFractionDigits - XMLTotalDigits - XMLLISTPARAMETER - XSDTYPE - XMLTYPE - SUPPRESSTYPEPREFIX ### 7.1 Viewing the Schema for an XML-Enabled Class To see the schema for a given XML-enabled class, you have two options: - You can use %XML.Schema and %XML.Writer to generate complete schema documents. For details, see Generating XML Schemas from Classes. - You can use the XMLSchema() class method of your XML-enabled class, which writes the XML schema for this class to the current device. This method does not write the XML declaration and ignores namespaces and thus has limited use. This method can be helpful, however, if you are interested only in the XML types. This topic primarily uses the XMLSchema() class method, because using it requires only a single line of code. #### 7.1.1 Example For example, consider the following class definitions: Class Definition Class GXML.Person Extends (%Persistent, %Populate, %XML.Adaptor) { Property Name As %Name; Property DOB As %Date(FORMAT = 5, MAXVAL = "+$h"); Property GroupID As %String (XMLPROJECTION="ATTRIBUTE"); Property OtherID As %String(XMLPROJECTION = "NONE"); Property Address As GXML.Address; Property Doctors As list Of GXML.Doctor; } The GXML.Address class is as follows: Class Definition Class GXML.Address Extends (%Persistent, %Populate, %XML.Adaptor) { Property Street As %String; Property City As %String; Property State As %String(MAXLEN = 2, PATTERN = "2u"); Property Zip As %String(MAXLEN = 10, PATTERN = "5n.1(1""-""4n)"); } And the GXML.Doctor class is as follows: Class Definition Class GXML.Doctor Extends (%Persistent, %Populate, %XML.Adaptor) { Property Name As %Name; } To see the schema for the GXML.Person class, enter the following command in the Terminal: ObjectScript do ##class(GXML.Person).XMLSchema() You then see the following: <\/s:sequence> <\/s:complexType> <\/s:sequence> <\/s:complexType> <\/s:sequence> <\/s:complexType> <\/s:sequence> <\/s:complexType> Notice the following: - The schemas for the ,

projecting-objects-to-xml