Chapter 29 Generates classes from an XML schema

Studio provides a wizard that reads an XML schema (from a file or URL) and generates a set of XML-enabled classes that correspond to the types defined in the schema. All classes extend % xml.adaptor. Specify a package to contain the class and various options to control the details of the class definition.

A wizard can also be used as a class method or as a class method. Internally, the SOAP wizard uses this method when reading a WSDL document and generating a Web client or Web service;

Note: The XML declaration of any XML document used should indicate the character encoding of the document, and the document should be encoded as declared. If character encodings are not declared, InterSystems IRIS will use the default values described in “Input and Output Character encodings” earlier in this book. If these defaults are incorrect, modify the XML declaration so that it specifies the actual character set to use.

Using the wizard

To use the XML Schema wizard, do the following:

  1. Choose Tools > Add-ins > XML Schema Wizard.

  1. On the first screen, specify the XML schema to use.

Do one of the following:

  • For the Schema File Schema File, select Browse to select the XML Schema File.
  • For urls, specify the URL of the schema.

  1. Select Next.

The next screen displays the mode so that you can verify that the correct mode was selected.

  1. You can select the following options:
  • Keep Empty Classes, which specifies whether to Keep unused Classes without attributes.

If you select this option, the class will not be deleted at the end of the wizard; Otherwise, they are deleted.

  • Create No Array Properties Controls whether the wizard generates Array Properties.

If you select this option, instead of generating array properties, the wizard generates another form.

  • Generates the XMLNIL property parameter for nullable elements, which controls whether the wizard specifies the XMLNIL property parameter for properties applicable in the generated class.

This option applies to every attribute that corresponds to an XML element specified with nillable=”true”. If this option is selected, the wizard adds XMLNIL=1 to the property definition. Otherwise, do not add this parameter. For more information on this parameter, see “Handling Empty Strings and Null Values” for projecting objects into XML.

  • Is generated for nullable elementsXMLNILNOOBJECTProperty parameter, which controls whether the wizard specifies properties that are applicable in the generated classXMLNILNOOBJECTProperty parameter.

This option applies to every attribute that corresponds to an XML element specified with nillable=”true”. If this option is selected, the wizard adds XMLNILNOOBJECT=1 to the property definition. Otherwise, do not add this parameter. For more information on this parameter, see “Handling Empty Strings and Null Values” for projecting objects into XML.

  1. Select Next.

The next screen shows some basic information about the options for the class to be generated.

  1. On this screen, specify the following options:
  • If you want the generated classes to be compiled by wizard, select Compile Generated Classes.
  • You can select Add NAMESPACE Class Parameter to specify this parameterNAMESPACEParameters.

In this case, the NAMESPACE is set to the value of targetNamespace in the schema.

If this option is not set, NAMESPACE is not specified.

This option is recommended in all cases, because each XML-enabled class should be assigned to an XML namespace. (However, this option can be cleared for backward compatibility.)

  • If you want to generate classes that are persistent, select Create Persistent Classes. And then the class extends%Persistent.

You can change this later in the wizard for individual classes.

  • If you generate a persistent class, can you choose how to handle it by another<complexType> bthe<sequence>Consisting of a<complexType>A. When the wizard generates an include propertyaThe property has three possible forms.

It can be defined as a list of objects, a one-to-many relationship (the default), or a parent-child relationship. The following table summarizes these options:

Use relationships for collection properties in persistence classes Add indexes to multi-pair relationships Use father-child relationships The form of the generated property A
selected (default) not selected not selected A one-to-many relationship without an index
selected (default) selected not selected A one-to-many relationship with an index on multiple sides
selected (default) If Use parent-child relationship is selected, this option is ignored selected Father and son
not selected not selected not selected List of objects

In addition, if you do not choose to use parent-child relationships, you can choose to add the %OnDelete method to the class for cascading deletions. If selected, when the wizard generates class definitions, it includes the implementation of the %OnDelete() callback method in those classes. The generated %OnDelete() method deletes all persistent objects referenced by the class. If you do select parent-child relationship, do not select this option. The father-child relationship already provides similar logic.

Note: If you modify the generated class, be sure to modify the %OnDelete() callback method as needed.

If persistent classes are generated, the wizard can add temporary properties to each object type class so that the InterSystems IRIS internal identifier can be projected onto the object. The options are as follows:

  • None- If selected, the wizard will not add any of the properties described here.
  • Use Id – If selected, the wizard adds the following properties to each object type class:
