Creating Web Clients

Overview of the SOAP WizardCopy link to this section

To create an InterSystems IRIS web client, you can use the SOAP Wizard in Studio or the corresponding class method provided by InterSystems IRIS. In either case, the input is a WSDL document. The tools generate a web client class and all needed supporting classes.

You can use the tool with nearly any WSDL document; see “WSDL Support in InterSystems IRIS” in the first topic.

You can provide either the URL or the file path for the WSDL.

Using the SOAP WizardCopy link to this section

If you have access to the WSDL that describes a given web service, you can use the SOAP Wizard in Studio to generate a web client for the service.

To use the SOAP wizard:

1. In Studio, click Tools > Add-ins > SOAP Wizard.

2. On the first screen of the SOAP Wizard, specify the location of the WSDL and the SSL configuration required to access it:

   1. Click URL or FILE to indicate the format of the WSDL.

   2. Type the WSDL URL, or browse to the WSDL file.

   3. If you specify a URL that requires SSL authentication (that is, if the URL begins with https), do the following:

      1. Select an SSL configuration from the SSL Configuration drop-down list.

         For information about creating and managing SSL/TLS configurations, see InterSystems TLS Guide.

         Important:

         The SSL Configuration field specifies only the SSL configuration that the wizard uses to access the WSDL.

      2. Optionally, clear the When making an SSL connection check that the server identity in the server certificate matches the name of the system being connected to check box.

         When the check box is selected, the wizard determines whether the certificate server name matches the DNS name used to connect to the server. If the 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 window, section 3.1. You can also see RFC 2595Opens in a new window, section 2.4 for more information.

   4. Click Next.

      The wizard attempts to access and display the WSDL.

      If the wizard is unsuccessful, an error appears. For possible causes, see “Problems Consuming WSDLs”.

      Tip:

      If the wizard cannot access the WSDL URL after several attempts, you can save the WSDL as a file and browse to it instead.

      If the wizard is successful, the Step 2 screen appears.

   5. If the WSDL URL requires password authentication, specify your credentials:

      1. Select the type of credentials to use:

         • For InterSystems IRIS credentials, select InterSystems IRIS user name and password.

         • For HTTP Basic authentication credentials, select HTTP authentication user name and password.

      2. Fill in the Username and Password fields.

      3. Click Try Again.

         The wizard does not save your entries.

         If the username and password are valid, the Step 2 screen appears.

      For more information, see “Using a Password-Protected WSDL URL”.

3. On the Step 2 screen of the SOAP Wizard, specify how the wizard generates classes from the WSDL:

   1. Configure the settings in the Options to control class generation and compilation area.

      For descriptions of the settings, see “SOAP Wizard Options to Control Class Generation and Compilation”.

   2. Click Next.

      The Step 3 screen appears.

4. On the Step 3 screen of the SOAP Wizard, specify how the wizard packages the classes it generates from the WSDL:

   1. Configure the settings at the top of the screen to determine how the wizard generates class packages from the XML namespaces in the WSDL.

      For descriptions of the settings, see “SOAP Wizard Options for XML Namespaces”.

   2. Optionally edit the class package names.

      For information about the Package Name fields, see “SOAP Wizard Rules for Class Package Names”.

   3. Click Next.

      The wizard generates, compiles, and lists the classes. Then, the Step 4 screen appears.

      Note:

      If the name of an element in the schema begins with an underscore (_), then properties of the class generated for the element begin with a percent sign (%).

5. Click Finish.

SOAP Wizard Options to Control Class Generation and CompilationCopy link to this section

The Step 2 screen of the SOAP wizard includes the following options, which enable you to specify the types of classes that the wizard generates from the WSDL.

Create Client for Web Service

Indicates whether the wizard generates proxy classes that function as a client for the web service defined by the WSDL.

Create Web Service

Indicates whether the wizard generates classes that function as an InterSystems IRIS web service based on the WSDL.

Compile generated classes

Indicates whether the wizard compiles classes after generating them.

If you select Compile generated classes, you can control the behavior of the compiler by specifying flags in the Compile flags field. For more information, execute the following command:

 Do $System.OBJ.ShowFlags()

Copy code to clipboard

Class Type

Specifies the type of classes that the wizard generates from the WSDL. You can select one of the following options:

• Persistent — Specifies that the classes inherit from %PersistentOpens in a new window, and collections are defined as lists.

• Persistent using one-many relationships — Specifies that the classes inherit from %PersistentOpens in a new window, and collection properties are defined as one-to-many relationships.

