%XML.Adaptor

ATTRIBUTEQUALIFIED controls the format of exported XML by controlling whether attributes are qualified by a prefix. Possible values are 1 for qualified, 0 for not qualified(default). The ATTRIBUTEQUALIFIED specification should be based on the ATTRIBUTEFormDefault attribute of the schema that defines the type.

NOTE: Direct use of XMLExport method does not support the ATTRIBUTEQUALIFIED The export must be done using %XML.Writer or SOAP support.

ELEMENTQUALIFIED controls the format of exported XML. The ELEMENTQUALIFIED specification should be based on the elementFormDefault attribute of the schema that defines the type. To maintain compatibility, ELEMENTQUALIFIED will default to 1 (true) for literal format export and will default to 0 (false) for encoded or encoded12 format export. These were the values always previously assumed for the elementFormDefault attribute.

NOTE: Direct use of XMLExport method does not support the ELEMENTQUALIFIED. The export must be done using %XML.Writer or SOAP support.

NAMESPACE specifies the XML namespace to be used when projecting the class to XML. If NAMESPACE = "", the default namespace is used for the XML schema is used as the namespace for his class.

SUPPRESSTYPEPREFIX allows the type name that refers to this class when used in an xsi:type attribute to have no prefix. The prefix may be left out of the type's QName by setting SUPPRESSTYPEPREFIX=1. This usage corresponds to an included schema for this class which has no targetNamespace. The default is false which will include the prefix in the type QName.

XMLDEFAULTREFERENCE specifies the default value of the XMLREFERENCE property parameter that specifies how to project references to XML. XMLREFERENCE may be specified for each property to override this default value. Possible values of XMLDEFAULTREFERENCE are SUMMARY, COMPLETE, ID, OID, GUID.

SUMMARY indicates that only the summary properties of the referenced class are used to represent the reference. SUMMARY is the default. Note that by default all properties of the referenced class are in the summary.

COMPLETE indicates that all properties of the referenced class are used to represent the reference.

ID indicates that the id of a persistent or serial class is used to represent the reference.

OID indicates that the oid of a persistent or serial class is used to represent the reference. The form of the oid will be classname,id.

GUID indicates the GUID of a persistent class is used to represent the reference.

If this parameter is true then XML-enabling methods will be generated. Otherwise, the method generators do not produce a runnable method.

The XMLFORMAT parameter controls the generation of the XMLExport and XMLImport methods for XML enabled classes to include code for only literal or only encoded format. This allows the generated routines to be significantly smaller since usually both formats are not needed.

If XMLFORMAT="Literal", then only support for literal format import and export is generated.

If XMLFORMAT="Encoded", then only support for SOAP encoded format import and export is generated.

The default is to generate support for both literal and encoded format.

The XMLIGNOREINVALIDATTRIBUTE parameter allows the programmer to control handling of unexpected attributes in the XML input. By default (XMLIGNOREINVALIDATTRIBUTE = 1), will ignore unexpected attributes. If XMLIGNOREINVALIDATTRIBUTE is set = 0, then an unexpected attribute will be treated as an error.

The XMLIGNOREINVALIDTAG parameter allows the programmer to control handling of unexpected elements in the XML input. The XMLIGNOREINVALIDTAG parameter will only take affect if XMLSEQUENCE = 0 (the default). By default (XMLIGNOREINVALIDTAG = 0), will treat an unexpected element as an error. If XMLIGNOREINVALIDTAG is set = 1 and XMLSEQUENCE = 0, then unexpected elements will be ignored.

XMLIGNORENULL allows the programmer to override the default XML handling of empty strings for properties of type %String. By default (XMLIGNORENULL = 0), empty strings in the XML input are stored as $c(0) and $c(0) is written to XML as an empty tag. A missing tag in the XML input is always stored as "" and "" is always output to XML as no tag.

If XMLIGNORENULL is set = 1, then both missing tags in the XML and empty strings are input as "", and both "" and $c(0) are output as empty tags (i.e. <tag></tag>).

If XMLIGNORENULL is set = "inputonly", then both missing tags in the XML and empty strings are input as "". Output of "" and $c(0) are for XMLIGNORENULL = 0: $c(0) is output as an empty tag (i.e. <tag></tag>) and "" is output as no tag.

