org.systinet.wasp.webservice
Class ServiceClient

java.lang.Object
  org.systinet.wasp.webservice.ServiceClient

All Implemented Interfaces:

Processing

public abstract class ServiceClient

extends java.lang.Object

implements Processing

This class represents client side of a service which is being called. It represents WSDL service name & port name and/or message processing such as client handlers, interceptors etc. It's factory for invocation under WSDL - dynamic proxy and dynamic calls (DII). Other type of settings is pertained to attributes of invocation: service url, service iface, timeouts, asynchronous transport etc. Common usages are as following:

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) with given SOAP message (see WaspProviderConnection) ...

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

when the service doesn't have WSDL ...

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

Since:

4.5

Component:

Core

Constructor Summary

protected

ServiceClient()

Method Summary

abstract void	addListener(ServiceClientListener listener) Adds service client listener.
static ServiceClient	create() Creates new instance of ServiceClient.
static ServiceClient	create(java.lang.Class iface) Deprecated. use create() and createProxy(java.lang.Class) instead
static ServiceClient	create(ServiceClient serviceClient) Creates new instance of ServiceClient.
static ServiceClient	create(java.lang.String wsdlUrl) Creates new instance of ServiceClient with WSDL from given URL.
static ServiceClient	create(java.lang.String wsdlUrl, java.lang.Class iface) Deprecated. use create(java.lang.String) and createProxy(java.lang.Class) instead
static ServiceClient	create(java.lang.String wsdlUrl, java.lang.Class iface, java.util.Map contextData) Deprecated. use create(java.lang.String, java.util.Map) and createProxy(java.lang.Class) instead
static ServiceClient	create(java.lang.String wsdlUrl, java.lang.Class iface, ServiceClient serviceClient) Deprecated. use create(org.systinet.wasp.webservice.ServiceClient) and createProxy(java.lang.Class) instead
static ServiceClient	create(java.lang.String wsdlUrl, java.util.Map contextData) Creates new instance of ServiceClient with WSDL from given URL.
abstract WaspCall	createCall() Creates new dynamic call object for the port name of this service client WSDL.
abstract WaspCall	createCall(java.lang.String operation) Creates new dynamic call object for given operation and port name of this service client WSDL.
abstract java.lang.Object	createProxy(java.lang.Class iface) Creates new dynamic proxy object with given interface from the port of this service client WSDL.
abstract java.lang.String	getAsyncEndpointPath() Retrieves the path of callback endpoint used during transport coupling.
abstract int	getAsyncTimeout() Deprecated. use AsyncConversation.getTimeout() instead
abstract java.lang.String	getAsyncTransport() Retrieves the name of asynchronous protocol used during transport coupling.
abstract Attributes	getAttributes() Retrieves attributes store bound to this service instance.
abstract CallContext	getCallContext() Gets call context associated with this service client calls.
abstract Configurable	getConfigurable() Retrieves a custom configuration of the service client.
abstract int	getConnectionTimeout() Deprecated. See CallContext.TRANSPORT_CONNECTION_TIMEOUT.
abstract ServiceClientContext	getContext() Retrieves unique context for this service client.
abstract java.lang.Class	getInterface() Deprecated. ServiceClient doesn't remember an interface for created proxy. See createProxy(java.lang.Class).
abstract java.lang.Object	getProxy() Deprecated. use createProxy(java.lang.Class) instead
abstract java.lang.String	getResource(java.lang.String path) Returns the resource with the given name or null if the resource could not be found.
abstract java.io.InputStream	getResourceAsStream(java.lang.String path) Returns an input stream for reading the specified resource or null if the resource could not be found.
abstract java.lang.String	getServiceURL() Gets URL of service location used during service invocation.
abstract Definition	getWSDL() Retrieves WSDL definition for this service client.
abstract java.lang.String	getWSDLLocation() Retrieves URL of WSDL definition for called webservice.
abstract java.lang.String	getWSDLPortName() Returns name of service port in WSDL definition.
abstract QName	getWSDLServiceName() Returns name of service in WSDL.
abstract void	log(java.lang.String msg) Logs a message.
abstract void	log(java.lang.String message, java.lang.Throwable throwable) Logs a message and exception.
abstract void	removeListener(ServiceClientListener listener) Removes service client listener.
abstract void	setAsyncEndpointPath(java.lang.String path) Sets the callback endpoint path for transport coupling.
abstract void	setAsyncTimeout(int timeout) Deprecated. use AsyncConversation.setTimeout(long) instead
abstract void	setAsyncTransport(java.lang.String asyncTransport) Sets the asynchronous protocol used during transport coupling.
abstract void	setConfigurable(Configurable serviceClientConfig) Sets the configuration of the service client.
abstract void	setConnectionTimeout(int timeout) Deprecated. See CallContext.TRANSPORT_CONNECTION_TIMEOUT. You can set timeout for all invocations from this ServiceClient: serviceClient.getContext().getContextData().put(CallContext.TRANSPORT_CONNECTION_TIMEOUT, new Integer(10000)); or timeout for next invocation only: serviceClient.getCallContext().getContextData().put(CallContext.TRANSPORT_CONNECTION_TIMEOUT, new Integer(10000));
abstract void	setInterface(java.lang.Class iface) Deprecated. use createProxy(java.lang.Class) instead
abstract void	setServiceURL(java.lang.String url) Sets service location.
abstract void	setWSDL(Definition wsdl) Sets WSDL definition for this service client.
abstract void	setWSDLLocation(java.lang.String url) Sets WSDL definition URL.
abstract void	setWSDLPortName(java.lang.String portName) Sets name of service port in WSDL definition.
abstract void	setWSDLServiceName(QName serviceName) Sets WSDL definition URL.
abstract void	unpublishAsyncEndpoint() Unpublish callback endpoint if it is published.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.systinet.wasp.webservice.Processing