• Persistent using indexed one-many relationships — Specifies that the classes inherit from %PersistentOpens in a new window, collection properties are defined as one-to-many relationships, and InterSystems IRIS defines an index for each relationship.

• Persistent using parent-child for relationships — Specifies that classes inherit from %PersistentOpens in a new window, and any collection properties are defined as parent-child relationships.

• Serial — Specifies that classes inherit from %SerialObjectOpens in a new window.

• Registered — Specifies that classes inherit from %RegisteredObjectOpens in a new window.

Add %OnDelete method to classes in order to cascade deletes

For persistent class types, indicates whether to implement the %OnDelete() callback method for each generated class definition. Do not use this option if you select Persistent using parent-child for relationships.

The generated %OnDelete() method deletes all persistent objects that are referenced by the class.

If you modify the generated classes, be sure to modify the corresponding %OnDelete() callback methods as needed.

Proxy Class Package

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.

Create Business Operation

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

For information about productions, see Introducing Interoperability Productions and Creating Web Services and Web Clients in Productions.

If you select Create Business Operation, you must specify the following values:

• Business Operation Package — Package name for the business operation class.

• Request Package — Package name for the request message class.

• Response Package — Package name for the response message class.

SOAP Wizard Options for XML NamespacesCopy link to this section

The Step 3 screen of the SOAP wizard includes the following options, which enable you to configure the class packages generated from the WSDL:

Add NAMESPACE class parameter

Indicates whether the generated type class will 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, Add NAMESPACE Class Parameter is selected and grayed out. 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, you can select or clear Add NAMESPACE Class Parameter.

Use unwrapped message format for document style web methods

Indicates 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, select this check box:

• The <message> elements contain multiple parts.

• The types used by the response messages belong to multiple namespaces.

Alternatively, the wizard 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.

Copy code to clipboard

For more information, see Details of the Generated Classes and Using InterSystems IRIS Web Client Classes.

Do not create array properties

Indicates whether the wizard generates array properties.

If you select this option, the wizard does not generate array properties but instead generates another form. For more information, see Creation of Array Properties.

Generate XMLNIL property parameter for nillable elements

Indicates 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 property parameter, see “Handling Empty Strings and Null Values” in Projecting Objects to XML.

Generate XMLNILNOOBJECT property parameter for nillable elements

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

Set XMLSEQUENCE parameter to 0

Indicates whether the wizard sets the XMLSEQUENCE class parameter in the generated classes to 0.

By default, the wizard 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” in Projecting Objects to XML.

Generate XMLIGNORENULL parameter set to 1

Indicates whether the wizard specifies the XMLIGNORENULL class parameter in the generated classes.

If you select this option, the wizard 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” in Projecting Objects to XML.

Use Streams for Binary

Indicates whether the wizard generates a property of type %Stream.GlobalBinaryOpens in a new window for each element of type xsd:base64Binary.

If you select this option, the generated properties are of type %Stream.GlobalBinaryOpens in a new window. Alternatively, the properties are of type %xsd.base64BinaryOpens in a new window.

The wizard ignores any attributes of type xsd:base64Binary.

Specify SECURITYIN class parameter

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” in Securing Web Services.

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

Generating the Client Classes ProgrammaticallyCopy link to this section

You can instead generate the client classes programmatically by using the %SOAP.WSDL.ReaderOpens in a new window class.

The resulting generated classes and their organization may not be the same as if you used the SOAP wizard, which provides greater control over the packages for the generated classes.

To generate the client classes programmatically:

1. Create an instance of %SOAP.WSDL.ReaderOpens in a new window.

2. Optionally set properties to control the behavior of your instance. For details, see the class documentation for %SOAP.WSDL.ReaderOpens in a new window.

   Note that if the WSDL is at a location that uses SSL, %SOAP.WSDL.ReaderOpens in a new window 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 window, section 3.1; also see RFC 2595Opens in a new window, section 2.4.

   To disable this check, set the SSLCheckServerIdentity property of the instance equal to 0.

3. 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 window, do this:

   1. Create an instance of %Net.HttpRequestOpens in a new window and set its properties as needed.

   2. For your instance of %SOAP.WSDL.ReaderOpens in a new window, set the HttpRequest property equal to the instance of %Net.HttpRequestOpens in a new window that you just created.

   For example, you might do this if the server requires authentication. See “Providing Login Credentials” in the chapter “Sending HTTP Requests” in Using Internet Utilities.