If XMLIGNORENULL = "runtime" (runtime is not case sensitive), then the behavior of XMLIGNORENULL is determined by the format parameter of XMLExport, XMLImport and %XML.Reader.OpenFile. The default behavior for XMLIGNORENULL="runtime is the same as XMLIGNORENULL=0. Adding "ignorenull" to the format argument changes the behavior to that of XMLIGNORENULL=1. "ignorenull" shoud be separated by a comma from literal/encoded part of the format. Example values for format are "", ",ignorenull", "literal,ignorenull" and "encoded,ignorenull". Note that "inputonly" is equivalent to using ,ignorenull for XMLExport and not for %XML.Reader.

XMLINCLUDEINGROUP allows the programmer to control whether a class is included in the group of subclasses of a base class that are represented by one XML element. By default (XMLINCLUDEINGROUP = 1), will include the class. Classes may excluded by specifying XMLINCLUDEINGROUP=0.

If the XMLINHERITANCE parameter is set to "LEFT", then in the case of multiple inheritance XMLImport and XMLExport generate code to order the properties from the left-most class first followed by properties in left to right order of the super class. XMLINHERITANCE"LEFT" is the default. XMLINHERITANCE"RIGHT" is included to use the old right to left property order which is inconsistent with the order in WSDLs and XSDs produced by InterSystems IRIS SOAP and XML libraries.

This parameter provides the default XMLNAME for the class. If it is empty then the class name will be used to construct a default XML name. The default XMLNAME is used as the top level tag when exporting objects and the export context did not provide an XML container name.

The XMLNIL class parameter controls the use of xsi:nil by XMLExport and nillable attribute by XMLSchema. If XMLNIL=1, then properties of the class with value = "" (null) are XMLExported as <propname xsi:nil="true" />. The exception is that string properties with value = "" are always exported as <propname /> if XMLIGNORENULL=1 even if XMLNIL=1.

The XMLNILNOOBJECT parameter allows creation of an object to be skipped for elements with xsi:nil="true".

The default of XMLNILNOOBJECT = 0 will always create an object for an element with xsi:nil="true".

If XMLNILNOOBJECT = 1, then elements with xsi:nil="true" and no attributes specified will be skipped, i.e. the value of the property will remain "".

The XMLPREFIX parameter controls the prefix to be used for the XML namespace that is given by the NAMESPACE parameter.

If the XMLSEQUENCE = 1, then the order of the XML elements must match the order of the class properties. This allows us to deal with XML where the same field appears multiple times and is distinguished by the order.

The summary fields to be used when an object is referenced are specified by the object's XMLSUMMARY class parameter. XMLSUMMARY is a comma separated, unordered list of properties to include in the object summary. Properties are mapped to the XML in the order that the properties appear in the class not in the list order. If XMLSUMMARY is not specified, then all properties are included in the summary.

This parameter provides the default XMLTYPE for the class. If it is empty then the class name will be used to construct a default XML type.

The default XMLTYPE is used when naming and referencing this type in a schema and the schema context did not provide an XML type name.

If the XMLUNSWIZZLE parameter is set to 1, then single object references in this persistent or serial classes will be unswizzled after being exported. List elements will continue to always be unswizzled after export independent of this parameter.

If the XMLUSEEMPTYELEMENT parameter is set to 1, then the empty element shorthand () is used to represent empty elements. Otherwise is used. The parameter applies to the class in which it appears when none of its properties appear as elements in the XML export, and for any empty xsd:string valued child elements. The XMLUSEEMPTYELEMENT parameter does to apply to objects referenced as properties. The class for a referenced object must have its own XMLUSEEMPTYELEMENT parameter.

Write the DTD to the current device for this XML enabled class serialized as an XML document.

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type. DTDs may only be generated for the default "literal" format.

input=true means that the DTD for the input XML will be generated, otherwise the DTD for the output XML will be generated. The default is input=false. Normally, this argument is not relevant since the all properties of a class participate in input and output.

The dtdlist argument is used internally to track DTD generation for referenced objects.

Serialize an XML enabled class as an XML document and write it to the current device.

IMPORTANT: The XMLExport method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToDevice() method.

The supported arguments for XMLExport are:

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique encoding in the future.

**********
**********
All the following arguments are for internal use only and may change
**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and ObjectScript types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

