org.jboss.ejb.client.annotation

Enum ClientTransactionPolicy

java.lang.Object

java.lang.Enum<ClientTransactionPolicy>

org.jboss.ejb.client.annotation.ClientTransactionPolicy

All Implemented Interfaces:

Serializable, Comparable<ClientTransactionPolicy>

public enum ClientTransactionPolicy
extends Enum<ClientTransactionPolicy>

The transaction policy for the client side of an EJB interface or method.

Author:

David M. Lloyd

Enum Constant Summary

Enum Constants

Enum Constant and Description
MANDATORY Fail with exception when there is no client-side transaction context; propagate the client-side transaction context when it is present.
NEVER Invoke without propagating any transaction context; if a client-side transaction context is present, an exception is thrown.
NOT_SUPPORTED Invoke without propagating any transaction context whether or not a client-side transaction context is present.
SUPPORTS Invoke without a transaction if there is no client-side transaction context; propagate the client-side transaction context if it is present.

Method Summary

Modifier and Type	Method and Description
boolean	failIfTransactionAbsent() Determine whether this transaction policy causes a failure when a client-side transaction context is absent.
boolean	failIfTransactionPresent() Determine whether this transaction policy causes a failure when a client-side transaction context is present.
boolean	in(ClientTransactionPolicy... values) Determine whether this instance is equal to one of the given instances.
boolean	in(ClientTransactionPolicy v1) Determine whether this instance is equal to one of the given instances.
boolean	in(ClientTransactionPolicy v1, ClientTransactionPolicy v2) Determine whether this instance is equal to one of the given instances.
boolean	in(ClientTransactionPolicy v1, ClientTransactionPolicy v2, ClientTransactionPolicy v3) Determine whether this instance is equal to one of the given instances.
static boolean	isFull(EnumSet<ClientTransactionPolicy> set) Determine whether the given set is fully populated (or "full"), meaning it contains all possible values.
boolean	propagate() Determine whether this transaction policy causes the client-side transaction context (if any) to be propagated to invocations.
static ClientTransactionPolicy	valueOf(String name) Returns the enum constant of this type with the specified name.
static ClientTransactionPolicy[]	values() Returns an array containing the constants of this enum type, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

MANDATORY

public static final ClientTransactionPolicy MANDATORY

Fail with exception when there is no client-side transaction context; propagate the client-side transaction context when it is present. The target is never invoked without a client-side transaction context.

This mode is compatible with the following server-side transaction attribute types:

• TransactionAttributeType.MANDATORY
• TransactionAttributeType.REQUIRED
• TransactionAttributeType.SUPPORTS

This mode is recommended when the server side method uses TransactionAttributeType.MANDATORY.

This mode may be used with TransactionAttributeType.REQUIRES_NEW and TransactionAttributeType.NOT_SUPPORTED, but such usage may not make sense in most situations because the transaction that is required to be propagated by the client will always be suspended on the server; in this case, a client-side policy of TransactionAttributeType.NOT_SUPPORTED is recommended to avoid the useless propagation of the client-side transaction context.

Usage of this mode with the following server-side transaction attribute types will always result in an exception, and is therefore not recommended:

• TransactionAttributeType.NEVER

SUPPORTS

public static final ClientTransactionPolicy SUPPORTS

Invoke without a transaction if there is no client-side transaction context; propagate the client-side transaction context if it is present. The target may be invoked with or without a client-side transaction context.

This is the overall default policy.

This mode is compatible with the following server-side transaction attribute types:

• TransactionAttributeType.REQUIRED
• TransactionAttributeType.SUPPORTS
• TransactionAttributeType.NOT_SUPPORTED

This mode can also be used with TransactionAttributeType.NEVER and TransactionAttributeType.MANDATORY, however the success of the invocation of such methods will depend on the local transaction state.

Unlike TransactionAttributeType.SUPPORTS, this client-side transaction policy is generally safe to use in all cases, as it still allows the server to decide to create a new transaction according to local policy.

