org.jboss.remoting
Class Client

java.lang.Object
  extended byorg.jboss.remoting.Client
All Implemented Interfaces:
java.io.Serializable

public class Client
extends java.lang.Object
implements java.io.Serializable

Client is a convience class for invoking remote methods for a given subsystem. It is intended to be the main user interface for making remote invocation on the client side.

Version:
$Revision: 1.27 $
Author:
Jeff Haynie, Tom Elrod
See Also:
Serialized Form

Field Summary
static java.lang.String ENABLE_LEASE
          Key for the configuration map passed to the Client constructor to indicate that client should not make initial request to establish lease with server.
static java.lang.String LISTENER_ID_KEY
          Key to be used when tracking callback listeners.
static int MAX_NUM_ONEWAY_THREADS
          Specifies the default number of work threads in the pool for executing one way invocations on the client.
static java.lang.String RAW
          The key to use for the metadata Map passed when making a invoke() call and wish for the invocation payload to be sent as is and not wrapped within a remoting invocation request object.
 
Constructor Summary
Client(java.lang.ClassLoader cl, ClientInvoker invoker, java.lang.String subsystem)
          Deprecated. This constructor should not be used any more as will no longer take into account the classloader specified as a parameter.
Client(java.lang.ClassLoader cl, InvokerLocator locator, java.lang.String subsystem, java.util.Map configuration)
          Deprecated. This constructor should not be used any more as will no longer take into account the classloader specified as a parameter.
Client(InvokerLocator locator)
          Constructs a remoting client with intended target server specified via the lcoator, without specifing a remote subsystem or including any metadata.
Client(InvokerLocator locator, java.util.Map configuration)
          Constructs a remoting client with intended target server specified via the locator and configuration metadata.
Client(InvokerLocator locator, java.lang.String subsystem)
          Constructs a remoting client with intended target server specified via the locator and intended subsystem on server for invocations to be routed to.
Client(InvokerLocator locator, java.lang.String subsystem, java.util.Map configuration)
          Constructs a remoting client with intended target server specified via the locator, intended subsystem on the server for invocations to be routed to, and configuration metadata.
 