getHandlers, getHeaderProcessors, getInterceptors

Constructor Detail

ServiceClient

protected ServiceClient()

Method Detail

create

public static ServiceClient create()

Creates new instance of ServiceClient.

Returns:

ServiceClient instance

create

public static ServiceClient create(java.lang.String wsdlUrl)

Creates new instance of ServiceClient with WSDL from given URL.

Parameters:

wsdlUrl - URL used for retrieving WSDL

Returns:

ServiceClient instance

create

public static ServiceClient create(java.lang.String wsdlUrl,
                                   java.util.Map contextData)

Creates new instance of ServiceClient with WSDL from given URL. There can be also specified additional context data that is put into the ServiceClientContext and used during the lookup operation also.

Parameters:

wsdlUrl - URL used for retrieving WSDL

contextData - ServiceClientContext data for this ServiceClient

Returns:

ServiceClient instance

See Also:

ServiceClientContext

create

public static ServiceClient create(ServiceClient serviceClient)

Creates new instance of ServiceClient. Copies settings and processing from supplied service client.

Parameters:

serviceClient - source of other settings that are cloned to newly created instance of ServiceClient.

Returns:

ServiceClient instance

create

public static ServiceClient create(java.lang.Class iface)

Deprecated. use create() and createProxy(java.lang.Class) instead

Creates new instance of ServiceClient.

Parameters:

iface - service interface used during lookup process

Returns:

ServiceClient instance

create

public static ServiceClient create(java.lang.String wsdlUrl,
                                   java.lang.Class iface)

Deprecated. use create(java.lang.String) and createProxy(java.lang.Class) instead

Creates new instance of ServiceClient.

Parameters:

wsdlUrl - WSDL URL used for lookup process

iface - service interface used during lookup process

Returns:

ServiceClient instance

create

public static ServiceClient create(java.lang.String wsdlUrl,
                                   java.lang.Class iface,
                                   java.util.Map contextData)

Deprecated. use create(java.lang.String, java.util.Map) and createProxy(java.lang.Class) instead

Creates new instance of ServiceClient. There can be also specified additional context data that is put into the ServiceClientContext which is created during the lookup operation.

Parameters:

wsdlUrl - WSDL URL used for lookup process

iface - service interface used during lookup process

contextData - data used to configure the lookup operation and stub

Returns:

ServiceClient instance

See Also:

ServiceClientContext

create

public static ServiceClient create(java.lang.String wsdlUrl,
                                   java.lang.Class iface,
                                   ServiceClient serviceClient)

