Chapter 5 Using SOAP Management

SOAP management

Web Services Toolkit SOAP Management feature enables you to create a client proxy to assist your customers in accessing your Web service, and to define datatypes to use in your Web service. A client proxy can include:

• A WSDL document
• A SOAP templates document
• Instructions on using the proxy
• Classes needed to retrieve data from the WSDL file to build a SOAP request and process the SOAP response message

If you are using user-defined datatypes in your client proxy, you must manually add the following to a client proxy .jar file:

• Class files required by the client to access your Web service
• SOAP template file
• user.encoding.props file for any user defined datatypes.

This section discusses:

• Creating a SOAP Client Proxy
• Registering a user-defined datatype

Creating a SOAP Client Proxy

The client proxy is a collection of classes that work together to build and process SOAP messages on the client side. The Proxy's purpose is to hide all the details of SOAP processing and HTTP or HTTPS transport, allowing the client programmer to concentrate on the client business process. Invoking Web services through SOAP requires serialization and deserialization of datatypes, and the building and parsing of SOAP messages. The client proxy performs these tasks for the client programmer, thus eliminating the need for the client programmer to have extensive knowledge of the SOAP specification and schema, the XML Schema specification, or the WSDL specification and schema.

To create a SOAP client proxy

1. Connect to the Web Services Toolkit.
2. In the main pane of Sybase Central, double-click SOAP Management under Web Services Toolkit.
3. Click Utilities in the main pane of Sybase Central.
4. Double click on Create a SOAP ClientProxy Jar in the Details pane.
5. The Create SOAP Client Proxy dialog box opens.
6. Enter values in the following text fields:
   • Proxy Jar File name - creates a .jar file of this name in the Webservices directory in the EAServer installation. For a description of its contents see "Installing the Client Proxy". Enter only the name of the JAR file and not a path.
   • WSDL File name - adds the WSDL file to the client proxy. jar file. Type in a file name of an implementation file (which ends in Impl.wsdl) in the Webservices\work\wsdl directory in your EAServer installation or click Browse for a list of WSDL implementation files in the same directory. Enter only the name of the WSDL file and not a path.
   • SOAP Template File name - creates a SOAP template file. Type in a file name from the Webservices\work\templates directory in your EAServer installation or click Browse for a list of template files in the same directory. Enter only the name of the template file and not a path.
     
     You must manually add the SOAP template file to the client proxy .jar file.
7. Click OK.

The proxy jar file is created in the Webservices directory in the EAServer installation.

The process of using the client proxy to access a Web service involves:

1. Unjaring the proxy .jar file on the client. If you have multiple Web services with the only difference being the WSDL file name, you can have all Web services in one proxy .jar file. When they are expanded on the client they will be in the proxy directory.
2. Setting the SYBASE_SOAP variable to the client directory where the .jar file is expanded.
3. Copying the WSDL files from the proxy directory to the $JAGUAR directory on EAServer.

See Chapter 8, "Using the Sybase Web Services Client Proxy" for more information.

Registering a user-defined datatype

If you have an unsupported datatype that you want to include in a Web service, you must define a serializer and deserializer class for it.

To register a user-defined datatype

1. Double-click SOAP Management in the main pane of Sybase Central.
2. In the main pane of Sybase Central click Utilities under SOAP Management.
3. Double-click Manage User-Defined Types in the Details pane. The Manage User-Defined Types dialog box opens.
4. Enter values in the following text fields:
   • Data Type - the fully-qualified name of your class, which must be in your EAServer's classpath.
   • Serializer Class - the fully-qualified name of your serializer, which must be in your EAServer's classpath.
   • Deserializer Class - the name of your fully-qualified deserializer, which must be in your EAServer's classpath.
   • Serialization Rule - the URI of the schema that defines how a datatype is serialized.
   • Encoding Style - a general set of rules for how data is encoded as XML. In most cases the SOAP encoding style is appropriate.
5. Click OK.

These values are saved in the user.encoding.props file in the Webservices\work directory in the EAServer installation.

To use a user-defined datatype in a client proxy, manually add the user.encoding.props file to the client proxy .jar file. A Webservices directory is created when the client proxy .jar file is expanded on the client. Make sure the user.encoding.props file is in this directory.

A Web service returning a user-defined datatype is represented as a SOAP encoded structure. The client proxy checks the datatype being used against the standard datatypes table. If no match is found, it looks up the datatype in the user.encoding.props file and locates the corresponding serializer/deserializer mappings which it uses to convert the component class to and from XML.

Copyright © 2002 Sybase, Inc. All rights reserved.