4. Invoke the Process() method of your instance:

   method Process(pLocationURL As %String, pPackage As %String = "") as %Status 

   Copy code to clipboard

   • 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;

     Copy code to clipboard

The following shows an example Terminal session:

set r=##class(%SOAP.WSDL.Reader).%New() 
GSOAP>set url="http://localhost:52773/csp/gsop/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.

Copy code to clipboard

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,” later in this book.

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.

Modifying the Generated Client ClassesCopy link to this section

After you generate an InterSystems IRIS web client class, you do not usually edit the class. Instead you write code that creates an instance of the web client and that provides provide client-side error handling. This section documents the notable exceptions where you do modify the generated client class.

Also see the section “Additional Notes on Web Methods in the Generated Class” and the topic “Fine-Tuning a Web Client in InterSystems IRIS.”

Adjusting the Generated Classes for Extremely Long StringsCopy link to this section

In rare cases, you might need to edit the generated client class to accommodate extremely long strings or binary values — values whose lengths exceed the string length limit.

When the SOAP Wizard reads a WSDL, it assumes that any string-type input or output can be represented in InterSystems IRIS as %StringOpens in a new window, which is not always true. In rare cases, a string might exceed the string length limit. Similarly, the wizard assumes that any input or output with XML type base64Binary can be represented in InterSystems IRIS as %xsd.base64BinaryOpens in a new window), which is not always true, due to the same string length limitation. In neither case does the WSDL contain any information to indicate that this input or output could exceed the string length limit.

When your web client encounters a string or a binary value that is too long, it throws one of the following errors:

• A <MAXSTRING> error

• A datatype validation error:

  ERROR #6232: Datatype validation failed for tag your_method_name ...

  Copy code to clipboard

  (This error, of course, can also be caused by a datatype mismatch.)

The problem, however, is easy to correct: adjust the method signature in your generated web client class (specifically the class that inherits from %SOAP.WebClientOpens in a new window) to use an appropriate stream class:

• Use %GlobalCharacterStreamOpens in a new window instead of %StringOpens in a new window.

• Use %GlobalBinaryStreamOpens in a new window instead of %xsd.base64BinaryOpens in a new window.

For example, consider a web service (MyGiantStringService) that has one method (WriteIt), which takes no arguments and returns a very long string. If you use the SOAP Wizard to generate the web client class, the web client class originally looks something like this:

Class GetGiantString.MyServiceSoap Extends %SOAP.WebClient
{

Method WriteIt() As %String 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke($this,"http://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}

}

Copy code to clipboard

In this case, there is only one adjustment to make. Change the return type of WriteIt as follows:

Method WriteIt() As %GlobalCharacterStream 
[Final,SoapBindingStyle=document,SoapBodyUse=literal,WebMethod]
{
 Quit ..WebMethod("WriteIt").Invoke($this,"http://tempuri.org/MyApp.MyGiantStringService.WriteIt")
}

Copy code to clipboard

When you compile this class, the system automatically regenerates the associated classes as needed.

You may also need to adjust property types within any generated type classes. For example, suppose the web service uses an element called <Container>, which includes an element <ContainerPart> of type string. When you generate the InterSystems IRIS web client classes, the system creates a Container class with a ContainerPart property of type %StringOpens in a new window. If the web service sends a string longer than the string length limit in the <ContainerPart> element, your web client throws an error. To avoid this error, change the type of the ContainerPart property to %GlobalCharacterStreamOpens in a new window.

Other AdjustmentsCopy link to this section

If the WSDL does not specify the location of the web service, the SOAP Wizard does not specify the LOCATION parameter of the web client. This is a rare scenario. In this scenario, edit the web client class to include the LOCATION parameter. For example:

Parameter LOCATION = "http://localhost:52773/csp/gsop/GSOP.AddComplexWS.cls";

Copy code to clipboard

Or specify the Location property of your web client instance as shown later in this topic.

You might need to adjust other parameters of the web client class to make other changes. See the topic “Fine-Tuning a Web Client in InterSystems IRIS” for details.

Using the Generated Web Client ClassesCopy link to this section

As noted in the previous section, after you generate an InterSystems IRIS web client class, you do not usually edit the generated class. Instead you write code that creates an instance of that web client and that provides provide client-side error handling. In this code, do the following:

1. Create an instance of the web client class.

2. Set its properties. Here you can control items such as the following:

   • Endpoint of the web client (the URL of the web service it uses). To control this, set the Location property, which overrides the LOCATION parameter of the web client class.

   • Settings that designate a proxy server.

   • Settings that control HTTP Basic authentication.

   See the next section in this topic as well as the topic “Fine-Tuning a Web Client in InterSystems IRIS.”

3. Invoke the methods of the web client as needed.

4. Perform client-side error handling. See the topic “SOAP Fault Handling.”

5. Optionally examine the HTTP response received by the web client, as described later in this topic.

The following shows a simple example, from a session in the Terminal:

GSOAP>set client=##class(Proxies.CustomerLookupServiceSoap).%New()

GSOAP>set resp=client.GetCustomerInfo("137")
 
GSOAP>w resp
 
11@Proxies.CustomerResponse

GSOAP>w resp.Name
Smith,Maria

Copy code to clipboard

Example 1: Using the Client That Uses Wrapped MessagesCopy link to this section

In this example, we create a wrapper class for a web client that uses wrapped messages. To use the example GSOAPClient.AddComplex.AddComplexSoap shown previously, we could create a class like the following:

Class GSOAPClient.AddComplex.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As ComplexNumber, arg2 As ComplexNumber) As ComplexNumber
{
    Set client=##class(AddComplexSoap).%New()
    //uncomment the following to enable tracing
    //set client.Location="http://localhost:8080/csp/gsop/GSOP.AddComplexWS.cls"
    Set ans=client.Add(arg1,arg2)
    Quit ans 
}

}