Deprecated. use create(org.systinet.wasp.webservice.ServiceClient) and createProxy(java.lang.Class) instead

Creates new instance of ServiceClient. Copies settings from supplied service client.

Parameters:

wsdlUrl - service url used during lookup process

iface - service interface used during lookup process

serviceClient - source of other settings that are cloned to newly created instance of ServiceClient.

Returns:

ServiceClient instance

getConfigurable

public abstract Configurable getConfigurable()

Retrieves a custom configuration of the service client.

Returns:

the configuration of the service client

setConfigurable

public abstract void setConfigurable(Configurable serviceClientConfig)

Sets the configuration of the service client.

Parameters:

serviceClientConfig -

getContext

public abstract ServiceClientContext getContext()

Retrieves unique context for this service client. This context can be used as a holder of client data etc.

Returns:

service client context

getCallContext

public abstract CallContext getCallContext()

Gets call context associated with this service client calls. This context is per thread so when we are a client in a service you can use it to set some data for client processing before invocation and it will be thread-safe.

Returns:

call context

getAsyncTransport

public abstract java.lang.String getAsyncTransport()

Retrieves the name of asynchronous protocol used during transport coupling. Until lookup is performed with this service client and not explicitly set using setAsyncTransport(java.lang.String) this method returns null. After lookup, async transport is the same as the transport used in service url defined in service wsdl. Transport can be setup explicitly using setAsyncTransport(java.lang.String).

Returns:

asynchronous transport

setAsyncTransport

public abstract void setAsyncTransport(java.lang.String asyncTransport)

Sets the asynchronous protocol used during transport coupling. Overrides all default settings. See getAsyncTransport().

Parameters:

asyncTransport - name of tranport used during transport coupling

getAsyncEndpointPath

public abstract java.lang.String getAsyncEndpointPath()

Retrieves the path of callback endpoint used during transport coupling.

Returns:

asynchronous endpoint path

setAsyncEndpointPath

public abstract void setAsyncEndpointPath(java.lang.String path)

Sets the callback endpoint path for transport coupling. If the path does not begin with slash '/', it is added to the path. See getAsyncEndpointPath().

Parameters:

path - of the asynchronous callback endpoint used during transport coupling

unpublishAsyncEndpoint

public abstract void unpublishAsyncEndpoint()
                                     throws PublishException

Unpublish callback endpoint if it is published. Publishing could be accomplished by using setAsyncEndpointPath(java.lang.String) method or automatically. If the endpoint isn�t published method will return immediately.

Throws:

PublishException

getAsyncTimeout

public abstract int getAsyncTimeout()

Deprecated. use AsyncConversation.getTimeout() instead

Retrieves the timeout for waiting for response when using tranport coupling.

Returns:

timeout in millis

setAsyncTimeout

public abstract void setAsyncTimeout(int timeout)

Deprecated. use AsyncConversation.setTimeout(long) instead

Sets the timeout for waiting for response when using transport coupling.

Parameters:

timeout - in millis

getResource