Property %identity As %XML.Id (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
Copy the code
  • Use Oid – If selected, the wizard adds the following properties to each object type class:
Property %identity As %XML.Oid (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
Copy the code
  • Use GUID- If this option is selected, the wizard adds the following properties to each object type class:
Property %identity As %XML.GUID (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
Copy the code

The table at the bottom lists the XML namespaces in the schema. Here, specify the package that contains the class for the XML namespace shown in this line. To do this, specify the package name for the row in the package name field.

  1. Choose the next step.
  2. On the next screen, specify the following options:
  • Java Enabled – If this option is selected, each class includes a Java map.
  • Data Population – If this option is selected, it is removed%XML.AdaptorIn addition, each class also inherits%Populate.
  • SQL Column Order- If selected, each attribute will beSqlColumnNumberThe keyword specifies a value so that the properties are in the same order in SQL as they are in the schema.
  • No Sequence Check- If this option is selected, the wizard will generate the classXMLSEQUENCEThe parameter is set to 0. This option is useful in some cases where the order of the elements of an XML file differs from the XML schema.

By default, the XMLSEQUENCE parameter is set to 1 in the generated class. This ensures that the attributes are included in the class definition in the same order as in the schema.

  • XMLIGNORENULL- If this option is selected, the wizard willXMLIGNORENULL=1Add to the class definition. Otherwise, it does not add this parameter.
  • Use Streams for Binary – If this option is selected, the wizard willXSD: base64BinaryType for any element generated%Stream.GlobalBinaryType property. If this option is cleared, the property is of type%xsd.base64Binary.

Note that the wizard ignores any attributes of type XSD: base64Binary.

  • Below the check box, the table lists the classes that the wizard will generate. For each class, make sure you set it up properlyExtensions/Type. Here, you can select one of the following options:
    • Last classPersistent– If this option is selected, the class is persistent.
    • Serial– If this option is selected, the class is sequence class.
    • Registered Object– If this option is selected, the class is registered object class.

All generated classes also extend % xml.adaptor.

  • In the right column of the table, select an index for each attribute that should be indexed.
  1. Select Finish.

The wizard will then generate these classes and compile them as needed.

For attributes of these classes, if the name of the corresponding element in the schema begins with an underscore (_), the attribute name begins with a percent sign (%).

Generate classes programmatically

The XML schema wizard can also be used as the process() method of the % xml.utils.schemareader class. To use this method, do the following:

  1. create%XML.Utils.SchemaReaderThe instance.
  2. You can optionally set the properties of an instance to control its behavior.
  3. You can choose to create InterSystems IRIS multidimensional arrays to contain information about additional Settings.
  4. Calling instance’sprocess()Methods:
method Process(LocationURL As %String, 
               Package As %String = "Test", 
               ByRef Features As %String) as %Status
Copy the code
  • The LocationURL must be the URL of the schema or the name of the schema file (including its full path).
  • Package is the name of the Package used to put the generated class. If you do not specify a package, InterSystems IRIS uses the service name as the package name.
  • Feature is the multidimensional array you selected to create in the previous step.

The default IRIS data type for each XSD type

For each attribute it generates, the XML schema wizard automatically uses the appropriate InterSystems IRIS data type class based on the XSD type specified in the schema. The following table lists the XSD types and the corresponding InterSystems IRIS data types:

InterSystems IRIS data types for XML types

XSD type in the source document Data types in the generated IRIS class
anyURI %xsd.anyURI
base64Binary %xsd.base64Binaryor%Stream.GlobalBinaryDepending on which option is selected. Determines whether each string can exceed the string length limit, and if so, sets the generated properties from%xsd.base64BinaryModify to the appropriate stream class.
boolean %Boolean
byte %xsd.byte
date %Date
dateTime %TimeStamp
decimal %Numeric
double %xsd.double
float %xsd.float
hexBinary %xsd.hexBinary
int %xsd.int
integer %Integer
long %Integer
negativeInteger %xsd.negativeIntege
nonNegativeInteger %xsd.nonNegativeInteger
nonPositiveInteger %xsd.nonPositiveInteger
positiveInteger %xsd.positiveInteger
short %xsd.short
string %String(Note: It is the responsibility to determine whether each string may exceed the string length limit, and if so, modify the generated type to the appropriate stream class.)
time %Time
unsignedByte %xsd.unsignedByte
unsignedInt %xsd.unsignedInt
unsignedLong %xsd.unsignedLong
unsignedShort %xsd.unsignedShort
no type given %String

The property keyword of the generated property

For each attribute it generates, the XML schema wizard also automatically sets the following keywords using information in the schema:

  • Description

  • Required

  • ReadOnly (if the corresponding element or attribute is defined with a fixed attribute)

  • InitialExpression (this value is taken from a fixed attribute in the schema)

  • Keywords related to relationships

Arguments to the generated property

For each attribute it generates, the XML Schema wizard automatically sets XMLNAME, XMLPROJECTION, and all other XML-related parameters as needed. It also sets other parameters, such as MAXVAL, MINVAL, and VALUELIST, as needed.

Classes that are generated for extremely long strings

In rare cases, you may need to edit the generated class to accommodate excessively long strings or binary values that exceed the string length limit.

For any string type, the XML schema contains no information indicating the length of the string. The XML schema wizard maps all String values to the InterSystems IRIS %String class and all base64Binary values to the %xsd.base64Binary class. These choices may not be appropriate, depending on the data the class is hosting.

Before using the generated class, you should do the following:

  • Examine the generated class to find the class defined as%stringor%xsd.base64BinaryProperties. Consider the context in which these classes will be used, especially these attributes.
  • If you think%stringProperty may need to contain strings that exceed the string length limit; redefine this property as an appropriate character stream. Similarly, if you think that%xsd.base64BinaryProperty may need to contain strings that exceed the same limit; redefine this property as an appropriate binary stream.
  • Also note that for type is%string,%xsd.stringand%BINARYBy default,MAXLENAttribute parameter is50A character. You may need to specify higher limits for proper validation.

For attributes of type %xsd.base64Binary, MAXLEN is “”, which means the length will not pass the validation check. However, the string length limit does apply.