Generating Classes from XML Schemas

Generating the Classes

To generate XML-enabled classes that correspond to the types defined in an XML schema, use 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. In particular, you may want to set these properties (most of which are boolean):

   • KeepEmptyClasses, which specifies whether to keep unused classes that have no properties. If this property is 1, such classes are not removed at the end of the generation process; otherwise, they are removed.

   • NoArrayProperties, which controls to generate array properties. If this property is 1, the system does not generate array properties but instead generates another form. See Creation of Array Properties in Details of the Generated Classes.

   • GenerateXMLNIL, which controls to specify 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 this property is 1, the system 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.

   • GenerateXMLNILNOOBJECT, which controls whether to specify 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 this property is 1, the system 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.

   • CompileClasses, which controls whether to automatically compile the generated classes.

   • MakeNamespace, which controls whether to specify the NAMESPACE parameter. In this case, NAMESPACE is set to the value of the targetNamespace in the schema.

     If this property is 1, NAMESPACE is not specified.

     It is recommended to specify this as 1 in all cases, because every XML-enabled class should be assigned to an XML namespace.

   • MakePersistent, which controls whether the generated classes should extend %PersistentOpens in a new tab.

   • MakeRelationships, IndexRelationship and ParentChildRelationship, which controls the form of connections between persistent classes. These properties apply when the schema has a <complexType> A that consists of a <sequence> of another <complexType> B. When the code 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 permutations are summarized in the following table:

     MakeRelationships	IndexRelationship	ParentChildRelationship	Form of the generated property A
     1	1	0	One-to-many relationship with no index
     1	1	0	One-to-many relationship with index on the many side
     1	This property if ParentChildRelationship is 1	1	Parent-child relationship
     0	0	0	List of objects

   • CascadeDeletes, which specifies whether to also generate an implementation of the %OnDelete() callback method in the generated classes. The generated %OnDelete() method deletes all persistent objects that are referenced by the class. Use this only if ParentChildRelationship is 0; a parent-child relationship already provides similar logic.

     Note:

     If you use this option and if you modify the generated classes, be sure to modify the %OnDelete() callback method as needed.

   • AddIdentity, which specifies how to generate InterSystems IRIS internal identifier for the objects (in the case of persistent classes). The choices are as follows:

     • "" — In this case, the system does not add any of the properties described here.

     • "ID" — In this case, the system adds the following property to each persistent class:

       Property %identity As %XML.Id (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];

       

     • "OID" — In this case, the system adds the following property to each persistent class:

       Property %identity As %XML.Oid (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];

       

     • "GUID" — In this case, the system adds the following property to each persistent class:

       Property %identity As %XML.GUID (XMLNAME="_identity", XMLPROJECTION="ATTRIBUTE") [Transient];

       

     See also Special Topics.

   For more information, see the class documentation for %XML.Utils.SchemaReaderOpens in a new tab.

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

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, 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, %XML.Utils.SchemaReaderOpens in a new tab 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 data types:

Property Keywords for the Generated Properties

For each property that it generates, %XML.Utils.SchemaReaderOpens in a new tab 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, %XML.Utils.SchemaReaderOpens in a new tab 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. %XML.Utils.SchemaReaderOpens in a new tab maps any string values to the %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.)