Client Settings (ServiceClient)

Client Settings (ServiceClient) ^Locate

Overview: ServiceClient ^Locate

The client side of a service which is being invoked is represented by the org.systinet.wasp.webservice.ServiceClient class. Using this class, one can fully set up message processing utilities such as client handlers, interceptors, etc. ServiceClient is the factory for invocation under WSDL: dynamic proxy and dynamic calls (DII). Other settings pertain to attributes of the invocation: service url, service iface, time-outs, asynchronous transport, etc.

You can use Registry.lookup to create a dynamic proxy. It creates a hidden instance of ServiceClient automatically, with default configuration (see Dynamic Proxy Invocation). You cannot specify another configuration from the client application in this case. When you want control over the client configuration, you must create ServiceClient directly. A ServiceClient instance is used to obtain a dynamic proxy or dynamic call via the createProxy(Class) or createCall(String) method, respectively. It is also used for custom configuration of client processing (see Client Custom Configuration).

One common usecase of ServiceClient is for creating a client and invoking the service when the service's WSDL requires authentication, as described in Looking Up a Secure Service.

One instance of ServiceClient can be used in only one lookup. The relationship between ServiceClient and the looked-up proxy is thus 1-1.

The four use cases follow:

Invocation via dynamic proxy

ServiceClient client = 
                    ServiceClient.create("http://localhost:6060/HelloWorld/wsdl");
client.set...; 
MyService proxy = (MyService)client.createProxy(MyService.class); 
proxy.hello(...);

Invocation with dynamic call

ServiceClient client = 
                    ServiceClient.create("http://localhost:6060/HelloWorld/wsdl");
client.set...; 
WaspCall call = client.createCall("hello");
call.invoke(...);

Calling service with WSDL (or nonblocked send) for a given SOAP message

ServiceClient client =
          ServiceClient.create("http://localhost:6060/HelloWorld/wsdl");
client.set...; 
SOAPMessage request = msgFactory.createMessage();
request... SOAPMessage response = connection.call(request, client);

Calling a service that does not have a WSDL

ServiceClient client = ServiceClient.create();
client.setServiceURL("http://localhost:6060/HelloWorld");

Creation ^Locate

The following methods are for creating instances of ServiceClient:

```
public static ServiceClient create();
```
This is useful when the service does not have a WSDL, such as in JAXM messaging.
```
public static ServiceClient create(String wsdlUrl);
```
This lets you specify the WSDL location of the service that this service client will communicate with.
```
public static ServiceClient create(String wsdlUrl, Map contextData);
```
As in step 2 above, but it also lets you specify the context data. This data is used during the service call on the client side.
```
public static ServiceClient create(ServiceClient serviceClient);
```
A "copy constructor." Use this when you already have a ServiceClient configured and you want to create another ServiceClient with the same customized settings.

Settings ^Locate

```
public abstract Configurable getConfigurable();
```
```
public abstract void setConfigurable(Configurable serviceClientConfig);
```
Enables user to customize the runtime configuration of the service client using the WSO2 SOA Enablement Server configurationframework.
```
public abstract ServiceClientContext getContext();
```
Returns the service client context. This context is created during the creation process. Its main use is to enable the storage of additional data for use during the service call, that is, by the interceptor. This call context is accessible on the client side during the call, from getCallContext().
```
public abstract CallContext getCallContext();
```
Gets the service client's call context. The user can prepare data used only for the one service call. This data is automatically erased from the context at the end of the service call. This call context is accessible on the client side during the call, from getCallContext().
```
public abstract String getServiceURL();
```
```
public abstract void setServiceURL(String url);
```
Sets and returns the URL of the service location, or null if none is set. In the latter case, the WSDL definition is examined for the service URL at lookup.

ServiceClientListener ^Locate

In general, a listener is an object that "listens" for events from another specific object. ServiceClientListener listens for a ServiceClient object being looked up.

Each ServiceClientListener must implement the following interface:

public interface ServiceClientListener {
    void onLookup(ServiceClient serviceClient) throws LookupException;
}

ServiceClientListeners can be registered as either global or local.

Global listeners must be registered on Registry via the Registry.addListener(ServiceClientListener listener) method and they are invoked whenever any service client is looked up.

Local listeners are registered on a specific ServiceClient via the ServiceClient.addListener(ServiceClientListener listener) method and called only when that particular service client is looked up.

For more information, please see the Javadoc org.systinet.wasp.webservice.ServiceClientListener.

WSDL Settings ^Locate

These WSDL settings are used during the lookup process only.

```
public abstract Definition getWSDL();
```
Retrieves the WSDL definition for the service client or null if none is set.
```
public abstract void setWSDL(Definition wsdl);
```
Sets the WSDL definition for the service client. If not set here, it is set automatically during lookup. The WSDL definition can be obtained with javax.wsdl.xml.WSDLReader.

public abstract String getWSDLLocation();

public abstract void setWSDLLocation(String url);

Sets and returns the URL for the WSDL definition.

public abstract QName getWSDLServiceName();

public abstract void setWSDLServiceName(QName serviceName);

Sets and returns the name of the service in WSDL.

public abstract String getWSDLPortName();

public abstract void setWSDLPortName(String portName);

Sets and returns the name of the service port in the WSDL definition.

Connection Settings ^Locate

To set connection timeout, use CallContext.TRANSPORT_CONNECTION_TIMEOUT instead.

To set timeout for all invocations from this ServiceClient:

serviceClient.getContext().getContextData().put(CallContext.TRANSPORT_CONNECTION_TIMEOUT, new Integer(10000));

To set timeout for next invocation only:

serviceClient.getCallContext().getContextData().put(CallContext.TRANSPORT_CONNECTION_TIMEOUT, new Integer(10000));

	Note
	The methods `getConnectionTimeout()` and `setConnectionTimeout()` are deprecated.

Other Methods ^Locate

```
public abstract String getResource(String path);
```
Returns the resource with the given name or null if the resource could not be found. The name of a resource is a "/"-separated path name that identifies the resource. If "/" is used as the path name, the method returns the location of the client-side service directory.
```
public abstract InputStream getResourceAsStream(String path) throws IOException;
```
As getResource(String path) above, except returns the input stream of the resource rather than the resource itself.

public abstract void log(java.lang.String msg);

Logs a message.

public abstract void log(java.lang.String message, java.lang.Throwable throwable);

Logs a message and exception.