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

Field Summary

Fields

Modifier and Type	Field and Description
static String	CLUSTER_AFFINITY A JNDI context key which, if defined, identifies that the proxy to be created should have affinity to the cluster.
static String	DISABLE_AFFINITY_LEARNING A JNDI context key which, if defined, disables learning in the case of an unspecified CLUSTER_AFFINITY
static String	SOURCE_ADDRESS_KEY An invocation context key which is set to the source socket address of the invocation request, if any.

Method Summary

Modifier and Type	Method and Description
static <T> T	asynchronous(T proxy) Get an asynchronous view of a proxy.
static void	clearInvocationTimeout(Object proxy) Clear the per-proxy invocation timeout, causing it to use the globally configured timeout.
static boolean	compareAndSetStrongAffinity(Object proxy, Affinity expectedAffinity, Affinity newAffinity) Compare and change the strong affinity of a proxy.
static void	convertToStateful(Object proxy, SessionID sessionID) Convert a non-stateful proxy to be stateful.
static <T> T	createProxy(EJBLocator<T> locator) Create a new proxy for the remote object identified by the given locator.
static <T> StatefulEJBLocator<T>	createSession(Affinity affinity, Class<T> viewType, String appName, String moduleName, String beanName) Create a new EJB session.
static <T> StatefulEJBLocator<T>	createSession(Affinity affinity, Class<T> viewType, String appName, String moduleName, String beanName, String distinctName) Create a new EJB session.
static <T> StatefulEJBLocator<T>	createSession(Class<T> viewType, String appName, String moduleName, String beanName) Create a new EJB session.
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(StatelessEJBLocator<T> statelessLocator) Create a new EJB session.
static <T> StatefulEJBLocator<T>	createSession(URI uri, Class<T> viewType, String appName, String moduleName, String beanName) Create a new EJB session.
static <T> StatefulEJBLocator<T>	createSession(URI uri, Class<T> viewType, String appName, String moduleName, String beanName, String distinctName) Create a new EJB session.
static <T> T	createSessionProxy(StatelessEJBLocator<T> statelessLocator) Create a new EJB session 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 <T> T	getProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey) Get a proxy attachment.
static Affinity	getStrongAffinity(Object proxy) Get the strong affinity of a proxy.
static UserTransaction	getUserTransaction(String targetNodeName) Deprecated.
static Affinity	getWeakAffinity(Object proxy) Get the current weak affinity of a proxy.
static <T> Object	invoke(T proxy, EJBMethodLocator methodLocator, Object... args) Perform an invocation by method locator on a proxy, returning the result.
static <T> Future<?>	invokeAsync(T proxy, EJBMethodLocator methodLocator, Object... args) Perform an asynchronous invocation by method locator on a proxy, returning the future result.
static <T> void	invokeOneWay(T proxy, EJBMethodLocator methodLocator, Object... args) Perform a one-way asynchronous invocation by method locator on a proxy.
static boolean	isEJBProxy(Object object) Determine whether an object is indeed a valid EJB proxy object created by this API.
static <T> T	putProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey, T newValue) Set a proxy attachment.
static <T> T	putProxyAttachmentIfAbsent(Object proxy, AttachmentKey<T> attachmentKey, T newValue) Set a proxy attachment if it is not already set.
static <T> T	removeProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey) Remove a proxy attachment.
static <T> boolean	removeProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey, T oldValue) Remove a proxy attachment with a particular value.
static <T> T	replaceProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey, T newValue) Replace a proxy attachment if it is already present.
static <T> boolean	replaceProxyAttachment(Object proxy, AttachmentKey<T> attachmentKey, T oldValue, T newValue) Replace a proxy attachment if it is already present.
static void	setInvocationTimeout(Object proxy, long timeout, TimeUnit timeUnit) Set a per-proxy invocation timeout.
static void	setStrongAffinity(Object proxy, Affinity newAffinity) Change the strong affinity of a proxy.
static void	setWeakAffinity(Object proxy, Affinity newAffinity) Change the weak affinity of a proxy.
static void	transformStrongAffinity(Object proxy, UnaryOperator<Affinity> transformOperator) Transform the strong affinity of a proxy.

Methods inherited from class java.lang.Object

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

Field Detail

SOURCE_ADDRESS_KEY

public static final String SOURCE_ADDRESS_KEY

An invocation context key which is set to the source socket address of the invocation request, if any. The value will be of type SocketAddress.

See Also:

Constant Field Values

CLUSTER_AFFINITY

public static final String CLUSTER_AFFINITY

A JNDI context key which, if defined, identifies that the proxy to be created should have affinity to the cluster.

See Also:

Constant Field Values

DISABLE_AFFINITY_LEARNING

public static final String DISABLE_AFFINITY_LEARNING

A JNDI context key which, if defined, disables learning in the case of an unspecified CLUSTER_AFFINITY

See Also:

Constant Field Values

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

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

createSessionProxy

