Package org.jboss.ejb.client

Class EJBClient

java.lang.Object
org.jboss.ejb.client.EJBClient
public final class EJBClient extends Object
The main Enterprise Beans 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 Details

    • 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:

    • 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:

    • 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:

  • Method Details

    • 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 Enterprise Bean proxy object created by this API.
      Parameters:
      object - the object to test
      Returns:
      true if it is an Enterprise Bean proxy, false otherwise

    • createSessionProxy

      public static <T> T createSessionProxy(StatelessEJBLocator<T> statelessLocator) throws Exception
      Create a new Enterprise Bean 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 Enterprise Beans
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean session.
      Type Parameters:
      T - the view type
      Parameters:
      viewType - the view type class
      appName - the application name
      moduleName - the module name
      beanName - the Enterprise Beans name
      distinctName - the module distinct name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean 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 Enterprise Beans name
      distinctName - the module distinct name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean session.
      Type Parameters:
      T - the view type
      Parameters:
      uri - a URI at which Enterprise Beans may be obtained
      viewType - the view type class
      appName - the application name
      moduleName - the module name
      beanName - the Enterprise Beans name
      distinctName - the module distinct name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean session.
      Type Parameters:
      T - the view type
      Parameters:
      viewType - the view type class
      appName - the application name
      moduleName - the module name
      beanName - the Enterprise Beans name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean 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 Enterprise Beans name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Bean session.
      Type Parameters:
      T - the view type
      Parameters:
      uri - a URI at which Enterprise Beans may be obtained
      viewType - the view type class
      appName - the application name
      moduleName - the module name
      beanName - the Enterprise Beans name
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.CreateException - if an error occurs
      Exception

    • createSession

      public static <T> StatefulEJBLocator<T> createSession(StatelessEJBLocator<T> statelessLocator) throws Exception
      Create a new Enterprise Bean session.
      Type Parameters:
      T - the view type
      Parameters:
      statelessLocator - the stateless locator identifying the stateful Enterprise Beans
      Returns:
      the new Enterprise Beans locator
      Throws:
      jakarta.ejb.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 Enterprise Beans 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 Enterprise Beans 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 Enterprise Beans 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 Enterprise Bean 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 Enterprise Bean 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 jakarta.transaction.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