org.jboss.ejb.client
Class EJBClientContext

java.lang.Object
  org.jboss.ejb.client.Attachable
      org.jboss.ejb.client.EJBClientContext

All Implemented Interfaces:

Closeable

public final class EJBClientContext
extends Attachable
implements Closeable

The public API for an EJB client context. An EJB client context may be associated with (and used by) one or more threads concurrently.

Author:

David M. Lloyd

Method Summary

void	close() Closes the EJB client context and notifies any registered EJBClientContextListeners about the context being closed.
static EJBClientContext	create() Creates and returns a new client context.
static EJBClientContext	create(ClassLoader classLoader) Creates and returns a new client context, using the given class loader to look for initializers.
static EJBClientContext	create(EJBClientConfiguration ejbClientConfiguration) Creates and returns a new client context.
static EJBClientContext	create(EJBClientConfiguration ejbClientConfiguration, ClassLoader classLoader) Creates and returns a new client context, using the given class loader to look for initializers.
protected void	finalize()
ClusterContext	getClusterContext(String clusterName) Deprecated.
static EJBClientContext	getCurrent() Get the current client context for this thread.
EJBClientConfiguration	getEJBClientConfiguration() Returns the EJBClientConfiguration applicable to this EJB client context.
ClusterContext	getOrCreateClusterContext(String clusterName) Deprecated.
static ContextSelector<EJBClientContext>	getSelector() Returns the current EJB client context selector
static boolean	isSelectorLocked() Returns true if the EJB client context cannot be changed because it has been lockSelector().
static void	lockSelector() Prevent the selector from being changed again.
void	registerConnection(org.jboss.remoting3.Connection connection) Deprecated.
void	registerConnection(org.jboss.remoting3.Connection connection, String remotingProtocol) Register a Remoting connection with this client context.
boolean	registerEJBClientContextListener(EJBClientContextListener listener) Registers a EJBClientContextListener for this EJBClientContext.
boolean	registerEJBReceiver(EJBReceiver receiver) Register an EJB receiver with this client context.
EJBClientInterceptor.Registration	registerInterceptor(int priority, EJBClientInterceptor clientInterceptor) Register a client interceptor with this client context.
void	registerReconnectHandler(ReconnectHandler reconnectHandler) Registers a ReconnectHandler in this EJBClientContext
void	removeCluster(String clusterName) Deprecated.
static EJBClientContext	require(EJBClientContextIdentifier ejbClientContextIdentifier) Returns a EJBClientContext which is identified by the passed ejbClientContextIdentifier.
static EJBClientContext	requireCurrent() Get the current client context for this thread, throwing an exception if none is set.
static ContextSelector<EJBClientContext>	setConstantContext(EJBClientContext context) Set a constant EJB client context.
static ContextSelector<EJBClientContext>	setSelector(ContextSelector<EJBClientContext> newSelector) Sets the EJB client context selector.
void	unregisterEJBReceiver(EJBReceiver receiver) Unregister (a previously registered) EJB receiver from this client context.
void	unregisterReconnectHandler(ReconnectHandler reconnectHandler) Unregisters a ReconnectHandler from this EJBClientContext

Methods inherited from class org.jboss.ejb.client.Attachable

getAttachment, getAttachments, putAttachment, putAttachmentIfAbsent, removeAttachment, removeAttachment, replaceAttachment, replaceAttachment

Methods inherited from class java.lang.Object

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

Method Detail

create

public static EJBClientContext create()

Creates and returns a new client context.

Returns:

the newly created context

create

public static EJBClientContext create(ClassLoader classLoader)

Creates and returns a new client context, using the given class loader to look for initializers.

Parameters:

classLoader - the class loader. Cannot be null

Returns:

the newly created context

create

public static EJBClientContext create(EJBClientConfiguration ejbClientConfiguration)

Creates and returns a new client context. The passed ejbClientConfiguration will be used by this client context during any of the context management activities (like auto-creation of remoting EJB receivers)

Parameters:

ejbClientConfiguration - The EJB client configuration. Can be null.

Returns:

create

public static EJBClientContext create(EJBClientConfiguration ejbClientConfiguration,
                                      ClassLoader classLoader)

Creates and returns a new client context, using the given class loader to look for initializers. The passed ejbClientConfiguration will be used by this client context during any of the context management activities (like auto-creation of remoting EJB receivers)

Parameters:

ejbClientConfiguration - The EJB client configuration. Can be null.

classLoader - The class loader. Cannot be null

Returns:

setSelector

public static ContextSelector<EJBClientContext> setSelector(ContextSelector<EJBClientContext> newSelector)

Sets the EJB client context selector. Replaces the existing selector, which is then returned by this method

Parameters:

newSelector - The selector to set. Cannot be null

Returns:

Returns the previously set EJB client context selector.

Throws:

SecurityException - if a security manager is installed and you do not have the setEJBClientContextSelector RuntimePermission

setConstantContext

public static ContextSelector<EJBClientContext> setConstantContext(EJBClientContext context)

Set a constant EJB client context. Replaces the existing selector, which is then returned by this method

Parameters:

context - the context to set

Returns:

Returns the previously set EJB client context selector.

Throws:

SecurityException - if a security manager is installed and you do not have the setEJBClientContextSelector RuntimePermission

getSelector

public static ContextSelector<EJBClientContext> getSelector()

Returns the current EJB client context selector

Returns:

lockSelector

public static void lockSelector()