public static <T> T createSessionProxy(StatelessEJBLocator<T> statelessLocator)
                                throws Exception

Create a new EJB session proxy. The returned proxy will be cluster-aware if a cluster affinity is used in the locator.

Type Parameters:

T - the view type

Parameters:

statelessLocator - the stateless locator identifying the stateful EJB

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

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.

Type Parameters:

T - the view type

Parameters:

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

distinctName - the module distinct name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

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

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

affinity - the affinity specification for the session

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

distinctName - the module distinct name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

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

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

uri - a URI at which EJBs may be obtained

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

distinctName - the module distinct name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

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

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

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

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

affinity - the affinity specification for the session

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

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

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

uri - a URI at which EJBs may be obtained

viewType - the view type class

appName - the application name

moduleName - the module name

beanName - the EJB name

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

createSession

public static <T> StatefulEJBLocator<T> createSession(StatelessEJBLocator<T> statelessLocator)
                                               throws Exception

Create a new EJB session.

Type Parameters:

T - the view type

Parameters:

statelessLocator - the stateless locator identifying the stateful EJB

Returns:

the new EJB locator

Throws:

CreateException - if an error occurs

Exception

invokeOneWay

public static <T> void invokeOneWay(T proxy,
                                    EJBMethodLocator methodLocator,
                                    Object... args)
                             throws Exception

Perform a one-way asynchronous invocation by method locator on a proxy. Any return value is ignored.

Type Parameters:

T - the view type

Parameters:

proxy - the EJB proxy

methodLocator - the method locator

args - the invocation arguments

Throws:

Exception - if the invocation failed for some reason

invokeAsync

public static <T> Future<?> invokeAsync(T proxy,
                                        EJBMethodLocator methodLocator,
                                        Object... args)
                                 throws Exception

Perform an asynchronous invocation by method locator on a proxy, returning the future result.

Type Parameters:

T - the view type

Parameters:

proxy - the EJB proxy

methodLocator - the method locator

args - the invocation arguments

Throws:

Exception - if the invocation failed for some reason

invoke

public static <T> Object invoke(T proxy,
                                EJBMethodLocator methodLocator,
                                Object... args)
                         throws Exception

Perform an invocation by method locator on a proxy, returning the result.

Type Parameters:

T - the view type

Parameters:

proxy - the EJB proxy

methodLocator - the method locator

args - the invocation arguments

Throws:

Exception - if the invocation failed for some reason

getLocatorFor

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

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

Type Parameters:

T - the proxy type

Parameters:

proxy - the proxy (may not be null)

Returns:

the locator

Throws:

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

setInvocationTimeout

public static void setInvocationTimeout(Object proxy,
                                        long timeout,
                                        TimeUnit timeUnit)
                                 throws IllegalArgumentException

Set a per-proxy invocation timeout. This overrides the globally configured timeout.

Parameters:

proxy - the proxy to change (must not be null, must be a valid EJB proxy)

timeout - the amount of time (must be greater than zero)

timeUnit - the time unit (must not be null)

Throws:

IllegalArgumentException - if the timeout is less than or equal to zero or a required parameter is null or invalid

clearInvocationTimeout

public static void clearInvocationTimeout(Object proxy)
                                   throws IllegalArgumentException

Clear the per-proxy invocation timeout, causing it to use the globally configured timeout.

Parameters:

proxy - the proxy to change (must not be null, must be a valid EJB proxy)

Throws:

IllegalArgumentException - if the proxy is null or is not valid

setStrongAffinity

public static void setStrongAffinity(Object proxy,
                                     Affinity newAffinity)
                              throws IllegalArgumentException,
                                     SecurityException

Change the strong affinity of a proxy. All subsequent invocations against the proxy will use the new affinity. Subsequent calls to getLocatorFor(Object) for the given proxy will return the updated locator.

Parameters:

proxy - the proxy (may not be null)

newAffinity - the new affinity (may not be null)

Throws:

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

SecurityException - if a security manager is present and the caller does not have the changeStrongAffinity EJBClientPermission

getStrongAffinity

public static Affinity getStrongAffinity(Object proxy)
                                  throws IllegalArgumentException

Get the strong affinity of a proxy. This is a shortcut for getLocatorFor(proxy).getAffinity().

Parameters:

proxy - the proxy (may not be null)

Returns:

the proxy strong affinity

Throws:

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

compareAndSetStrongAffinity

public static boolean compareAndSetStrongAffinity(Object proxy,
                                                  Affinity expectedAffinity,
                                                  Affinity newAffinity)
                                           throws IllegalArgumentException,
                                                  SecurityException

Compare and change the strong affinity of a proxy. All subsequent invocations against the proxy will use the new affinity. Subsequent calls to getLocatorFor(Object) for the given proxy will return the updated locator. If the affinity is not equal to the expected value, false is returned and no change is made.

Parameters:

proxy - the proxy (may not be null)

newAffinity - the new affinity (may not be null)