Copy code to clipboard

The client application would invoke this method in order to execute the web method.

Example 2: Using the Client That Uses Unwrapped MessagesCopy link to this section

In this example, we create a wrapper class for a web client that uses unwrapped messages. To use the example GSOAPClient.AddComplex.AddComplexSoap shown previously, we could create a class like the following:

Class GSOAPClient.AddComplexUnwrapped.UseClient Extends %RegisteredObject
{

ClassMethod Add(arg1 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber, 
arg2 As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber) 
As GSOAPClient.AddComplexUnwrapped.s0.ComplexNumber
{
    //create the Add message
    Set addmessage=##class(GSOAPClient.AddComplexUnwrapped.s0.Add).%New()
    Set addmessage.a = arg1
    Set addmessage.b = arg2

    Set client=##class(AddComplexSoap).%New()
    
    //send the Add message to client and get response
    Set addresponse=client.Add(addmessage)
    
    //get the result from the response message
    Set ans=addresponse.AddResult
    
    Quit ans
 
}

}

Copy code to clipboard

The method has the signature that would typically be expected; that is, it accepts two complex numbers and returns a complex number. The method creates the message that the web client expects. The elements of this message are the two complex numbers.

As you can see, when the web client uses unwrapped messages, it is necessary to write slightly more code to convert arguments in a user-friendly form into the message used by the web client.

Adjusting Properties of a Web Client InstanceCopy link to this section

When you use an instance of your web client classes, you can specify properties of that instance to control its behavior. This section discusses the properties that are most commonly set, as well as their default values.

Changing the Endpoint for the Web ClientCopy link to this section

The SOAP Wizard automatically sets the endpoint for the web client by setting the LOCATION parameter of the web client. By default, it sets this parameter equal to the URL of the web service with which it communicates.

To override this, set the Location property of your web client instance. If Location is null, then the LOCATION parameter is used.

A common usage is to set the Location property to use a different port, in order to enable tracing. For example, suppose that in the generated web client class, the endpoint is defined as follows:

Parameter LOCATION = "http://localhost:52773/csp/gsop/GSOP.AddComplexWS.cls";

Copy code to clipboard

When you use this client, you can include the following line:

   Set client.Location="http://localhost:8080/csp/gsop/GSOP.AddComplexWS.cls"

Copy code to clipboard

Note:

If the WSDL does not specify the location of the web service, the SOAP Wizard does not specify the LOCATION parameter of the web client. This is a rare scenario. In this scenario, either edit the web client class to include the LOCATION parameter or specify the Location property of your web client instance as shown here.

Using the HTTP ResponseCopy link to this section

By default, when you invoke a web client method, you do so via HTTP. The HTTP response is then available as the HttpResponse property of the web client instance. This property is an instance of %Net.HttpResponseOpens in a new window, which in turn has properties like the following:

• Headers contains the headers of the HTTP response.

• Data is an InterSystems IRIS multidimensional array that contains any data in the HTTP response.

• StatusCode, StatusLine, and ReasonPhrase provide status information.

For details, see the book Using Internet Utilities. Or see the class documentation for %Net.HttpResponseOpens in a new window.