Prevent the selector from being changed again. Attempts to do so will result in a SecurityException.

Throws:

SecurityException - if a security manager is installed and you do not have the setEJBClientContextSelector RuntimePermission

isSelectorLocked

public static boolean isSelectorLocked()

Returns true if the EJB client context cannot be changed because it has been lockSelector(). Returns false otherwise.

Returns:

getCurrent

public static EJBClientContext getCurrent()

Get the current client context for this thread.

Returns:

the current client context

requireCurrent

public static EJBClientContext requireCurrent()
                                       throws IllegalStateException

Get the current client context for this thread, throwing an exception if none is set.

Returns:

the current client context

Throws:

IllegalStateException - if the current client context is not set

require

public static EJBClientContext require(EJBClientContextIdentifier ejbClientContextIdentifier)
                                throws IllegalStateException

Returns a EJBClientContext which is identified by the passed ejbClientContextIdentifier. The EJBClientContext is identified with the help of the current selector. If the current selector is not of type IdentityEJBClientContextSelector or if that selector can't return a EJBClientContext for the passed ejbClientContextIdentifier then this method throws an IllegalStateException

Parameters:

ejbClientContextIdentifier - The EJB client context identifier

Returns:

Throws:

IllegalStateException - If this method couldn't find a EJBClientContext for the passed ejbClientContextIdentifier

registerEJBReceiver

public boolean registerEJBReceiver(EJBReceiver receiver)

Register an EJB receiver with this client context.

If the same EJBReceiver has already been associated in this client context or if a receiver with the same node name has already been associated in this client context, then this method does not register the passed receiver and returns false.

Parameters:

receiver - the receiver to register

Returns:

Returns true if the receiver was registered in this client context. Else returns false.

Throws:

IllegalArgumentException - If the passed receiver is null

unregisterEJBReceiver

public void unregisterEJBReceiver(EJBReceiver receiver)

Unregister (a previously registered) EJB receiver from this client context.

This EJB client context will not use this unregistered receiver for any subsequent invocations

Parameters:

receiver - The EJB receiver to unregister

Throws:

IllegalArgumentException - If the passed receiver is null

registerConnection

@Deprecated
public void registerConnection(org.jboss.remoting3.Connection connection)

Deprecated.

Register a Remoting connection with this client context.

Parameters:

connection - the connection to register

registerConnection

public void registerConnection(org.jboss.remoting3.Connection connection,
                               String remotingProtocol)

Register a Remoting connection with this client context.

Parameters:

connection - the connection to register

remotingProtocol - The remoting protocol. Can be 'remote', 'http-remoting' or 'https-remoting'

registerInterceptor

public EJBClientInterceptor.Registration registerInterceptor(int priority,
                                                             EJBClientInterceptor clientInterceptor)
                                                      throws IllegalArgumentException

Register a client interceptor with this client context.

If the passed clientInterceptor is already added to this context with the same priority then this method just returns the old EJBClientInterceptor.Registration. If however, the clientInterceptor is already registered in this context with a different priority then this method throws an IllegalArgumentException

Parameters:

priority - the absolute priority of this interceptor (lower runs earlier; higher runs later)

clientInterceptor - the interceptor to register

Returns:

a handle which may be used to later remove this registration

Throws:

IllegalArgumentException - if the given interceptor is null, the priority is less than 0, or the given interceptor is already registered with a different priority

getEJBClientConfiguration

public EJBClientConfiguration getEJBClientConfiguration()

Returns the EJBClientConfiguration applicable to this EJB client context. Returns null if this EJB client context isn't configured with a EJBClientConfiguration

Returns:

registerReconnectHandler

public void registerReconnectHandler(ReconnectHandler reconnectHandler)

Registers a ReconnectHandler in this EJBClientContext

Parameters:

reconnectHandler - The reconnect handler. Cannot be null

unregisterReconnectHandler

public void unregisterReconnectHandler(ReconnectHandler reconnectHandler)

Unregisters a ReconnectHandler from this EJBClientContext

Parameters:

reconnectHandler - The reconnect handler to unregister

registerEJBClientContextListener

public boolean registerEJBClientContextListener(EJBClientContextListener listener)

Registers a EJBClientContextListener for this EJBClientContext. The EJBClientContextListener will be notified of lifecycle events related to the EJBClientContext

Parameters:

listener - The EJB client context listener. Cannot be null.

Returns:

Returns true if the passed listener was registered with this EJB client context. False otherwise.

getOrCreateClusterContext

@Deprecated
public ClusterContext getOrCreateClusterContext(String clusterName)

Deprecated.

Returns a ClusterContext corresponding to the passed clusterName. If no such cluster context exists, a new one is created and returned. Subsequent invocations on this EJBClientContext for the same cluster name will return this same ClusterContext, unless the cluster has been removed from this client context.

Parameters:

clusterName - The name of the cluster

Returns:

getClusterContext

@Deprecated
public ClusterContext getClusterContext(String clusterName)

Deprecated.

Returns a ClusterContext corresponding to the passed clusterName. If no such cluster context exists, then this method returns null.

Parameters:

clusterName - The name of the cluster

Returns:

removeCluster

@Deprecated
public void removeCluster(String clusterName)

Deprecated.

Removes the cluster identified by the clusterName from this client context

Parameters:

clusterName - The name of the cluster

close

public void close()
           throws IOException

Closes the EJB client context and notifies any registered EJBClientContextListeners about the context being closed.

Specified by:

close in interface Closeable

Throws:

IOException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable