org.jboss.ejb.client

Class EJBReceiver

java.lang.Object

org.jboss.ejb.client.Attachable

org.jboss.ejb.client.EJBReceiver

Direct Known Subclasses:

RemotingConnectionEJBReceiver

public abstract class EJBReceiver
extends Attachable

A receiver for EJB invocations. Receivers can be associated with one or more client contexts. This interface is implemented by providers for EJB invocation services.

Author:

David M. Lloyd

Constructor Summary

Constructors

Constructor and Description
EJBReceiver(String nodeName)

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract void	associate(EJBReceiverContext context) Handle the association of this EJB receiver with the EJB client context.
protected void	beforeCompletion(EJBReceiverContext context, TransactionID transactionID) The before-completion hook.
protected boolean	cancelInvocation(EJBClientInvocationContext clientInvocationContext, EJBReceiverInvocationContext receiverContext) Attempt to cancel an invocation.
protected boolean	deregisterModule(String appName, String moduleName, String distinctName) Deregister a module from this receiver.
protected abstract void	disassociate(EJBReceiverContext context) Remove an association of this EJB receiver with the EJB client context.
protected abstract boolean	exists(String appName, String moduleName, String distinctName, String beanName) Verify the existence of a remote EJB.
protected String	getNodeName() Returns the node name corresponding to this receiver.
protected abstract <T> StatefulEJBLocator<T>	openSession(EJBReceiverContext context, Class<T> viewType, String appName, String moduleName, String distinctName, String beanName) Creates a session for a stateful session bean represented by the passed app name, module name, distinct name and bean name combination.
protected abstract void	processInvocation(EJBClientInvocationContext clientInvocationContext, EJBReceiverInvocationContext receiverContext) Process the invocation.
protected boolean	registerModule(String appName, String moduleName, String distinctName) Register a new module to this receiver.
protected void	sendCommit(EJBReceiverContext context, TransactionID transactionID, boolean onePhase) Send a transaction-commit message for the given transaction ID.
protected void	sendForget(EJBReceiverContext context, TransactionID transactionID) Send a transaction-forget message for the given transaction ID.
protected int	sendPrepare(EJBReceiverContext context, TransactionID transactionID) Send a transaction-prepare message for the given transaction ID.
protected Xid[]	sendRecover(EJBReceiverContext receiverContext, String txParentNodeName, int recoveryFlags) Send a transaction recover message with the recoveryFlags.
protected void	sendRollback(EJBReceiverContext context, TransactionID transactionID) Send a transaction-rollback message for the given transaction ID.

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, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EJBReceiver

public EJBReceiver(String nodeName)

Method Detail

registerModule

protected final boolean registerModule(String appName,
                     String moduleName,
                     String distinctName)

Register a new module to this receiver.

Parameters:

appName - the app name

moduleName - the module name

distinctName - the distinct name

Returns:

true if this is a previously-unknown registration

deregisterModule

protected final boolean deregisterModule(String appName,
                       String moduleName,
                       String distinctName)

Deregister a module from this receiver.

Parameters:

appName - the app name

moduleName - the module name

distinctName - the distinct name

Returns:

true if the registration was present

associate

protected abstract void associate(EJBReceiverContext context)

Handle the association of this EJB receiver with the EJB client context. After this method is called, the EJB receiver should notify the EJB receiver context of the available module identifiers that it can service, and it should maintain that availability list for the life of the receiver association.

Parameters:

context - the receiver context

disassociate

protected abstract void disassociate(EJBReceiverContext context)

Remove an association of this EJB receiver with the EJB client context.

Parameters:

context - the receiver context

processInvocation

protected abstract void processInvocation(EJBClientInvocationContext clientInvocationContext,
                     EJBReceiverInvocationContext receiverContext)
                                   throws Exception

Process the invocation. Implementations of this method should always execute the operation asynchronously. The operation result should be passed in to the receiver invocation context. To ensure ideal GC behavior, the receiver should discard any reference to the invocation context(s) once the result producer has been set.

Parameters:

clientInvocationContext - the interceptor clientInvocationContext

