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.Adaptor. 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 in Caché.
This topic includes information on the following items:
This wizard does not load data into Caché. If you need to load data after generating classes, see the topic “Importing XML into Caché 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, Caché uses the defaults described in “Character Encoding of Input and Output,” earlier in this book. 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.
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 the topic “Details of the Generated Classes” in Creating Web Services and Web Clients in Caché.
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” in Projecting Objects to XML.
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” in Projecting Objects to XML.
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 %Persistent.
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 a Caché 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];Copy code to clipboard
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];Copy code to clipboard
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];Copy code to clipboard
See also the topic “Special Topics” in Projecting Objects to XML.
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.
On the next screen, specify the following options:
Java Enabled — If you select this option, each class includes a Java projection.
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 the topic “Special Topics” in Projecting Objects to XML.
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” in Projecting Objects to XML.
Use Streams for Binary — If you select this option, the wizard generates a property is of type %Stream.GlobalBinary for any element of type xsd:base64Binary. If this option is clear, the property is of type %xsd.base64Binary 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.Adaptor.
In the right column of the table, select Index for each property that should be indexed.
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.SchemaReader class. To use this method:
Create an instance of %XML.Utils.SchemaReader.
Optionally set properties of the instance to control its behavior. For details, see the class documentation for %XML.Utils.SchemaReader.
Optionally create a Caché multidimensional array to contain information about additional settings. For details see the Process() method in the class documentation for %XML.Utils.SchemaReader.
Invoke the Process() method of your instance:
method Process(LocationURL As %String, Package As %String = "Test", ByRef Features As %String) as %StatusCopy code to clipboard
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, Caché uses the service name as the package name.
Features is the multidimensional array that you optionally created in the previous step.
Default Caché Data Types for Each XSD Type
For each property that it generates, the XML Schema Wizard automatically uses an appropriate Caché data type class, depending on the XSD type specified in the schema. The following table lists the XSD types and the corresponding Caché data types:
|XSD Type in Source Document||Data Type in the Generated Caché Classes|
|base64Binary||%xsd.base64Binary or %Stream.GlobalBinary, depending on options you chose. Note that if long string operations are not enabled in Caché, it is your responsibility to determine if each string might exceed the long string limit, and if so, to modify the generated property from %xsd.base64Binary to an appropriate stream class.)|
|string||%String (Note: If long string operations are not enabled in Caché, it is your responsibility to determine if each string might exceed the long string limit, and if so, to modify the generated type to an appropriate stream class.)|
|no type given||%String|
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:
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 Long Strings
In some cases, you might need to edit the generated classes to accommodate long strings or long binary values.
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 Caché %String class, and it maps any base64Binary values to the %xsd.base64Binary class. These choices might not be appropriate, depending on the data that the class is intended to carry.
If you have not enabled long string operations in Caché, you should do the following:
Consider the contexts in which you will use these classes, and particularly these properties.
If you think a %String property might need to contain a long string, redefine the property to an appropriate character stream. Similarly, if you think a %xsd.base64Binary property might need to contain a long binary string, redefine the property to an appropriate binary stream.
If you have enabled long string operations in Caché: