Web Service Clients

Web Service Clients ^Locate

Overview ^Locate

There are multiple ways of creating and running clients for Web services in WSO2 SOA Enablement Server for Java. Clients may use several types of invocation scenarios, invoke a service synchronously or asynchronously or use WSO2 SOA Enablement Server security features. Clients can be run with libraries from WSO2 SOA Enablement Server server during development. For production you may create a client distribution described later.

	Tip
	To see how to create a very simple client, please read Web Service Clients. It shows how to create a client for the most common invocation scenario (Dynamic proxy).

Setting Up the Client Environment ^Locate

There are two ways to set up the client environment:

For testing clients: We assume you have WSO2 SOA Enablement Server installed. In this case add the correct master JAR to the classpath from the WASP_HOME/lib directory. This JAR references all other necessary JARs. For clients without security, the master JAR is wasp.jar. For clients with security, it is security_providers_client.jar. For information on setting up security providers client-side, please see Client-Side Security.
For production: If you do not need the server-side of WSO2 SOA Enablement Server for Java, you can install the client-side only. This can be done automatically in the installation process, either through selecting a client installation or through assembling the components you want in a custom installation, as described in Installation Types.
We have developed a set of common installation scenarios, including client-side only. They are described and the components required for each are listed in Installation Scenarios.
Client structure, required JAR files and the setting of global WSO2 SOA Enablement Server properties is described in WSO2 SOA Enablement Server Configuration.

Invocation Scenarios ^Locate

WSO2 SOA Enablement Server supports three scenarios of creating and running a client (ordered from the simplest to the most complicated cases). In all scenarios the target service can be called asynchronously or synchronously:

Dynamic proxy (Java client)
WSO2 SOA Enablement Server generates interfaces/SOAP mapping from the WSDL document. At development time, a user simply calls methods on these interfaces. This approach is suitable for most applications. It is covered under Web Service Clients.
Note that WSO2 SOA Enablement Server also supports the generation of dynamic proxies with the JAX-RPC API. WSO2 SOA Enablement Server does not currently support statically generated stubs created with JAX-RPC.
JAX-RPC DII call (Java client)
JAX-RPC is a set of Java APIs designed to support emerging industry XML based RPC standards. At runtime, the user supplies the name of the operation or the names and values of arguments. WSO2 SOA Enablement Server then downloads the WSDL document from specified URL, selects the correct operation, maps arguments and calls the target Web service.
JAXM/SAAJ call (XML/SOAP client)
JAXM is a set of APIs designed specifically for the exchange of SAAJ messages. This message can be processed with SAAJ's DOM-like API or WSO2 SOA Enablement Server's proprietary stream-based extension of SAAJ.

UDDI Client Lookup ^Locate

WSO2 Registry allows you to look up Web services registered in UDDI using the UDDI Lookup Address (ULA). This type of lookup follows best practices and open recommendations. These principles can be used not only for a WSO2 SOA Enablement Server client and the WSO2 SOA Enablement Server UDDI registry but also for other registries that support the Using WSDL in UDDI v2.0 best practice document. For more information, please see Service Lookup via UDDI.

WSDL URL - Best Practices ^Locate

When deploying a service into WSO2 SOA Enablement Server for Java, the service URL must be specified.A WSDL document associated with this service is accessible at the WSDL URL. The WSDL document references the service URLs of all services described in the document. In WSO2 SOA Enablement Server for Java, the WSDL URL always consists of the whole service URL with the suffix /wsdl appended. For example, if your service is exposed at the service URL http://service/endpoint/path, the WSDL document describing this service will be accessible at http://service/endpoint/path/wsdl.

Note

	Note
Although not recommended, in older versions of SSJ might trying to get the WSDL document from service URL instead of WSDL URL succeed. However, in the latest versions of WSO2 SOA Enablement Server for Java trying this may fail especially when your WSDL document relatively references other documents (WSDL, XML Schema). To be sure that your client always gets the correct WSDL document as well as all referenced documents, follow the best practices summarized below: Service URL should not end with a slash. The service URL `http://service/endpoint/path` is correct. The service URL `http://service/endpoint/path/` is not correct. Always get WSDL document from the WSDL URL. Getting the document from `http://service/endpoint/path/wsdl` is correct. Getting it from `http://service/endpoint/path` is not correct. Never use `..` when referencing other documents from the main WSDL document.

Although not recommended, in older versions of SSJ might trying to get the WSDL document from service URL instead of WSDL URL succeed. However, in the latest versions of WSO2 SOA Enablement Server for Java trying this may fail especially when your WSDL document relatively references other documents (WSDL, XML Schema).

To be sure that your client always gets the correct WSDL document as well as all referenced documents, follow the best practices summarized below:

Service URL should not end with a slash.
- The service URL http://service/endpoint/path is correct.
- The service URL http://service/endpoint/path/ is not correct.
Always get WSDL document from the WSDL URL.
- Getting the document from http://service/endpoint/path/wsdl is correct.
- Getting it from http://service/endpoint/path is not correct.
Never use .. when referencing other documents from the main WSDL document.