Generating the Client Classes Programmatically

You generate the client classes programmatically by using the %SOAP.WSDL.ReaderOpens in a new tab class. To generate the client classes programmatically:

Create an instance of %SOAP.WSDL.ReaderOpens in a new tab.
Optionally set properties to control the behavior of your instance. The subsections provide details.
Note that if the WSDL is at a location that uses SSL, %SOAP.WSDL.ReaderOpens in a new tab will (by default) checks whether the certificate server name matches the DNS name used to connect to the server. If these names do not match, the connection is not permitted. This default behavior prevents man in the middle attacks and is described in RFC 2818Opens in a new tab, section 3.1; also see RFC 2595Opens in a new tab, section 2.4.
To disable this check, set the SSLCheckServerIdentity property of the instance equal to 0.
If you need the ability to control the HTTP request in a way that is not directly supported by %SOAP.WSDL.ReaderOpens in a new tab, do this:
1. Create an instance of %Net.HttpRequestOpens in a new tab and set its properties as needed.
2. For your instance of %SOAP.WSDL.ReaderOpens in a new tab, set the HttpRequest property equal to the instance of %Net.HttpRequestOpens in a new tab that you just created.
For example, you might do this if the server requires authentication. See Providing Login Credentials in Sending HTTP Requests.
Invoke the Process() method of your instance:
```
method Process(pLocationURL As %String, pPackage As %String = "") as %Status 
```
- pLocationURL must be the URL of the WSDL of the web service or the name of the WSDL file (including its complete path). Depending on the configuration of the web service, it may be necessary to append a string that provides a suitable username and password; see the examples.
- pPackage 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.
  Note:
  
  If this package is the same as an existing package, by default the tool overwrites any existing classes that have the same name. To prevent the tool from overwriting a class definition, add the following to that class definition:
```
Parameter XMLKEEPCLASS = 1;
```

The following shows an example Terminal session:

set r=##class(%SOAP.WSDL.Reader).%New() 
GSOAP>set url="https://devsys/csp/mysamples/GSOP.AddComplexWS.CLS?WSDL=1"
 
GSOAP>d r.Process(url) 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.ns2.ComplexNumber
Compiling routine AddComplex.ns2.ComplexNumber.1
Compilation finished successfully in 0.170s.
 
Compilation started on 11/09/2009 12:53:52 with qualifiers 'dk'
Compiling class AddComplex.AddComplexSoap
Compiling routine AddComplex.AddComplexSoap.1
Compiling class AddComplex.AddComplexSoap.Add
Compiling routine AddComplex.AddComplexSoap.Add.1
Compilation finished successfully in 0.363s.

The WSDL URL is part of a web application, which might be protected by password authentication. For details on using the WSDL in this case, to generate InterSystems IRIS web clients or third-party web clients, see Using a Password-Protected WSDL URL.

In all cases, it is also possible to retrieve the WSDL from a browser after supplying the required username and password, save it as a file, and use the file instead.

Properties to Control Class Generation and Compilation

%SOAP.WSDL.ReaderOpens in a new tab includes the following properties which you can set in order to specify the types of classes to generate from the WSDL.

MakeClient

Specifies whether to generate client classes.

MakeService

Specifies whether to generate an InterSystems IRIS web service based on the WSDL.

CompileClasses

Specifies whether to compile classes after generating them.

If CompileClasses is 1, you can control the behavior of the compiler by specifying flags in the CompileFlags property. For more information, execute the following command:

 Do $System.OBJ.ShowFlags()

ClientPackage

Specifies the package name for the web client and any generated classes.

The default package name is the service name.

If you specify an existing package name, the tool overwrites any existing class that has the same name as a newly generated class by default.

MakeEnsembleClasses

Specifies whether to generate a business operation and related request and response message classes, which you can use in a production.

See Creating Web Services and Web Clients in Productions.

If MakeEnsembleClasses is 1, you must also specify the following propperties:

OperationPackage — Package name for the business operation class.
RequestPackage — Package name for the request message class.
ResponsePackage — Package name for the response message class.

Properties to Control Class Details

%SOAP.WSDL.ReaderOpens in a new tab includes the following properties to control details of the classes generated from the WSDL:

MakeNamespace

Specifies whether the generated classes should include the NAMESPACE class parameter set equal to the namespace of the web service.

If the WSDL explicitly indicates the namespace to which a given type belongs, MakeNamespace should be 1. In this case, the generated type class includes the NAMESPACE class parameter set equal to that namespace.
If the WSDL does not indicate the namespace for a given type, MakeNamespace can be either 1 or 0.

MakeMessageStyle

Specifies whether to use an unwrapped message format for the methods in the generated web client. This option affects only methods that have SoapBindingStyle equal to "document".

If either of the following statements are true of the WSDL, specify MakeMessageStyle as 1:

The <message> elements contain multiple parts.
The types used by the response messages belong to multiple namespaces.

Alternatively, the code generation fails and displays an error message such as the following:

ERROR #6425: Element 'wsdl:binding:operation:msg:input' - message 'AddSoapOut' 
Message Style must be used for document style message with 2 or more parts.

For more information, see Using InterSystems IRIS Web Client Classes.

NoArrayProperties

Specifies whether to generate array properties.

If this property is 1, the system does not generate array properties but instead generates another form. For more information, see Creation of Array Properties.

GenerateXMLNIL

Specifies whether 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 property parameter, see Handling Empty Strings and Null Values.

GenerateXMLNILNOOBJECT

Specifies 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, 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.

NoSequence

Specifies whether to set the XMLSEQUENCE class parameter in the generated classes to 0.

By default, the system sets this parameter to 1 in the generated classes, which ensures that the classes respect the order of elements as given in the schema in the WSDL. This value is useful when the schema has multiple elements of the same name within a given parent. For details, see Handling a Document with Multiple Tags with the Same Name.

IgnoreNull

Specifies whether the generated classes should include the XMLIGNORENULL class parameter set to 1.

If you select this option, the system adds XMLIGNORENULL=1 to the class definitions, including the generated web client (or web service). Otherwise, it does not add this parameter.

For details on this class parameter, see Handling Empty Strings and Null Values.

BinaryAsStream

Specifies whether to generate a property of type %Stream.GlobalBinaryOpens in a new tab for each element of type xsd:base64Binary.

If this property is 1, the generated properties are of type %Stream.GlobalBinaryOpens in a new tab. Alternatively, the properties are of type %xsd.base64BinaryOpens in a new tab.

%SOAP.WSDL.ReaderOpens in a new tab ignores any attributes of type xsd:base64Binary.

SecurityInParameter

Specifies the value of the SECURITYIN class parameter in the generated client class.

If you are using Web-Services security, use REQUIRE or ALLOW, depending on whether you want the client to require the elements or simply validate them. Otherwise, IGNORE or IGNOREALL is generally suitable. For details, see Validating WS-Security Headers.

The SECURITYIN parameter is ignored if there is a security policy in an associated (and compiled) configuration class. See Securing Web Services.

Using the Generated Web Client Classes