Web Services Client Gear

Module name: soapclient

The Web Services Client Gear enables portal visitors to access Web services made available on remote computers. A Web service application can describe itself, publish this description to a directory, and be invoked remotely over a network via Simple Object Access Protocol (SOAP). The Web Services Client Gear acts as a client in Web service transactions.

For example, there might be a Web service that exposes the top five news headlines for a given topic. A client of this service would provide a topic (technology, financial, entertainment etc.) that it would like the top five headlines for. The server exposing this service would then return the matching headlines. In this example, the Web Services client gear provides the ability for a portal user to configure the gear to connect to the service as well as provide the topics that should be obtained from the server. These headlines will then be displayed on a given portal page where the gear is deployed.

There are several restrictions on the type of Web services and Web Services Description Language (WSDL) documents that the gear can handle. The gear can only support the invocation of services where the types of the parameters to the service as well as the return value are simple types. The following types are supported:

These types are expected to be declared in the WSDL document as the associated schema data type. Additionally, a WSDL document that is to be uploaded can contain only the definition of a single method for a service.

There are two types of configuration information that must be supplied in order to successfully invoke a Web service:

Using the above example, protocol-level connection information would be things like a URL to connect to and a method name to invoke. The runtime parameter would be the news topic you are requesting. Configuring protocol-level connection information is a technical task and thus is the responsibility of the Portal Administrator. Each user will then want to customize the parameters passed to a given service in order to personalize the service. Thus, the Web Services client gear can be configured at both the Portal Administrator level as well as user level.

Installation Configuration

Before the gear can be successfully used, it must be configured with its connection-level information. The installation configuration is the only place that this can be done. The information that must be supplied is information that is specific to SOAP (the RPC layer in the Web Services protocol) as well as the transport information that the SOAP message will be sent over. The Web Services gear supports invoking Web Services over the HTTP-based protocol.

The following SOAP connection information is required:

Method name

The method name that is to be invoked on the remote service

Parameters

The name and type of the parameters that are to be supplied to a particular method

URI of target object

The URI for the remote service

The following HTTP connection information is required:

Target URL

The URL where the remote service is located

SOAP Action

Value that can be placed into HTTP header to indicate intent

Web services provide a way to describe this information in a single document. This is done via the Web Services Description Language (WSDL). The WSDL specification provides a standard way to model the definition of a particular service. The modeling is done via an XML document. Typically, any Web service that is available will provide a WSDL document that describes the service. The Web Services gear only needs this WSDL document in order to know its connection information. It will take this WSDL document and parse out all of the SOAP- and HTTP-specific information. To configure the gear with this WSDL document follow these steps:

  1. On the Gears tab of the Portal Administration Pages click the configure link next to the Web Services Client Gear name.

  2. Browse to the location of the WSDL document on your machine and then click Upload.

    This will upload the WSDL document from your local machine to the server. The server will then attempt to extract all of the necessary connection information from this document. If any errors occur then the user will remain on the same page and the errors that resulted will be displayed.

    Each user must now customize the values of the parameters to pass to the Web service by using the User Configuration pages. For example, the user must specify what type of news headlines to receive.

User Configuration

Users set the value of the parameters to pass to a given service. They are personalizing the service to obtain the information that interests them.

In the News Service example, if the Portal Administrator has uploaded a WSDL document describing the service to connect to (News), then the gear has all the information necessary to connect to the service. In addition, the News Service has defined a single parameter for the service, newsTopic. Before the gear can successfully invoke the News Web service, it must know what newsTopic it should request the headlines for. It is up to the user to set the runtime values to pass to a particular service. While these values could be supplied in a variety of ways (form input, user configuration, JSP value passing, etc.) the Web Services gear only supports configuration of runtime parameters through the user configuration pages.

The user configuration page will expose form input fields for each parameter that can be passed to a particular service. The name and number of these parameters will vary depending on the service you are invoking. The service pages are built up dynamically depending on the WSDL document that the gear installation configuration was supplied with. The user configuration pages will determine all the parameters from the WSDL document that was previously uploaded and then generate the form input on the fly. So, for the News Service the user configuration page would expose a single input box. The name for this input box would be News Topic and then the user would be expected to type in the News topic that they wanted to receive headlines for: financial, technology, etc.

To configure the value of the parameters, follow these steps. (This assumes that the Gear has been installed onto a particular community page).

  1. In the Web Services gear, click the edit button.

    The user configuration page for the gear opens.

  2. Enter or set the appropriate values.

  3. Click the done button.