This mode may be used with TransactionAttributeType.REQUIRES_NEW, but such usage may not make sense in most situations because the transaction that is propagated by the client (if any) will always be suspended on the server; in this case, a client-side policy of NOT_SUPPORTED is recommended to avoid the useless propagation of the client-side transaction context.

NOT_SUPPORTED

public static final ClientTransactionPolicy NOT_SUPPORTED

Invoke without propagating any transaction context whether or not a client-side transaction context is present. The target is always invoked without a client-side transaction context.

This mode is compatible with the following server-side transaction attribute types:

• TransactionAttributeType.REQUIRED
• TransactionAttributeType.REQUIRES_NEW
• TransactionAttributeType.SUPPORTS
• TransactionAttributeType.NOT_SUPPORTED

This mode can also be used with TransactionAttributeType.NEVER, however, in this case the server will never see the client-side transaction, causing the invocation to effectively use the server-side mode TransactionAttributeType.NOT_SUPPORTED in this case, which might result in unexpected behavior.

Usage of this mode with the following server-side transaction attribute types will always result in an exception, and is therefore not recommended:

• TransactionAttributeType.MANDATORY

NEVER

public static final ClientTransactionPolicy NEVER

Invoke without propagating any transaction context; if a client-side transaction context is present, an exception is thrown.

This mode is compatible with the following server-side transaction attribute types:

• TransactionAttributeType.REQUIRED
• TransactionAttributeType.REQUIRES_NEW
• TransactionAttributeType.SUPPORTS
• TransactionAttributeType.NOT_SUPPORTED

This mode can also be used with TransactionAttributeType.NEVER, however, in this case the server will never see the client-side transaction, causing the invocation to effectively use the server-side mode TransactionAttributeType.NOT_SUPPORTED in this case, which might result in unexpected behavior.

Usage of this mode with the following server-side transaction attribute types will always result in an exception, and is therefore not recommended:

• TransactionAttributeType.MANDATORY

Method Detail

values

public static ClientTransactionPolicy[] values()

Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

for (ClientTransactionPolicy c : ClientTransactionPolicy.values())
    System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they are declared

valueOf

public static ClientTransactionPolicy valueOf(String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum type has no constant with the specified name

NullPointerException - if the argument is null

failIfTransactionPresent

public boolean failIfTransactionPresent()

Determine whether this transaction policy causes a failure when a client-side transaction context is present.

Returns:

true if the policy would fail when a transaction is present, false otherwise

failIfTransactionAbsent

public boolean failIfTransactionAbsent()

Determine whether this transaction policy causes a failure when a client-side transaction context is absent.

Returns:

true if the policy would fail when a transaction is absent, false otherwise

propagate

public boolean propagate()

Determine whether this transaction policy causes the client-side transaction context (if any) to be propagated to invocations.

Returns:

true if the transaction is propagated by this policy, false otherwise

isFull

public static boolean isFull(EnumSet<ClientTransactionPolicy> set)

Determine whether the given set is fully populated (or "full"), meaning it contains all possible values.

Parameters:

set - the set

Returns:

true if the set is full, false otherwise

in

public boolean in(ClientTransactionPolicy v1)

Determine whether this instance is equal to one of the given instances.

Parameters:

v1 - the first instance

Returns:

true if one of the instances matches this one, false otherwise

in

public boolean in(ClientTransactionPolicy v1,
                  ClientTransactionPolicy v2)

Determine whether this instance is equal to one of the given instances.

Parameters:

v1 - the first instance

v2 - the second instance

Returns:

true if one of the instances matches this one, false otherwise

in

public boolean in(ClientTransactionPolicy v1,
                  ClientTransactionPolicy v2,
                  ClientTransactionPolicy v3)

Determine whether this instance is equal to one of the given instances.

Parameters:

v1 - the first instance

v2 - the second instance

v3 - the third instance

Returns:

true if one of the instances matches this one, false otherwise

in

public boolean in(ClientTransactionPolicy... values)

Determine whether this instance is equal to one of the given instances.

Parameters:

values - the possible values

Returns:

true if one of the instances matches this one, false otherwise