Generate classes from XML schema

Studio Provides a wizard , The wizard reads XML Pattern ( From a document or URL), And generate a set of support XML Class , These classes correspond to the types defined in the schema . All classes extend %XML.Adaptor. Specify a package to contain classes , And various options to control the details of class definition .

Wizards can also be used as class methods , You can also use this kind of method . In the internal ,SOAP The wizard is reading WSDL Document and generate web The client or web Use this method when serving ;

Be careful ： Any use of XML Document XML The declaration should indicate the character encoding of the document , And the document should be encoded in a declarative way . If no character encoding is declared ,InterSystems IRIS Will use the... At the beginning of this book “ Input and output character encoding ” The default values described in . If these defaults are incorrect , Please amend XML Statement , Make it specify the character set actually used .

Use the wizard

To use XML Architecture Wizards , Do the following ：

1. choice Tools > Add-Ins > XML Schema Wizard.
2. On the first screen , Specify the XML Pattern . Do one of the following :

• For schema files Schema File, choice Browse To choose XML Pattern file .
• about URL, Of the specified pattern URL.

1. choice Next.

Next screen display mode , In order to verify that the correct mode is selected .

1. You can choose the following options :

• Leave empty classes Keep Empty Classes, It specifies whether to keep unused classes without attributes . If you choose this option , This class will not be deleted at the end of the wizard ; otherwise , They will be deleted .
• “ Do not create array properties ”Create No Array Properties Controls whether the wizard generates array properties . If you choose this option , The wizard will not generate array properties , Instead, generate another form .
• Generate for nullable elements XMLNIL Property parameters , It controls whether the wizard specifies XMLNIL Property parameters .

This option applies to each corresponding to nillable="true" designated XML Attribute of element . If you choose this option , The wizard will add XMLNIL=1. Otherwise, do not add this parameter . For details of this parameter, see projecting objects to XML Medium “ Handle empty strings and values ”.

• Generate for nullable elements XMLNILNOOBJECT Property parameters , It controls whether the wizard specifies XMLNILNOOBJECT Property parameters .

This option applies to each corresponding to nillable="true" designated XML Attribute of element . If you choose this option , The wizard will add XMLNILNOOBJECT=1. Otherwise, do not add this parameter . For details of this parameter, see projecting objects to XML Medium “ Handle empty strings and values ”.

1. choice Next.

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

1. On this screen , Specify the following options :

• If you want the wizard to compile the generated class , You can choose “ Compile the generated class ”.
• Can choose “ add to NAMESPACE Class parameter ” To specify the NAMESPACE Parameters . In this case ,NAMESPACE Is set to mode targetNamespace Value .

If you do not set this option , It doesn't specify NAMESPACE.

It is recommended to choose this option in all cases , Because every support XML All classes of should be assigned to a XML The name space . ( however , For backward compatibility , You can clear this option .)

• If the class you want to generate is a persistent class , Please select Create persistent classes. Then the class extends %Persistent.

You can change this later in the wizard for each class .

• If you generate persistent classes , You can choose how to deal with it by another <complexType> b Of <sequence> Composed of <complexType> a. When the wizard generates a containing attribute a Persistent class of , This attribute has three possible forms . It can be defined as a list of objects 、 One-to-many relation ( Default ) Or father son relationship . The following table summarizes these choices :

Use relationships for collection properties in persistence classes	Add an index to a many pair relationship	Use parent-child relationships	Generated properties A In the form of
selected (default)	not selected	not selected	One to many relationship without index
selected (default)	selected	not selected	One to many relationship with index on multiple sides
selected (default)	If you choose Use parent-child relationship, Ignore this option	selected	Father and son
not selected	not selected	not selected	List of objects

Besides , If you do not choose to use parent-child relationship , Then you can choose to %OnDelete Method is added to the class to cascade deletion . If you choose this option , When the wizard generates the class definition , It will include %OnDelete() Implementation of callback method . Generated %OnDelete() Method to delete all persistent objects referenced by the class . If you do choose to use parent-child relationship , Please do not select this option ; The parent-child relationship has provided a similar logic .

Be careful ： If you modify the generated class , Please make sure to modify as needed %OnDelete() The callback method .

If you generate persistent classes , The wizard can add temporary properties to each object type class , So that you can project InterSystems IRIS Internal identifier . Options are as follows ：

• None- If you choose this option , The wizard will not add any of the properties described here .
• Use Id - If you choose this option , The wizard will add the following attributes to each object type class ：

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

Copy

• Use Oid - If you choose this option , The wizard will add the following attributes to each object type class ：

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

Copy

• Use GUID- If you choose this option , The wizard will add the following attributes to each object type class ：

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

Copy

The table at the bottom lists XML The name space . ad locum , Specify to include XML Package of namespace classes . To do this , Please specify the package name for this line in the package name field .

1. Select next .
2. On the next screen , Specify the following options ：

