org.jboss.ejb.client
Class EJBClient

java.lang.Object
  org.jboss.ejb.client.EJBClient

public final class EJBClient
extends Object

The main EJB client API class. This class contains helper methods which may be used to create proxies, open sessions, and associate the current invocation context.

Author:

jpai, David M. Lloyd

Method Summary

static <T> T	asynchronous(T proxy) Get an asynchronous view of a proxy.
static <T> T	createProxy(EJBLocator<T> locator) Create a new proxy for the remote object identified by the given locator.
static <T> T	createProxy(EJBLocator<T> locator, EJBClientContextIdentifier identifier) Creates a new proxy for the remote object identified by the given locator and associates that proxy with the passed identifier
static <T> StatefulEJBLocator<T>	createSession(Class<T> viewType, String appName, String moduleName, String beanName, String distinctName) Create a new EJB session.
static <T> StatefulEJBLocator<T>	createSession(EJBClientContextIdentifier ejbClientContextIdentifier, Class<T> viewType, String appName, String moduleName, String beanName, String distinctName) Create a new EJB session.
static EJBClientContextIdentifier	getEJBClientContextIdentifierFor(Object proxy) Get the EJBClientContextIdentifier associated with the passed EJB proxy.
static Future<?>	getFutureResult() Get the future result of an operation.
static <T> Future<T>	getFutureResult(T operation) Get the future result of an operation.
static <T> EJBLocator<? extends T>	getLocatorFor(T proxy) Get the locator for a proxy, if it has one.
static UserTransaction	getUserTransaction(String targetNodeName) Get a UserTransaction object instance which can be used to control transactions on a specific node.
static boolean	isEJBProxy(Object object) Determine whether an object is indeed a valid EJB proxy object created by this API.

Methods inherited from class java.lang.Object

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

Method Detail

asynchronous

public static <T> T asynchronous(T proxy)
                      throws IllegalArgumentException

Get an asynchronous view of a proxy. Any void method on the proxy will be invoked fully asynchronously without a server round-trip delay. Any method which returns a Future will continue to be asynchronous. Any other method invoked on the returned proxy will return null (the future result can be acquired by wrapping the remote call with getFutureResult(Object) or by using getFutureResult()). If an asynchronous view is passed in, the same view is returned.

Type Parameters:

T - the proxy type

Parameters:

proxy - the proxy interface instance

Returns:

the asynchronous view

Throws:

IllegalArgumentException - if the given object is not a valid proxy

getFutureResult

public static <T> Future<T> getFutureResult(T operation)
                                 throws IllegalStateException

Get the future result of an operation. Should be called in conjunction with asynchronous(Object).

Type Parameters:

T - the result type

Parameters:

operation - the operation

Returns:

the future result

Throws:

IllegalStateException - if the operation is not appropriately given

getFutureResult

public static Future<?> getFutureResult()
                                 throws IllegalStateException

Get the future result of an operation. Should be called in conjunction with asynchronous(Object).

Returns:

the future result

Throws:

IllegalStateException - if the operation is not appropriately given

createProxy

public static <T> T createProxy(EJBLocator<T> locator)
                     throws IllegalArgumentException

Create a new proxy for the remote object identified by the given locator.

Type Parameters:

T - the proxy type

Parameters:

locator - the locator

Returns:

the new proxy

Throws:

IllegalArgumentException - if the locator parameter is null or is invalid

createProxy

public static <T> T createProxy(EJBLocator<T> locator,
                                EJBClientContextIdentifier identifier)

Creates a new proxy for the remote object identified by the given locator and associates that proxy with the passed identifier

Type Parameters:

T - The proxy type

Parameters:

locator - The locator

identifier - The EJB client context identifier to associate this proxy with. Can be null.

Returns:

IllegalArgumentException if the locator null

isEJBProxy

public static boolean isEJBProxy(Object object)

Determine whether an object is indeed a valid EJB proxy object created by this API.

Parameters:

object - the object to test

Returns:

true if it is an EJB proxy, false otherwise

createSession

public static <T> StatefulEJBLocator<T> createSession(Class<T> viewType,
                                                      String appName,
                                                      String moduleName,
                                                      String beanName,
                                                      String distinctName)
                                           throws Exception

Create a new EJB session.

Parameters:

viewType - the view type

appName - the application name

moduleName - the module name

beanName - the EJB name

distinctName - the module distinct name

Returns:

the new session ID

Throws:

Exception - if an error occurs

createSession

public static <T> StatefulEJBLocator<T> createSession(EJBClientContextIdentifier ejbClientContextIdentifier,
                                                      Class<T> viewType,
                                                      String appName,
                                                      String moduleName,
                                                      String beanName,
                                                      String distinctName)
                                           throws Exception

Create a new EJB session.

Parameters:

ejbClientContextIdentifier - The EJB client context identifier. Can be null in which case the session will be created using the current active EJB client context

viewType - the view type

appName - the application name

moduleName - the module name

beanName - the EJB name

distinctName - the module distinct name

Returns:

the new session ID

Throws:

Exception - if an error occurs

getLocatorFor

public static <T> EJBLocator<? extends T> getLocatorFor(T proxy)
                                             throws IllegalArgumentException

Get the locator for a proxy, if it has one.

Parameters:

proxy - the proxy

Returns:

the locator

Throws:

IllegalArgumentException - if the given proxy is not a valid client proxy instance

getEJBClientContextIdentifierFor

public static EJBClientContextIdentifier getEJBClientContextIdentifierFor(Object proxy)
                                                                   throws IllegalArgumentException

Get the EJBClientContextIdentifier associated with the passed EJB proxy. If no EJBClientContextIdentifier is associated with the proxy then this method returns null.

Parameters:

proxy - The EJB proxy

Returns:

Throws:

IllegalArgumentException - If the passed proxy is not a valid EJB proxy

getUserTransaction

public static UserTransaction getUserTransaction(String targetNodeName)

Get a UserTransaction object instance which can be used to control transactions on a specific node.

Parameters:

targetNodeName - the node name

Returns:

the UserTransaction instance

Throws:

IllegalStateException - if the transaction context isn't set or cannot provide a UserTransaction instance