Skip to main content

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 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.”

Note:

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:

  1. Select Tools > Add-Ins > XML Schema Wizard.

  2. 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.

  3. Select Next.

    The next screen displays the schema so that you can verify that you have chosen the correct one.

  4. 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.

  5. Select Next.

    The next screen displays some basic information on options about the classes to generate.

  6. 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 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];
        
      • 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 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.

  7. Select Next.

  8. 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 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.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.

  9. 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:

  1. Create an instance of %XML.Utils.SchemaReaderOpens in a new tab.

  2. Optionally set properties of the instance to control its behavior. For details, see the class documentation for %XML.Utils.SchemaReaderOpens in a new tab.

  3. 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.SchemaReaderOpens in a new tab.

  4. 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, 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:

Caché Data Types Used for XML Types
XSD Type in Source Document Data Type in the Generated Caché Classes
anyURI %xsd.anyURIOpens in a new tab
base64Binary %xsd.base64BinaryOpens in a new tab or %Stream.GlobalBinaryOpens in a new tab, 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.base64BinaryOpens in a new tab to an appropriate stream class.)
boolean %BooleanOpens in a new tab
byte %xsd.byteOpens in a new tab
date %DateOpens in a new tab
dateTime %TimeStampOpens in a new tab
decimal %NumericOpens in a new tab
double %xsd.doubleOpens in a new tab
float %xsd.floatOpens in a new tab
hexBinary %xsd.hexBinaryOpens in a new tab
int %xsd.intOpens in a new tab
integer %IntegerOpens in a new tab
long %IntegerOpens in a new tab
negativeInteger %xsd.negativeIntegerOpens in a new tab
nonNegativeInteger %xsd.nonNegativeIntegerOpens in a new tab
nonPositiveInteger %xsd.nonPositiveIntegerOpens in a new tab
positiveInteger %xsd.positiveIntegerOpens in a new tab
short %xsd.shortOpens in a new tab
string %StringOpens in a new tab (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.)
time %TimeOpens in a new tab
unsignedByte %xsd.unsignedByteOpens in a new tab
unsignedInt %xsd.unsignedIntOpens in a new tab
unsignedLong %xsd.unsignedLongOpens in a new tab
unsignedShort %xsd.unsignedShortOpens in a new tab
no type given %StringOpens in a new tab

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 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é %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.

If you have not enabled long string operations in Caché, you should do the following:

If you have enabled long string operations in Caché:

FeedbackOpens in a new tab