public abstract java.lang.String getResource(java.lang.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. For the path name "/" returns the location of the client-side packages directory, if some client package for requested service exists.

Parameters:

path - path of the resource

Returns:

the string representation of the resource's URL

getResourceAsStream

public abstract java.io.InputStream getResourceAsStream(java.lang.String path)
                                                 throws java.io.IOException

Returns an input stream for reading the specified resource or null if the resource could not be found.

Parameters:

path - path of the resource

Returns:

the input stream of the resource

Throws:

java.io.IOException - if something goes wrong

log

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

Logs a message.

Parameters:

msg - message to be logged

log

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

Logs a message and exception.

Parameters:

message - the message to be logged

throwable - the exception to be logged

setConnectionTimeout

public abstract void setConnectionTimeout(int timeout)

Deprecated. See CallContext.TRANSPORT_CONNECTION_TIMEOUT. You can set timeout for all invocations from this ServiceClient:

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

or timeout for next invocation only:

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

Sets the connection timeout. If specified timeout is negative connection will use its own default timeout.

Parameters:

timeout - timeout in millis, 0 means no timeout

getConnectionTimeout

public abstract int getConnectionTimeout()

Deprecated. See CallContext.TRANSPORT_CONNECTION_TIMEOUT.

Gets the actually set connection timeout. If specified timeout is negative connection will use its own default timeout.

Returns:

timeout in millis, 0 means no timeout

getInterface

public abstract java.lang.Class getInterface()

Deprecated. ServiceClient doesn't remember an interface for created proxy. See createProxy(java.lang.Class).

Retrieves class of interface used during lookup process.

Returns:

interface class

setInterface

public abstract void setInterface(java.lang.Class iface)

Deprecated. use createProxy(java.lang.Class) instead

Sets service interface.

Parameters:

iface - service interface

createProxy

public abstract java.lang.Object createProxy(java.lang.Class iface)
                                      throws LookupException

Creates new dynamic proxy object with given interface from the port of this service client WSDL.

Parameters:

iface - proxy interface

Returns:

proxy object

Throws:

LookupException - when an error occurs during lookup

getProxy

public abstract java.lang.Object getProxy()

Deprecated. use createProxy(java.lang.Class) instead

Retrieves stub object. This object is created during lookup process (See Registry.lookup(org.systinet.wasp.webservice.ServiceClient).

Returns:

Stub object

createCall

public abstract WaspCall createCall(java.lang.String operation)
                             throws LookupException

Creates new dynamic call object for given operation and port name of this service client WSDL.

Parameters:

operation - operation name

Returns:

new dynamic call

Throws:

LookupException - when an error occurs during lookup

createCall

public abstract WaspCall createCall()
                             throws LookupException

Creates new dynamic call object for the port name of this service client WSDL. The operation name must be specified with Call.setOperationName(javax.xml.namespace.QName) on the call instance.

Returns:

new dynamic call

Throws:

LookupException - when an error occurs during lookup

getWSDL

public abstract Definition getWSDL()
                            throws LookupException

Retrieves WSDL definition for this service client.

Returns:

WSDL definition or null

Throws:

LookupException - when an error occurs during lookup

setWSDL

public abstract void setWSDL(Definition wsdl)

Sets WSDL definition for this service client. If not set, it is automatically set during lookup process. WSDL definition can be also obtain with WSDLReader.readWSDL(java.lang.String), for instance:

 Definition myWSDL = WSDLFactory.newInstance().newWSDLReader().readWSDL(null, "...");

Parameters:

wsdl - WSDL definition.

getWSDLLocation

public abstract java.lang.String getWSDLLocation()

Retrieves URL of WSDL definition for called webservice.

Returns:

URL of WSDL definition

setWSDLLocation

public abstract void setWSDLLocation(java.lang.String url)

Sets WSDL definition URL.

Parameters:

url - WSDL definition URL

getWSDLServiceName

public abstract QName getWSDLServiceName()
                                  throws LookupException

Returns name of service in WSDL.

Returns:

name of service in WSDL

Throws:

LookupException - when an error occurs during lookup

setWSDLServiceName

public abstract void setWSDLServiceName(QName serviceName)

Sets WSDL definition URL.

Parameters:

serviceName - name of service in WSDL

getWSDLPortName

public abstract java.lang.String getWSDLPortName()
                                          throws LookupException

Returns name of service port in WSDL definition.

Returns:

name of service port in WSDL

Throws:

LookupException - when an error occurs during lookup

setWSDLPortName

public abstract void setWSDLPortName(java.lang.String portName)

Sets name of service port in WSDL definition.

Parameters:

portName - name of service port in WSDL

setServiceURL

public abstract void setServiceURL(java.lang.String url)

Sets service location. If none is set, it is taken from supplied wsdl definition.

Parameters:

url - service url

getServiceURL

public abstract java.lang.String getServiceURL()
                                        throws LookupException

Gets URL of service location used during service invocation.

Returns:

service URL

Throws:

LookupException - when an error occurs during lookup

getAttributes

public abstract Attributes getAttributes()

Retrieves attributes store bound to this service instance.

Returns:

attributes store

addListener

public abstract void addListener(ServiceClientListener listener)

Adds service client listener.

Parameters:

listener - listener to add

removeListener

public abstract void removeListener(ServiceClientListener listener)

Removes service client listener.

Parameters:

listener - listener to remove