Using the SOAP Wizard

Using the SOAP Wizard

Studio provides the SOAP Wizard, which enables you to generate a client for a given web service, given the WSDL of that service.

To use the SOAP wizard:

1. Examine the WSDL and check for the following items:

   • Do the <message> elements contain multiple parts?

   • Do the types used by the response messages belong to multiple namespaces?

   In either case, if the answer is yes, then you will need to select the option Use unwrapped message format for document style web methods, which is described in a later step.

2. Click Tools > Add-ins > SOAP Wizard.

3. On the first screen:

   1. Click either URL or FILE, depending on the location of the WSDL.

   2. Enter the location of the WSDL. Type either the entire URL or the complete path and filename for the WSDL.

   3. If the WSDL is at a location that uses SSL (that is, if the URL starts with https), then select a suitable SSL configuration from the SSL Configuration dropdown list. For information on creating and managing SSL/TLS configurations, see the chapter “Using SSL/TLS with Caché” in the Caché Security Administration Guide.

      Important:

      This wizard specifies an SSL configuration to use when accessing the WSDL. This field is not used in any other way.

   4. If the WSDL is at a location that uses SSL, the wizard 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, clear the check box When making an SSL connection check that the server identity in the server certificate matches the name of the system being connected to.

4. Click Next.

   The wizard then attempts to access the WSDL and display it so that you can verify that you have chosen the correct one.

   If the wizard cannot access the WSDL, it displays a screen that displays the error and provides options that you can use to provide a username and password. (Many WSDLs are at URLs that are protected by a username and password, and this is a common reason for failing to access the WSDL.) In this scenario, first do one of the following:

   • To provide a Caché username and password, select CACHÉ user name and password

   • To provide a username and password for HTTP Basic authentication, select HTTP authentication user name and password

   Then enter values in the Username and Username fields and press Try Again. Note that the wizard does not save your entries for these items.

5. On the screen that displays the WSDL, specify options as follows:

   • Create Client for Web Service — Select this if you want the wizard to generate web client classes.

   • Create Web Service — Select this if you want the wizard to generate web service classes.

   • Compile generated classes — Select this if you want the wizard to compile the classes after generating them.

   • Compile flags — Specify flags to control how the compiler behaves. To get information about the compiler flags, execute the following command:

      Do $System.OBJ.ShowFlags()

     

   • Class Type — Choose a type to use for the generated type classes:

     • Persistent — The type classes should inherit from %PersistentOpens in a new tab. Any collections should be defined as lists.

     • Persistent using one-many relationships — The type classes should inherit from %PersistentOpens in a new tab and any collection properties should be defined as one-to-many relationships.

     • Persistent using indexed one-many relationships — The same as the preceding item except that Caché also defines an index for the relationship.

     • Persistent using parent-child for relationships — The type classes should inherit from %PersistentOpens in a new tab and any collection properties should be defined as parent-child relationships.

     • Serial — The type classes should inherit from %SerialObjectOpens in a new tab.

     • Registered — The type classes should inherit from %RegisteredObjectOpens in a new tab.

   • Add %OnDelete method to classes in order to cascade deletes — This option is displayed if you choose any persistent class type. If you select this option, when the wizard generates class definitions, it includes an implementation of the %OnDelete() callback method. The generated %OnDelete() method deletes all persistent objects that are referenced by the class.

     Note:

     Do not use this option if you select Persistent using parent-child for relationships.

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

   • Proxy Class Package — Type a package name for the web client. This is also used as the base package for any generated type classes. The default package name is the service name.

     If this package is the same as an existing package, by default the tool overwrites any existing classes that have the same name.

6. If you have an Ensemble installation, optionally provide values for the following additional fields:

   • Create Business Operation — Select this to generate an Ensemble business operation and related request and response message classes.

   • Business Operation Package — Specify the package for the business operation class.

   • Request Package — Specify the package for the request message class.

   • Response Package — Specify the package for the response message class.

   For information on Ensemble, see the Ensemble documentation.

7. Click Next. The wizard then displays a screen like the following:

8. Specify the following options:

   • Add NAMESPACE class parameter, which affects how generated type classes are assigned to namespaces:

     • 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 will include 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.

       If you select this option, the generated type class will include the NAMESPACE class parameter set equal to the namespace of the web service.

       If you clear this option, the generated type class will not include the NAMESPACE class parameter.

   • Use unwrapped message format for document style web methods, which affects the signature of the methods in the generated web client. See the appendix “Details of the Generated Classes” and see “Using Caché Web Client Classes,” later in this chapter.

     Important:

     If the WSDL that you are using contains <message> elements with multiple parts, be sure to select this option. If you do not, the wizard fails and displays a message like 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.
     

     

     Similarly, if the types used by the response messages are in different namespaces than each other, be sure to select this option.

     This option affects only methods that have SoapBindingStyle equal to "document".

   • Do not create 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 appendix “Details of the Generated Classes.”

   • 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 property 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.

   • Set XMLSEQUENCE parameter to 0, which controls how the wizard sets the XMLSEQUENCE class parameter in the generated classes.

     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, which controls 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, which controls how the wizard handles any element of type xsd:base64Binary. If you select this option, the corresponding property is of type %Stream.GlobalBinaryOpens in a new tab. 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.

   • Specify SECURITYIN class parameter, which controls the class parameter SECURITYIN 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 Caché Web Services.

     Important:

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

9. Optionally edit the package names. The wizard uses the following rules for package names:

   • The packages specified in Web Client Package or Web Service Package contain the main generated web client or web service class. These values are initialized by your entry in the previous page of the wizard.

   • If the wizard generates a policy class as well (because the WSDL contains WS-Policy information), that class is in the same package by default. To specify a different package, specify a value for Configuration Sub-Package.

     By default, the class name is the web client or service name, with Config appended to it. If you specify a value for Configuration Sub-Package, then this generated class has the same name as the web client or service (but is in the given subpackage instead).

     For information on WS-Policy, see Securing Caché Web Services.

   • For any supporting classes that are generated, the wizard detects all the namespaces used in the WSDL. By default, it organizes the generated classes into packages, with one package for each namespace.

     Optionally edit these package names.

     Not all namespaces necessarily correspond to generated classes. For example, the WSDL used in this example uses the namespaces http://schemas.xmlsoap.org/wsdl, http://schemas.xmlsoap.org/wsdl/mime, and http://schemas.xmlsoap.org/wsdl/soap. No generated classes are in these namespaces in this case, and the corresponding packages are not generated.

10. Click Next. The wizard generates and compiles the classes and displays a list of these classes.

11. Click Finish.

If the WSDL contains references to externally defined entities, the wizard attempts to resolve those; for this task, the timeout period is 10 seconds.

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 (%).