Package org.jboss.ejb.client

Class 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 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

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

      • 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

      • 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