%XML.Adaptor
Class %XML.Adaptor [ Abstract, Not ProcedureBlock, PropertyClass = %XML.PropertyParameters, System = 2 ]
For details on using this class, see Projecting Objects to XML.
Subclasses of %XML.Adaptor are said to be "XML enabled" and may be projected as either pure XML or as the return value or arguments of a SOAP method.
The methods that are generated for XML enabled classes are specified here. The class parameters that control the generation of these methods are defined here.
The property parameters that control the generation of code for each property of an XML enabled class are defined in %XML.PropertyParameters.
Parameters
XMLENABLED
Parameter XMLENABLED = 1;
If this parameter is true then XML-enabling methods will be generated. Otherwise, the method generators do not produce a runnable method.
XMLNAME;
Parameter XMLNAME;
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.
XMLTYPE;
Parameter XMLTYPE;
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.
XMLMAPPING
Parameter XMLMAPPING As STRING [ Constraint = ",SEQUENCE,TYPE", Flags = ENUM, Internal ];
The XMLMAPPING parameter specifies the mapping between a class and a XML schema grouping. The default value, "type", maps a class to an XML schema type. The value "sequence" maps a class to an XML schema sequence group.
XMLSUMMARY;
Parameter XMLSUMMARY;
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.
XMLIGNORENULL
Parameter XMLIGNORENULL As STRING [ Constraint = ",0,1,inputonly,runtime", Flags = ENUM ] = 0;
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.
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.
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.
XMLNIL
Parameter XMLNIL As STRING [ Constraint = ",0,1", Flags = ENUM ];
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
XMLNILNOOBJECT
Parameter XMLNILNOOBJECT As STRING [ Constraint = ",0,1", Flags = ENUM ];
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 "".
XMLIGNOREINVALIDTAG
Parameter XMLIGNOREINVALIDTAG As BOOLEAN = 0;
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.
XMLIGNOREINVALIDATTRIBUTE
Parameter XMLIGNOREINVALIDATTRIBUTE As BOOLEAN = 1;
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.
XMLINCLUDEINGROUP
Parameter XMLINCLUDEINGROUP As BOOLEAN = 1;
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.
XMLSEQUENCE
Parameter XMLSEQUENCE = 0;
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.
XMLDEFAULTREFERENCE
Parameter XMLDEFAULTREFERENCE As STRING [ Constraint = "SUMMARY,COMPLETE,ID,OID,GUID", Flags = ENUM ];
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.
NAMESPACE
Parameter NAMESPACE As STRING;
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.
ATTRIBUTEQUALIFIED
Parameter ATTRIBUTEQUALIFIED As BOOLEAN;
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
Parameter ELEMENTQUALIFIED As BOOLEAN;
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.
SUPPRESSTYPEPREFIX
Parameter SUPPRESSTYPEPREFIX As BOOLEAN;
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.
XMLFORMAT
Parameter XMLFORMAT As STRING;
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.
XMLPREFIX
Parameter XMLPREFIX As STRING;
The XMLPREFIX parameter controls the prefix to be used for the XML namespace that is given by the NAMESPACE parameter.
XMLUNSWIZZLE
Parameter XMLUNSWIZZLE As BOOLEAN;
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.
XMLINHERITANCE
Parameter XMLINHERITANCE As STRING [ Constraint = "LEFT,RIGHT", Flags = ENUM ];
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.
XMLUSEEMPTYELEMENT
Parameter XMLUSEEMPTYELEMENT As BOOLEAN;
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.
Methods
XMLBeforeExport
Method XMLBeforeExport() [ Abstract, Internal, ServerOnly = 1 ]
Callback at the beginning of XMLExport This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
XMLAfterExport
Method XMLAfterExport(status As %Status) [ Abstract, Internal, ServerOnly = 1 ]
Callback at the end of XMLExport This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
%XMLGenerate
ClassMethod %XMLGenerate() [ CodeMode = generator, GenerateAfter = (XMLBeforeExport, XMLAfterExport), Internal, ServerOnly = 1 ]
%XMLGenerate controls the generation of the other methods in %XML.Adaptor. If XMLGenerate is overridden, then XML meta data and the other generator methods of %XML.Adaptor will not be created.
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
XMLNew
ClassMethod XMLNew(document As %XML.Document, node As %Integer, containerOref As %RegisteredObject = "") As %RegisteredObject [ CodeMode = generator, GenerateAfter = %XMLGenerate, ServerOnly = 1 ]
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.
XMLIsObjectEmpty
Method XMLIsObjectEmpty(ignoreNull As %Boolean) As %Boolean [ CodeMode = generator, GenerateAfter = %XMLGenerate, Internal, ServerOnly = 1 ]
Test if a serial class has the values of the initial empty class.
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
XMLImport
Method XMLImport(top As %String, format As %String, namespace As %String, handler As %XML.Document, node As %Integer, ByRef idlist, keynameattr As %String, mimeAttachments As %ListOfObjects) As %Status [ Internal, ServerOnly = 1 ]
Import an XML document as a class.
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
top is the optional tag to be expected for the top-level tag.
format is the parameter formatting type ("literal", "encoded", "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.
namespace is the uri of the target namespace for this document that is being imported.
handler is the %XML.Document that holds the imported XML tree.
The idlist argument is used internally to track nodes identified by an id attribute for later reference.
keynameattr is the key name attribute specified for array elements.
If the class is to be imported from an XOP package for use by SOAP MTOM, mimeAttachments is the list of MIME parts for all the attachments in the XOP package.
XMLImportInternal
Method XMLImportInternal() As %Status [ CodeMode = generator, GenerateAfter = %XMLGenerate, Internal, ServerOnly = 1 ]
XMLImportInternal is internal method used by XMLImport
XMLImportAttributes
Method XMLImportAttributes() As %Status [ CodeMode = generator, GenerateAfter = %XMLGenerate, Private, ServerOnly = 1 ]
Import attributes of an XML document as a class.
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.
XMLExport
Method XMLExport(top As %String, format As %String, namespaces As %XML.Namespaces, attrs, createId As %String, typeAttr As %String, ByRef oreflist, ByRef idlist, initialIndent As %String, local As %Boolean, mimeAttachments As %Net.MIMEPart) As %Status [ ServerOnly = 1 ]
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.
XMLExportInternal
Method XMLExportInternal() As %Status [ CodeMode = generator, GenerateAfter = %XMLGenerate, Internal, ServerOnly = 1 ]
XMLExportInternal is internal method used by XMLExport
XMLExportToString
Method XMLExportToString(ByRef export As %String, top As %String, format As %String, namespaces As %XML.Namespaces, attrs, createId As %String, typeAttr As %String, ByRef oreflist, ByRef idlist, initialIndent As %String) As %Status [ ProcedureBlock = 1, ServerOnly = 1 ]
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).
XMLExportToStream
Method XMLExportToStream(ByRef export As %Stream.Object, top As %String, format As %String, namespaces As %XML.Namespaces, attrs, createId As %String, typeAttr As %String, ByRef oreflist, ByRef idlist, initialIndent As %String) As %Status [ ProcedureBlock = 1, ServerOnly = 1 ]
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.
XMLDTD
ClassMethod XMLDTD(top As %String, format As %String, input As %Boolean, ByRef dtdlist) As %Status [ CodeMode = generator, ServerOnly = 1 ]
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.
XMLSchema
ClassMethod XMLSchema(top As %String = "", format As %String = "", namespacePrefix As %String = "", input As %Boolean = 0, refOnly As %Boolean = 0, ByRef schema) As %Status [ CodeMode = generator, ServerOnly = 1 ]
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.
XMLSchemaType
ClassMethod XMLSchemaType(schemaInstance As %XML.Schema, node As %XML.Node, top As %String = "", encoded As %Boolean, summary As %Boolean = 0, input As %Boolean = 0, refOnly As %Boolean = 0) As %Status [ Abstract, ProcedureBlock = 1, ServerOnly = 1 ]
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.
XMLSchemaNamespace
ClassMethod XMLSchemaNamespace() As %String [ ProcedureBlock = 1, ServerOnly = 1 ]
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.
XMLGetSchemaImports
ClassMethod XMLGetSchemaImports(ByRef imports, ByRef classes) As %Status [ CodeMode = generator, Internal, ServerOnly = 1 ]
Get the import elements required for a schema. XMLGetSchemaImports is used to get the import elements needed for %XML.DataSet in a WSDL file.
The schema is is returned as a local array of where each node represents a required import:
imports(schemaNamespace)=schemaLocation
where schemaLocation may be "" for commonly known schemas such as http://www.w3.org/2001/XMLSchema
This method is for internal use only. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.