receiverContext - The EJB receiver invocation context

Throws:

Exception - if the operation throws an exception

cancelInvocation

protected boolean cancelInvocation(EJBClientInvocationContext clientInvocationContext,
                       EJBReceiverInvocationContext receiverContext)

Attempt to cancel an invocation. Implementations should make a reasonable effort to determine whether the operation was actually cancelled; however it is permissible to fall back to returning false if it cannot be discovered.

Parameters:

clientInvocationContext - the original clientInvocationContext

receiverContext - the EJB receiver invocation context

Returns:

true if the operation was definitely cancelled immediately, false otherwise

openSession

protected abstract <T> StatefulEJBLocator<T> openSession(EJBReceiverContext context,
                                    Class<T> viewType,
                                    String appName,
                                    String moduleName,
                                    String distinctName,
                                    String beanName)
                                              throws IllegalArgumentException

Creates a session for a stateful session bean represented by the passed app name, module name, distinct name and bean name combination. Returns a StatefulEJBLocator representing the newly created session.

Type Parameters:

T -

Parameters:

context - The receiver context

viewType - View class

appName - The application name

moduleName - The module name

distinctName - The distinct name

beanName - The name of the bean

Returns:

Throws:

IllegalArgumentException - If the session creation request is made for a bean which is not a stateful session bean.

exists

protected abstract boolean exists(String appName,
             String moduleName,
             String distinctName,
             String beanName)

Verify the existence of a remote EJB. Returns true if a bean identified by the passed appname, module name, distinct name and bean name combination exists. Else returns false.

Parameters:

appName - The application name

moduleName - The module name

distinctName - The distinct name

beanName - The bean name

sendPrepare

protected int sendPrepare(EJBReceiverContext context,
              TransactionID transactionID)
                   throws XAException

Send a transaction-prepare message for the given transaction ID.

Parameters:

context - the receiver context

transactionID - the transaction ID

Returns:

a value indicating the resource manager's vote on the outcome of the transaction; the possible values are: XA_RDONLY or XA_OK

Throws:

XAException - to roll back the transaction

sendCommit

protected void sendCommit(EJBReceiverContext context,
              TransactionID transactionID,
              boolean onePhase)
                   throws XAException

Send a transaction-commit message for the given transaction ID.

Parameters:

context - the receiver context

transactionID - the transaction ID

onePhase - true to perform a one-phase commit

Throws:

XAException - if the transaction commit failed

sendRollback

protected void sendRollback(EJBReceiverContext context,
                TransactionID transactionID)
                     throws XAException

Send a transaction-rollback message for the given transaction ID.

Parameters:

context - the receiver context

transactionID - the transaction ID

Throws:

XAException - if the transaction rollback failed

sendForget

protected void sendForget(EJBReceiverContext context,
              TransactionID transactionID)
                   throws XAException

Send a transaction-forget message for the given transaction ID.

Parameters:

context - the receiver context

transactionID - the transaction ID

Throws:

XAException - if the forget message failed

sendRecover

protected Xid[] sendRecover(EJBReceiverContext receiverContext,
                String txParentNodeName,
                int recoveryFlags)
                     throws XAException

Send a transaction recover message with the recoveryFlags. The receiver is expected to returns zero or more Xids of the transaction branches that are currently in a prepared or heuristically completed state. See XAResource.recover(int) for more details.

Parameters:

receiverContext - The EJB receiver context

recoveryFlags - @see XAResource.recover(int)

Returns:

Returns zero or more Xids of the transaction branches that are currently in a prepared or heuristically completed state.

Throws:

XAException - If an error occurs during the operation

getNodeName

protected final String getNodeName()

Returns the node name corresponding to this receiver. This method will not return a null value.

Returns:

beforeCompletion

protected void beforeCompletion(EJBReceiverContext context,
                    TransactionID transactionID)

The before-completion hook. Cause all connected subordinate transaction managers to invoke their beforeCompletion methods. This method should not return until all remote beforeCompletions have been called.

Parameters:

context - the receiver context

transactionID - the transaction ID