• Java Enabled - If you choose this option , Then each class includes a Java mapping .
• Data Population Data filling - If you choose this option , Is in addition to %XML.Adaptor Outside , Each class also inherits %Populate.
• SQL Column Order- If you choose this option , Each attribute will be SqlColumnNumber Keyword specifies a value , So that the attribute is in SQL The order in is the same as that in the schema .
• No Sequence Check- If this option is selected , In the class that the wizard will generate XMLSEQUENCE Parameter set to 0. In some cases , If XML The element order of the file is the same as XML Different architectures , This option is very useful .

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

• XMLIGNORENULL- If you choose this option , The wizard will XMLIGNORENULL=1 Add to class definition . otherwise , It will not add this parameter .
• Use streams for binary Use Streams for Binary - If you choose this option , The wizard will be xsd：base64Binary Any element of type generates %Stream.GlobalBinary Properties of type . If you clear this option , Then the type of this attribute is %xsd.base64Binary.

Please note that , The wizard will ignore xsd：base64Binary Any property of type .

• Below the check box , This table lists the classes that the wizard will generate . For each class , Make sure that Extensions/Type. Here it is , You can choose one of the following options ：
  • Persistent class Persistent - If you choose this option , Then the class is a persistent class .
  • Serial- If you choose this option , Then the class is a sequence class .
  • Registered Object- If you choose this option , Then the class is the registration 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. choice Finish( complete ).

then , The wizard will generate these classes , And compile them when needed .

For the properties of these classes , If the name of the corresponding element in the schema is underlined (_) start , Then the attribute name is represented by a percent sign (%) start .

Generate classes programmatically

XML The schema wizard can also be used %XML.Utils.SchemaReader Class process() Method . To use this method , Do the following ：

1. establish %XML.Utils.SchemaReader Example .
2. You can choose to set the properties of an instance to control its behavior .
3. You can choose to create InterSystems IRIS Multidimensional arrays , To include information about other settings .
4. Of the calling instance process() Method ：

method Process(LocationURL As %String, 
               Package As %String = "Test", 
               ByRef Features As %String) as %Status

Copy

• LocationURL Must be architectural URL Or the name of the schema file ( Including its full path ).
• Package Is the name of the package used to place the generated class . If you do not specify a package ,InterSystems IRIS The service name will be used as the package name .
• Feature Is the multidimensional array selected in the previous step .

Each of these XSD Default for type IRIS data type

For each attribute it generates ,XML The schema wizard will be based on XSD Type automatically uses the appropriate InterSystems IRIS Data type class . The following table lists them XSD Type and corresponding InterSystems IRIS data type ：

be used for XML Type of InterSystems IRIS data type

In the source document XSD type	Generated IRIS Data types in classes
anyURI	%xsd.anyURI
base64Binary	%xsd.base64Binary or %Stream.GlobalBinary, It depends on the choice . Determine whether each string may exceed the string length limit , If possible , Then the generated attribute is changed from %xsd.base64Binary Modify 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 ( Be careful ： Responsibility for determining whether each string may exceed the string length limit , If possible , Then modify the generated type to the appropriate flow class .)
time	%Time
unsignedByte	%xsd.unsignedByte
unsignedInt	%xsd.unsignedInt
unsignedLong	%xsd.unsignedLong
unsignedShort	%xsd.unsignedShort
no type given	%String

The attribute keyword of the generated attribute

For each attribute it generates ,XML The schema wizard also uses the information in the schema to automatically set the following keywords ：

• Description
• Required
• ReadOnly ( If the corresponding element or attribute is defined with a fixed attribute )
• InitialExpression ( This value is taken from the fixed attribute in the schema )
• Keywords related to relationships

Parameters of the generated attribute

For each attribute it generates ,XML The schema wizard will set it automatically as needed XMLNAME、XMLPROJECTION And all others with XML Related parameters . It also sets other parameters as needed , Such as MAXVAL、MINVAL and VALUELIST.

Adjust the class generated for super long string

In rare cases , You may need to edit the generated class to accommodate overly long strings or binary values , String length limit exceeded .

For any string type ,XML The schema does not contain any information indicating the length of the string .XML The schema wizard maps all string values to InterSystems IRIS %String class , And put all base64Binary Values map to %xsd.base64Binary class . These choices may not be appropriate , It depends on the data to be carried by the class .

Before using the generated class , You should do the following ：

• Check the generated class , Find the definition as %string or %xsd.base64Binary Properties of . Consider the context in which these classes will be used , Especially these attributes .
• If you think %string Property may need to contain a string that exceeds the string length limit , Please redefine this attribute as the appropriate character stream . Again , If you think %xsd.base64Binary Attributes may need to contain strings that exceed the same limit , Please redefine this attribute as the appropriate binary stream .
• Attention, please. , For types of %string、%xsd.string and %BINARY Properties of , By default ,MAXLEN The attribute parameter is 50 Characters . You may need to specify a higher limit to verify correctly .

( about %xsd.base64Binary Properties of type ,MAXLEN by “”, This means that the length will not be checked by validation . however , The string length limit does apply .)