Throws:

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

SecurityException - if a security manager is present and the caller does not have the changeStrongAffinity EJBClientPermission

transformStrongAffinity

public static void transformStrongAffinity(Object proxy,
                                           UnaryOperator<Affinity> transformOperator)
                                    throws IllegalArgumentException,
                                           SecurityException

Transform the strong affinity of a proxy. All subsequent invocations against the proxy will use the new affinity. Subsequent calls to getLocatorFor(Object) for the given proxy will return the updated locator.

Parameters:

proxy - the proxy (may not be null)

transformOperator - the operator to apply to acquire the new affinity from the old one (may not be null)

Throws:

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

SecurityException - if a security manager is present and the caller does not have the changeStrongAffinity EJBClientPermission

setWeakAffinity

public static void setWeakAffinity(Object proxy,
                                   Affinity newAffinity)
                            throws IllegalArgumentException,
                                   SecurityException

Change the weak affinity of a proxy. All subsequent invocations against the proxy will use the new affinity.

Parameters:

proxy - the proxy (may not be null)

newAffinity - the new affinity (may not be null)

Throws:

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

SecurityException - if a security manager is present and the caller does not have the changeWeakAffinity EJBClientPermission

getWeakAffinity

public static Affinity getWeakAffinity(Object proxy)
                                throws IllegalArgumentException

Get the current weak affinity of a proxy.

Parameters:

proxy - the proxy (must not be null)

Returns:

the affinity (not null)

Throws:

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

convertToStateful

public static void convertToStateful(Object proxy,
                                     SessionID sessionID)
                              throws IllegalArgumentException

Convert a non-stateful proxy to be stateful. If the proxy was already stateful and the session ID matches, the proxy is unchanged. If the proxy was otherwise already stateful, an exception is thrown. Subsequent calls to getLocatorFor(Object) for the given proxy will return the updated locator.

Parameters:

proxy - the proxy to convert (must not be null)

sessionID - the session ID to use for the stateful locator (must not be null)

Throws:

IllegalArgumentException - if the given proxy is not a valid client proxy instance, or the proxy is already stateful with a different session ID

getUserTransaction

@Deprecated
public static UserTransaction getUserTransaction(String targetNodeName)

Deprecated.

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

Parameters:

targetNodeName - the node name (ignored)

Returns:

the UserTransaction instance

Throws:

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

getProxyAttachment

public static <T> T getProxyAttachment(Object proxy,
                                       AttachmentKey<T> attachmentKey)
                                throws IllegalArgumentException

Get a proxy attachment.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

Returns:

the attachment value or null if the attachment is not present

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

putProxyAttachment

public static <T> T putProxyAttachment(Object proxy,
                                       AttachmentKey<T> attachmentKey,
                                       T newValue)
                                throws IllegalArgumentException

Set a proxy attachment.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

newValue - the new value to set (must not be null)

Returns:

the previous attachment value or null if the attachment previously did not exist

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

putProxyAttachmentIfAbsent

public static <T> T putProxyAttachmentIfAbsent(Object proxy,
                                               AttachmentKey<T> attachmentKey,
                                               T newValue)
                                        throws IllegalArgumentException

Set a proxy attachment if it is not already set.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

newValue - the new value to set (must not be null)

Returns:

the previous attachment value or null if the attachment previously did not exist

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

removeProxyAttachment

public static <T> T removeProxyAttachment(Object proxy,
                                          AttachmentKey<T> attachmentKey)
                                   throws IllegalArgumentException

Remove a proxy attachment.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

Returns:

the previous attachment value or null if the attachment previously did not exist

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

removeProxyAttachment

public static <T> boolean removeProxyAttachment(Object proxy,
                                                AttachmentKey<T> attachmentKey,
                                                T oldValue)
                                         throws IllegalArgumentException

Remove a proxy attachment with a particular value.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

oldValue - the new value to set (must not be null)

Returns:

true if the attachment was removed, or false if the value did not match or was not present

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

replaceProxyAttachment

public static <T> T replaceProxyAttachment(Object proxy,
                                           AttachmentKey<T> attachmentKey,
                                           T newValue)
                                    throws IllegalArgumentException

Replace a proxy attachment if it is already present.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

newValue - the new value to set (must not be null)

Returns:

the previous attachment value or null if the attachment previously did not exist

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy

replaceProxyAttachment

public static <T> boolean replaceProxyAttachment(Object proxy,
                                                 AttachmentKey<T> attachmentKey,
                                                 T oldValue,
                                                 T newValue)
                                          throws IllegalArgumentException

Replace a proxy attachment if it is already present.

Type Parameters:

T - the value type

Parameters:

proxy - the proxy (must not be null)

attachmentKey - the attachment key to use (must not be null)

newValue - the old value to replace (must not be null)

Returns:

true if the attachment value was replaced, false otherwise

Throws:

IllegalArgumentException - if a required parameter is null or if the object is not a valid EJB client proxy