local specifies if the element is treated as a local element. A global element is specified by a false value of local which can be either 0 to represent a global element in the namespace specified by the namespace argument or a string which is the namespace to which the global element belongs. The default for local is 0.

If the class is to be exported as an XOP package for use by SOAP MTOM, mimeAttachments is the MIME part which contains the list of MIME parts for all the attachments in the XOP package.

Serialize an XML enabled class as an XML document and appends it to a stream.

IMPORTANT: The XMLExportToStream method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToStream() method.

The supported arguments for XMLExportToStream are:

export is the exported stream. If export is the oref of a stream, the XML document will be written to this existing stream at the current position. If export is "", then a new %FileCharacterStream will be created to contain the XML document and its oref returned. In this case, export must be passed by reference.

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique encoding in the future.

**********
**********
All the following arguments are for internal use only and may change

**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and ObjectScript types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

Serialize an XML enabled class as an XML document and write it to a string.

IMPORTANT: The XMLExportToString method does not directly support many of the XML parameters. If you want control of the format of the export, do not use this method. Instead create an instance of %XML.Writer and use its OutputToString() method.

The supported arguments for XMLExportToString are:

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique encoding in the future.

**********
**********
All the following arguments are for internal use only and may change
**********
**********
namespaces is the %XML.Namespaces class instance for this XML document. Instead of namespaces typesPrefix is still supported for compatability and is the optional namespace prefix to be used for all element tags and ObjectScript types.

attrs is a multidimensional array of extra attributes for the top node:
attrs is number of attributes
attrs(i) is name of ith attribute
attrs(i,0) is value of the ith attribute

If the createId is not "", then an id field with this id value is created.

If the typeAttr is not "", then add a type attribute to the top element if the this class's name is not typeAttr.

The idlist and oreflist arguments are used internally to track deferred object export and should normally not be specified.

initialIndent is the initial indentation for use when the format is indent.

local specifies if the element is treated as a local element. Default is 0 (false).

Get an instance of an XML enabled class.

You may override this method to do custom processing (such as initializing the object instance) before returning an instance of this class. However, this method should not be called directly from user code.

Arguments:

document is the document with %XML.Node or macros in %xmlDOM.inc.

nodeId is a node id of the node which defines this object. An %XML.Node object may be obtained for this node using document.GetNode(nodeId)

containerOref is the containing object instance when called from XMLImport and is "" when called from %XML.Reader for Correlate'd objects.

Write an XML Schema fragment to the current device which describes an XML enabled class and dependent classes. The output of the XMLSchema method is not a complete sachema. The %XML.Schema class must be used to output a complete schema. In order to override schema generation the XMLSchemaType method should be overridden -- not the XMLSchema method.

top is the optional tag to be used for the top-level tag.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. In addition, the value "element" is the same as "literal" formatting with an element at the top level. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique encoding in the future.

namespacePrefix is the optional namespace prefix to be used for the namespace in which this schema is generated.

input=true means that the schema for the input XML will be generated, otherwise the schema for the output XML will be generated. The default is input=false. Normally, this argument is not relevant since the all properties of a class participate in input and output.

refOnly=true means that only the portions of the schema for referenced types are generated. The schema for this class is not generated. Default is refOnly=false that generates the entire schema.

The schema argument is used internally to track schema generation for referenced objects.

Get the namespace to which this class belongs for use in schema generation. The namespace is returned as a string or $c(0) is returned to indicate that the namespace of the referencing class should be used. This method should not normally need to be overridden.

Add a complexType to the schema that is respresented by an %XML.Schema instance.

schemaInstance is the %XML.Schema class instance that is used to build the schema.

node is the %XML.Node class instance for the schema that includes this class.

top is the optional override of the type name.

format is the parameter formatting type ("literal", "encoded" or "encoded12") to be used for this object. In addition, the value "element" is the same as "literal" formatting with an element at the top level. The default value for format is "" which currently is the same as the "literal" formatting, but may be a unique encoding in the future.

summary=true if summary type is to be created.

input=true means that the schema for the input XML will be generated, otherwise the schema for the output XML will be generated. The default is input=false. Normally, this argument is not relevant since the all properties of a class participate in input and output.

refOnly=true means that only the portions of the schema for referenced types are generated. The schema for this class is not generated. Default is refOnly=false that generates the entire schema.