Method Summary
 void addConnectionListener(ConnectionListener listener)
          Adds a connection listener that will be notified if/when the connection to the server fails while the client is idle (no calls being made).
 void addConnectionListener(ConnectionListener listener, int pingPeriod)
          Adds a connection listener that will be notified if/when the connection to the server fails while the client is idle (no calls being made).
 void addListener(InvokerCallbackHandler callbackHandler)
          Adds the specified handler as a callback listener for pull (sync) callbacks.
 void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator)
          Adds the specified handler as a callback listener for push (async) callbacks.
 void addListener(InvokerCallbackHandler callbackHandler, InvokerLocator clientLocator, java.lang.Object callbackHandlerObject)
          Adds the specified handler as a callback listener for push (async) callbacks.
 void connect()
          Will cause the underlying transport to make connection to the target server.
 void disconnect()
          Disconnects the underlying transport from the target server.
 java.util.List getCallbacks(InvokerCallbackHandler callbackHandler)
          Gets the callbacks for specified callback handler.
 java.util.Map getConfiguration()
          Gets the configuration map passed when constructing this object.
 ClientInvoker getInvoker()
          Get the client invoker (transport implementation).
 int getMaxNumberOfThreads()
          Gets the maximum number of threads to use within client pool for one way invocations on the client side (meaning oneway invocation is handled by thread in this pool and user's call returns immediately) Default value is MAX_NUM_ONEWAY_THREADS.
 org.jboss.util.threadpool.ThreadPool getOnewayThreadPool()
          Gets the thread pool being used for making one way invocations on the client side.
 java.lang.String getSessionId()
          Gets the session id used when making invocations on server invokers.
 java.lang.String getSubsystem()
          Gets the subsystem being used when routing invocation request on the server side.
 java.lang.Object invoke(java.io.InputStream inputStream, java.lang.Object param)
          Takes an inputstream and wraps a server around.
 java.lang.Object invoke(java.lang.Object param)
          Invokes the server invoker handler with the payload parameter passed.
 java.lang.Object invoke(java.lang.Object param, java.util.Map metadata)
          invoke the method remotely
 void invokeOneway(java.lang.Object param)
          Same as calling invokeOneway(Object param, Map sendPayload, boolean clientSide) with clientSide param being false and a null sendPayload.
 void invokeOneway(java.lang.Object param, java.util.Map sendPayload)
          Same as calling invokeOneway(Object param, Map sendPayload, boolean clientSide) with clientSide param being false.
 void invokeOneway(java.lang.Object param, java.util.Map sendPayload, boolean clientSide)
          Will invoke a oneway call to server without a return object.
 boolean isConnected()
          Indicates if the underlying transport has been connected to the target server.
 boolean removeConnectionListener(ConnectionListener listener)
          Removes specified connection listener.
 void removeListener(InvokerCallbackHandler callbackHandler)
          Removes callback handler as a callback listener from the server (and client in the case that it was setup to receive async callbacks).
 void setInvoker(ClientInvoker invoker)
          Set the client invoker (transport implementation)
 void setMarshaller(Marshaller marshaller)
          Sets the marshaller implementation that should be used by the client invoker (transport).
 void setMaxNumberOfThreads(int numOfThreads)
          Sets the maximum number of threads to use within client pool for one way invocations on the client side (meaning oneway invocation is handled by thread in this pool and user's call returns immediately) Default value is MAX_NUM_ONEWAY_THREADS.
 void setOnewayThreadPool(org.jboss.util.threadpool.ThreadPool pool)
          Sets the thread pool to be used for making one way invocations on the client side.
 void setSessionId(java.lang.String sessionId)
          This will set the session id used when making invocations on server invokers.
 void setSubsystem(java.lang.String subsystem)
          Sets the subsystem being used when routing invocation requests on the server side.
 void setUnMarshaller(UnMarshaller unmarshaller)
          Sets the unmarshaller implementation that should be used by the client invoker (transport).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LISTENER_ID_KEY

public static final java.lang.String LISTENER_ID_KEY
Key to be used when tracking callback listeners.

See Also:
Constant Field Values

MAX_NUM_ONEWAY_THREADS

public static final int MAX_NUM_ONEWAY_THREADS
Specifies the default number of work threads in the pool for executing one way invocations on the client. Value is 10.

See Also:
Constant Field Values

RAW

public static final java.lang.String RAW
The key to use for the metadata Map passed when making a invoke() call and wish for the invocation payload to be sent as is and not wrapped within a remoting invocation request object. This should be used when want to make direct calls on systems outside of remoting (e.g. making a http POST request to a web service).

See Also:
Constant Field Values

ENABLE_LEASE

public static final java.lang.String ENABLE_LEASE
Key for the configuration map passed to the Client constructor to indicate that client should not make initial request to establish lease with server. May be needed when connecting to non-remoting server (especially if using http client only). The value for this should be either a String that java.lang.Boolean can evaluate or a java.lang.Boolean.

See Also:
Constant Field Values
Constructor Detail

Client

public Client(InvokerLocator locator)
       throws java.lang.Exception
Constructs a remoting client with intended target server specified via the lcoator, without specifing a remote subsystem or including any metadata. Same as calling Client(locator, null, null);

Parameters:
locator -
Throws:
java.lang.Exception

Client

public Client(InvokerLocator locator,
              java.util.Map configuration)
       throws java.lang.Exception
Constructs a remoting client with intended target server specified via the locator and configuration metadata. The metadata supplied will be used when creating client invoker (in the case specific data is required) and also for passing along additional data to connection listeners on the server side in the case that the client fails, will be able to use this extra information when notified.

Parameters:
locator -
configuration -
Throws:
java.lang.Exception

Client

public Client(InvokerLocator locator,
              java.lang.String subsystem)
       throws java.lang.Exception
Constructs a remoting client with intended target server specified via the locator and intended subsystem on server for invocations to be routed to.

Parameters:
locator -
subsystem -
Throws:
java.lang.Exception

Client

public Client(InvokerLocator locator,
              java.lang.String subsystem,
              java.util.Map configuration)
       throws java.lang.Exception
Constructs a remoting client with intended target server specified via the locator, intended subsystem on the server for invocations to be routed to, and configuration metadata. The metadata supplied will be used when creating client invoker (in the case specific data is required) and also for passing along additional data to connection listeners on the server side in the case that the client fails, will be able to use this extra information when notified.

Parameters:
locator -
subsystem -
configuration -
Throws:
java.lang.Exception

Client

public Client(java.lang.ClassLoader cl,
              InvokerLocator locator,
              java.lang.String subsystem,
              java.util.Map configuration)
       throws java.lang.Exception
Deprecated. This constructor should not be used any more as will no longer take into account the classloader specified as a parameter.

Constructs a remoting client with intended target server specified via the locator, intended subsystem on the server for invocations to be routed to, and configuration metadata. The metadata supplied will be used when creating client invoker (in the case specific data is required) and also for passing along additional data to connection listeners on the server side in the case that the client fails, will be able to use this extra information when notified.

Parameters:
cl - - the classloader that should be used by remoting
locator -
subsystem -
configuration -
Throws:
java.lang.Exception

Client

public Client(java.lang.ClassLoader cl,
              ClientInvoker invoker,
              java.lang.String subsystem)
       throws java.lang.Exception
Deprecated. This constructor should not be used any more as will no longer take into account the classloader specified as a parameter.

Constructs a remoting client with intended target server specified via the locator and intended subsystem on server for invocations to be routed to.

Parameters:
cl -
invoker -
subsystem -
Throws:
java.lang.Exception
Method Detail

addConnectionListener

public void addConnectionListener(ConnectionListener listener)
Adds a connection listener that will be notified if/when the connection to the server fails while the client is idle (no calls being made). The default behavior is to ping for connection every two seconds.

Parameters:
listener -

addConnectionListener

public void addConnectionListener(ConnectionListener listener,
                                  int pingPeriod)
Adds a connection listener that will be notified if/when the connection to the server fails while the client is idle (no calls being made). The current behavior is to ping the server periodically. The time period is defined by the pingPeriod (which should be in milliseconds).

Parameters:
listener -

removeConnectionListener

public boolean removeConnectionListener(ConnectionListener listener)
Removes specified connection listener. Will return true if it has already been registered, false otherwise.

Parameters:
listener -
Returns:

setSessionId

public void setSessionId(java.lang.String sessionId)
This will set the session id used when making invocations on server invokers. There is a default unique id automatically generated for each Client instance, so unless you have a good reason to set this, do not set this.

Parameters:
sessionId -

getConfiguration

public java.util.Map getConfiguration()
Gets the configuration map passed when constructing this object.

Returns:

getSessionId

public java.lang.String getSessionId()
Gets the session id used when making invocations on server invokers. This is the id that will be used for tracking client connections on the server side, to include client failures that are sent to connection listeners on the server side.

Returns:

isConnected

public boolean isConnected()
Indicates if the underlying transport has been connected to the target server.

Returns:

connect

public void connect()
             throws java.lang.Exception
Will cause the underlying transport to make connection to the target server. This is important for any stateful transports, like socket or multiplex. This is also when a client lease with the server is started.

Throws:
java.lang.Exception

disconnect

public void disconnect()
Disconnects the underlying transport from the target server. Also notifies the target server to terminate client lease. Is important that this method is called when no longer using the remoting client. Otherwise resource will not be cleaned up and if the target server requires a lease, it will be maintained in the background.


getInvoker

public ClientInvoker getInvoker()
Get the client invoker (transport implementation).

Returns:

setInvoker

public void setInvoker(ClientInvoker invoker)
Set the client invoker (transport implementation)

Parameters:
invoker -

getSubsystem

public java.lang.String getSubsystem()
Gets the subsystem being used when routing invocation request on the server side.

Returns:

setSubsystem

public void setSubsystem(java.lang.String subsystem)
Sets the subsystem being used when routing invocation requests on the server side. Specifing a subsystem is only needed when server has multiple handlers registered (which will each have their own associated subsystem).

Parameters:
subsystem -

invoke

public java.lang.Object invoke(java.lang.Object param)
                        throws java.lang.Throwable
Invokes the server invoker handler with the payload parameter passed. Same as calling invoke(param, null);

Parameters:
param -
Returns:
Throws:
java.lang.Throwable

invoke

public java.lang.Object invoke(java.lang.Object param,
                               java.util.Map metadata)
                        throws java.lang.Throwable
invoke the method remotely

Parameters:
param - - payload for the server invoker handler
metadata - - any extra metadata that may be needed by the transport (i.e. GET or POST if using http invoker) or if need to pass along extra data to the server invoker handler.
Returns:
Throws:
java.lang.Throwable

invokeOneway

public void invokeOneway(java.lang.Object param,
                         java.util.Map sendPayload,
                         boolean clientSide)
                  throws java.lang.Throwable
Will invoke a oneway call to server without a return object. This should be used when not expecting a return value from the server and wish to achieve higher performance, since the client will not wait for a return. This is done one of two ways. The first is to pass true as the clientSide param. This will cause the execution of the remote call to be excuted in a new thread on the client side and will return the calling thread before making call to server side. Although, this is optimal for performance, will not know about any problems contacting server.

The second, is to pass false as the clientSide param. This will allow the current calling thread to make the call to the remote server, at which point, the server side processing of the thread will be executed on the remote server in a new executing thread and the client thread will return. This is a little slower, but will know that the call made it to the server.

Parameters:
param -
sendPayload -
clientSide -
Throws:
java.lang.Throwable

setMaxNumberOfThreads

public void setMaxNumberOfThreads(int numOfThreads)
Sets the maximum number of threads to use within client pool for one way invocations on the client side (meaning oneway invocation is handled by thread in this pool and user's call returns immediately) Default value is MAX_NUM_ONEWAY_THREADS.

Parameters:
numOfThreads -

getMaxNumberOfThreads

public int getMaxNumberOfThreads()
Gets the maximum number of threads to use within client pool for one way invocations on the client side (meaning oneway invocation is handled by thread in this pool and user's call returns immediately) Default value is MAX_NUM_ONEWAY_THREADS.

Returns:

getOnewayThreadPool

public org.jboss.util.threadpool.ThreadPool getOnewayThreadPool()
Gets the thread pool being used for making one way invocations on the client side. If one has not be specifically set via configuration or call to set it, will always return instance of org.jboss.util.threadpool.BasicThreadPool.

Returns:

setOnewayThreadPool

public void setOnewayThreadPool(org.jboss.util.threadpool.ThreadPool pool)
Sets the thread pool to be used for making one way invocations on the client side.

Parameters:
pool -

invokeOneway

public void invokeOneway(java.lang.Object param)
                  throws java.lang.Throwable
Same as calling invokeOneway(Object param, Map sendPayload, boolean clientSide) with clientSide param being false and a null sendPayload. Therefore, client thread will not return till it has made remote call.

Parameters:
param -
Throws:
java.lang.Throwable

invokeOneway

public void invokeOneway(java.lang.Object param,
                         java.util.Map sendPayload)
                  throws java.lang.Throwable
Same as calling invokeOneway(Object param, Map sendPayload, boolean clientSide) with clientSide param being false. Therefore, client thread will not return till it has made remote call.

Parameters:
param -
sendPayload -
Throws:
java.lang.Throwable

addListener

public void addListener(InvokerCallbackHandler callbackHandler)
                 throws java.lang.Throwable
Adds the specified handler as a callback listener for pull (sync) callbacks. The invoker server will then collect the callbacks for this specific handler. The callbacks can be retrieved by calling the getCallbacks() method. Note: this will cause the client invoker's client locator to be set to null.

Parameters:
callbackHandler -
Throws:
java.lang.Throwable

addListener

public void addListener(InvokerCallbackHandler callbackHandler,
                        InvokerLocator clientLocator)
                 throws java.lang.Throwable
Adds the specified handler as a callback listener for push (async) callbacks. The invoker server will then callback on this handler (via the server invoker specified by the clientLocator) when it gets a callback from the server handler. Note: passing a null clientLocator will cause the client invoker's client locator to be set to null.

Parameters:
callbackHandler -
clientLocator -
Throws:
java.lang.Throwable

addListener

public void addListener(InvokerCallbackHandler callbackHandler,
                        InvokerLocator clientLocator,
                        java.lang.Object callbackHandlerObject)
                 throws java.lang.Throwable
Adds the specified handler as a callback listener for push (async) callbacks. The invoker server will then callback on this handler (via the server invoker specified by the clientLocator) when it gets a callback from the server handler. Note: passing a null clientLocator will cause the client invoker's client locator to be set to null.

Parameters:
callbackHandler - interface to call on with callback
clientLocator - locator for callback server to callback on
callbackHandlerObject - will be included in the callback object passed upon callback
Throws:
java.lang.Throwable

removeListener

public void removeListener(InvokerCallbackHandler callbackHandler)
                    throws java.lang.Throwable
Removes callback handler as a callback listener from the server (and client in the case that it was setup to receive async callbacks). See addListener().

Parameters:
callbackHandler -
Throws:
java.lang.Throwable

getCallbacks

public java.util.List getCallbacks(InvokerCallbackHandler callbackHandler)
                            throws java.lang.Throwable
Gets the callbacks for specified callback handler. The handler is required because an id is generated for each handler. So if have two callback handlers registered with the same server, no other way to know for which handler to get the callbacks for.

Parameters:
callbackHandler -
Returns:
Throws:
java.lang.Throwable

setMarshaller

public void setMarshaller(Marshaller marshaller)
Sets the marshaller implementation that should be used by the client invoker (transport). This overrides the client's default marshaller (or any set within configuration).

Parameters:
marshaller -

setUnMarshaller

public void setUnMarshaller(UnMarshaller unmarshaller)
Sets the unmarshaller implementation that should be used by the client invoker (transport). This overrides the client's default unmarshaller (or any set within configuration).

Parameters:
unmarshaller -

invoke

public java.lang.Object invoke(java.io.InputStream inputStream,
                               java.lang.Object param)
                        throws java.lang.Throwable
Takes an inputstream and wraps a server around. Then calls the target remoting server and passes a proxy for an inputstream to the server's handler. When the server handler calls on this proxy, it will call back on this server wrapped around this inputstream.

Parameters:
inputStream -
param - invocation payload
Returns:
the return value from the invocation
Throws:
java.lang.Throwable


Copyright ? 1998-2005 JBoss Inc . All Rights Reserved.