Generating Classes from XML Schemas
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 the classes extend %XML.AdaptorOpens in a new tab. You specify a package to contain the classes, as well as various options that control the details of the class definitions.
The wizard is also available as a class method, which you can also use. Internally, the SOAP Wizard uses this method when it reads a WSDL document and generates web clients or web services; see Creating Web Services and Web Clients.
This wizard does not load data into InterSystems IRIS® data platform. If you need to load data after generating classes, see Importing XML into Objects.
The XML declaration of any XML document that you use should indicate the character encoding of that document, and the document should be encoded as declared. If the character encoding is not declared, InterSystems IRIS uses the defaults described in Character Encoding of Input and Output. If these defaults are not correct, modify the XML declaration so that it specifies the character set actually used.
Using the Wizard
To use the XML Schema Wizard:
-
Select Tools > Add-Ins > XML Schema Wizard.
-
On the first screen, you specify the XML schema to use. Do one of the following:
-
For Schema File, select Browse to select an XML schema file.
-
For URL, specify the URL of the schema.
-
-
Select Next.
The next screen displays the schema so that you can verify that you have chosen the correct one.
-
Optionally select the following options:
-
Keep Empty Classes, which specifies whether to keep unused classes that have no properties. If you select this option, such classes are not removed at the end of the wizard; otherwise, they are removed.
-
Create No Array Properties, which controls whether the wizard generates array properties. If you select this option, the wizard does not generate array properties but instead generates another form. See Creation of Array Properties in Details of the Generated Classes.
-
Generate XMLNIL property parameter for nillable elements, which controls whether the wizard specifies the XMLNIL property parameter for applicable properties in the generated classes.
This option applies to each property that corresponds to an XML element that is specified with nillable="true". If you select this option, the wizard adds XMLNIL=1 to the property definition. Otherwise, it does not add this parameter. For details on this parameter, see Handling Empty Strings and Null Values.
-
Generate XMLNILNOOBJECT property parameter for nillable elements, which controls whether the wizard specifies the XMLNILNOOBJECT property parameter for applicable properties in the generated classes.
This option applies to each property that corresponds to an XML element that is specified with nillable="true". If you select this option, the wizard adds XMLNILNOOBJECT=1 to the property definition. Otherwise, it does not add this parameter. For details on this parameter, see Handling Empty Strings and Null Values.
-
-
Select Next.
The next screen displays some basic information on options about the classes to generate.
-
On this screen, specify the following options:
-
Optionally select Compile generated classes if you want the wizard to compile the generated classes.
-
Optionally select Add NAMESPACE Class Parameter to specify the NAMESPACE parameter. In this case, NAMESPACE is set to the value of the targetNamespace in the schema.
If you leave this option clear, NAMESPACE is not specified.
It is recommended to select this option in all cases, because every XML-enabled class should be assigned to an XML namespace. (For backward compatibility, however, it is possible to leave this option clear.)
-
If you want the generated classes to be persistent classes, select Create Persistent Classes. Then the classes extend %PersistentOpens in a new tab.
You can change this later in the wizard for individual classes.
-
If you generate persistent classes, you have options to determine how to handle a <complexType> A that consists of a <sequence> of another <complexType> B. When the wizard generates a persistent class containing property A, there are three possible forms for this property. It can be defined as a list of objects, as a one-to-many relationship (the default), or as a parent-child relationship. The options are summarized in the following table:
Use Relationships for Collection Properties in Persistent Classes Add index to many-one relationship Use parent-child relationship Form of the generated property A selected (default) not selected not selected One-to-many relationship with no index selected (default) selected not selected One-to-many relationship with index on the many side selected (default) This option is ignored if you select Use parent-child relationship selected Parent-child relationship not selected not selected not selected List of objects Also, if Use parent-child relationship is not selected, optionally select the option Add %OnDelete method to classes in order to cascade deletes. If you select this option, when the wizard generates class definitions, it includes an implementation of the %OnDelete() callback method in those classes. The generated %OnDelete() method deletes all persistent objects that are referenced by the class. Do not select this option if you do select Use parent-child relationship; a parent-child relationship already provides similar logic.
Note:If you modify the generated classes, be sure to modify the %OnDelete() callback method as needed.
-
If you generate persistent classes, the wizard can add a transient property to each object-type class so that you can project an InterSystems IRIS internal identifier for the objects. The choices are as follows:
-
None — If you select this option, the wizard does not add any of the properties described here.
-
Use Id — If you select this option, the wizard adds the following property to each object-type class:
Property %identity As %XML.Id (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
-
Use Oid — If you select this option, the wizard adds the following property to each object-type class:
Property %identity As %XML.Oid (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
-
Use GUID — If you select this option, the wizard adds the following property to each object-type class:
Property %identity As %XML.GUID (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];
See also Special Topics.
-
-
The table at the bottom lists XML namespaces in the schema. Here, specify the package to contain the classes for the XML namespace shown in that row. To do so, specify a package name in the Package Name field for that row.
-
-
Select Next.
-
On the next screen, specify the following options:
-
Java Enabled — If you select this option, each class includes a Java projection.
-
Data Population — If you select this option, each class extends %PopulateOpens in a new tab in addition to %XML.AdaptorOpens in a new tab.
-
SQL Column Order — If you select this option, each property specifies a value for the SqlColumnNumber keyword, so that the properties have the same order in SQL that they have in the schema.
-
No Sequence Check — If you check this option, the wizard sets the XMLSEQUENCE parameter to 0 in the generated classes. This option is useful in some situations in which your XML files do not have elements in the same order as the XML schema.
By default, the XMLSEQUENCE parameter is set to 1 in the generated classes. This ensures that the properties are included within the class definition in the same order as in the schema. Also see Special Topics.
-
XMLIGNORENULL — If you select this option, the wizard adds XMLIGNORENULL=1 to the class definitions. Otherwise, it does not add this parameter.
For details on this class parameter, see Handling Empty Strings and Null Values.
-
Use Streams for Binary — If you select this option, the wizard generates a property is of type %Stream.GlobalBinaryOpens in a new tab for any element of type xsd:base64Binary. If this option is clear, the property is of type %xsd.base64BinaryOpens in a new tab instead.
Note that the wizard ignores any attributes of type xsd:base64Binary.
-
Below the check boxes, the table lists the classes that the wizard will generate. For each class, make sure that Extends/Type is set appropriately. Here you choose one of the following:
-
Persistent — If you select this option, the class is a persistent class.
-
Serial — If you select this option, the class is a serial class.
-
Registered Object — If you select this option, the class is a registered object class.
All generated classes also extend %XML.AdaptorOpens in a new tab.
-
-
In the right column of the table, select Index for each property that should be indexed.
-
-
Select Finish.
The wizard then generates the classes and, if requested, compiles them.
For properties of these classes, if the corresponding element in the schema has a name that starts with an underscore (_), the name of the property starts with a percent sign (%).
Generating the Classes Programmatically
The XML Schema Wizard is also available as the Process() method of the %XML.Utils.SchemaReaderOpens in a new tab class. To use this method:
-
Create an instance of %XML.Utils.SchemaReaderOpens in a new tab.
-
Optionally set properties of the instance to control its behavior. For details, see the class documentation for %XML.Utils.SchemaReaderOpens in a new tab.
-
Optionally create an InterSystems IRIS multidimensional array to contain information about additional settings. For details see the Process() method in the class documentation for %XML.Utils.SchemaReaderOpens in a new tab.
-
Invoke the Process() method of your instance:
method Process(LocationURL As %String, Package As %String = "Test", ByRef Features As %String) as %Status {}
-
LocationURL must be the URL of the schema or the name of the schema file (including its complete path).
-
Package is the name of the package in which to place the generated classes. If you do not specify a package, InterSystems IRIS uses the service name as the package name.
-
Features is the multidimensional array that you optionally created in the previous step.
-
Default Data Types
For each property that it generates, the XML Schema Wizard automatically uses an appropriate InterSystems IRIS data type class, depending on the XSD type specified in the schema. The following table lists the XSD types and the corresponding InterSystems IRIS data types:
Property Keywords for the Generated Properties
For each property that 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 the fixed attribute)
-
InitialExpression (the value is taken from the fixed attribute in the schema)
-
Keywords related to relationships
Parameters for the Generated Properties
For each property that it generates, the XML Schema Wizard automatically sets XMLNAME, XMLPROJECTION, and all other XML-related parameters as needed. For information on these, see Projecting Objects to XML. It also sets other parameters such as MAXVAL, MINVAL, and VALUELIST as appropriate.
Adjusting the Generated Classes for the Extremely Long Strings
In rare cases, you might need to edit the generated classes to accommodate extremely long strings or binary values, beyond the string length limit.
For any string types, an XML schema does not contain any information to indicate how long the strings might be. The XML Schema Wizard maps any string values to the InterSystems IRIS %StringOpens in a new tab class, and it maps any base64Binary values to the %xsd.base64BinaryOpens in a new tab class. These choices might not be appropriate, depending on the data that the class is intended to carry.
Before using the generated classes, you should do the following:
-
Examine the generated classes and find the properties that are defined as %StringOpens in a new tab or %xsd.base64BinaryOpens in a new tab. Consider the contexts in which you will use these classes, and particularly these properties.
-
If you think a %StringOpens in a new tab property might need to contain string that exceeds the string length limit, redefine the property to an appropriate character stream. Similarly, if you think a %xsd.base64BinaryOpens in a new tab property might need to contain a string that exceeds the same limit, redefine the property to an appropriate binary stream.
-
Also note that for properties of type %StringOpens in a new tab, %xsd.stringOpens in a new tab, and %BinaryOpens in a new tab, the MAXLEN property parameter is 50 characters, by default. You might need to specify a higher limit to have correct validation.
(For properties of type %xsd.base64BinaryOpens in a new tab, MAXLEN is "", which means the length is not checked by validation. The string length limit, however, does apply.)