org.jboss.cache
Class InvocationContext

java.lang.Object
  org.jboss.cache.InvocationContext

Direct Known Subclasses:

LegacyInvocationContext, MVCCInvocationContext

public abstract class InvocationContext
extends Object

A context that holds information regarding the scope of a single invocation. May delegate some calls to a TransactionContext if one is in scope.

Note that prior to 3.0.0, InvocationContext was a concrete class and not an abstract one.

Author:

Manik Surtani (manik AT jboss DOT org)

See Also:

TransactionContext

Field Summary

protected LinkedHashSet	invocationLocks LinkedHashSet of locks acquired by the invocation.
protected TransactionContext	transactionContext

Constructor Summary

InvocationContext()

Method Summary

void	addAllLocks(List locks) Adds a List of locks to the currently maintained collection of locks acquired.
void	addFqnLoaded(Fqn fqn) Adds an Fqn to the set of Fqns loaded by the cache loader interceptor.
void	addLock(Object lock) Adds a lock to the currently maintained collection of locks acquired.
void	clearLocks() Clears all locks from the currently maintained collection of locks acquired.
abstract void	clearLookedUpNodes() Clears the registry of looked up nodes.
abstract InvocationContext	copy() This is a "copy-factory-method" that should be used whenever a clone of this class is needed.
protected void	doCopy(InvocationContext copy)
boolean	equals(Object o)
VisitableCommand	getCommand() Deprecated.
Set<Fqn>	getFqnsLoaded()
GlobalTransaction	getGlobalTransaction() Retrieves the global transaction associated with this invocation
long	getLockAcquisitionTimeout(long timeout) If the lock acquisition timeout is overridden for current call using an option, then return that one.
List	getLocks() Returns an immutable, defensive copy of the List of locks currently maintained for the current scope.
abstract Map<Fqn,NodeSPI>	getLookedUpNodes() Retrieves a map of nodes looked up within the current invocation's scope.
MethodCall	getMethodCall() Deprecated.
Option	getOptionOverrides() Retrieves the option overrides associated with this invocation
Transaction	getTransaction() Retrieves the transaction associated with this invocation
TransactionContext	getTransactionContext()
int	hashCode()
boolean	hasLock(Object lock) Note that if a transaction is in scope, implementations should test this lock from on TransactionContext.
boolean	isLocalRollbackOnly()
boolean	isLockingSuppressed()
boolean	isOptionsUninitialised()
boolean	isOriginLocal() Tests if this invocation originated locally or from a remote cache.
boolean	isValidTransaction()
abstract NodeSPI	lookUpNode(Fqn fqn) Retrieves a node from the registry of looked up nodes in the current scope.
abstract void	putLookedUpNode(Fqn f, NodeSPI n) Puts an entry in the registry of looked up nodes in the current scope.
abstract void	putLookedUpNodes(Map<Fqn,NodeSPI> lookedUpNodes) Adds a map of looked up nodes to the current map of looked up nodes
void	removeLock(Object lock) Removes a lock from the currently maintained collection of locks acquired.
void	reset() Resets the context, freeing up any references.
void	setCommand(VisitableCommand cacheCommand) Deprecated.
void	setFqnsLoaded(Set<Fqn> fqnsLoaded)
void	setGlobalTransaction(GlobalTransaction globalTransaction) Sets the global transaction associated with this invocation
void	setLocalRollbackOnly(boolean localRollbackOnly) Marks teh context as only rolling back.
void	setMethodCall(MethodCall methodCall) Deprecated. not used anymore. Interceptors will get a ReplicableCommand instance passed in along with an InvocationContext.
void	setOptionOverrides(Option optionOverrides) Sets the option overrides to be associated with this invocation
void	setOriginLocal(boolean originLocal) If set to true, the invocation is assumed to have originated locally.
void	setState(InvocationContext template) Sets the state of the InvocationContext based on the template context passed in
void	setTransaction(Transaction transaction) Sets a transaction object on the invocation context.
void	setTransactionContext(TransactionContext transactionContext) Sets the transaction context to be associated with the current thread.
void	throwIfNeeded(Throwable e) Throws the given throwable provided no options suppress or prevent this from happening.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

transactionContext

protected TransactionContext transactionContext

invocationLocks

protected LinkedHashSet invocationLocks

LinkedHashSet of locks acquired by the invocation. We use a LinkedHashSet because we need efficient Set semantics but also need guaranteed ordering for use by lock release code (see JBCCACHE-874).

This needs to be unchecked since we support both MVCC (Fqns held here) or legacy Opt/Pess locking (NodeLocks held here). once we drop support for opt/pess locks we can genericise this to contain Fqns. - Manik Surtani, June 2008

Constructor Detail

InvocationContext

public InvocationContext()

Method Detail

lookUpNode

public abstract NodeSPI lookUpNode(Fqn fqn)

Retrieves a node from the registry of looked up nodes in the current scope.

Parameters:

fqn - fqn to look up

Returns:

a node, or null if it cannot be found.

Since:

3.0.

putLookedUpNode

public abstract void putLookedUpNode(Fqn f,
                                     NodeSPI n)

Puts an entry in the registry of looked up nodes in the current scope.

Parameters:

f - fqn to add

n - node to add

Since:

3.0.

putLookedUpNodes

public abstract void putLookedUpNodes(Map<Fqn,NodeSPI> lookedUpNodes)

Adds a map of looked up nodes to the current map of looked up nodes

Parameters:

lookedUpNodes - looked up nodes to add

clearLookedUpNodes

public abstract void clearLookedUpNodes()

Clears the registry of looked up nodes.

Since:

3.0.

getLookedUpNodes

public abstract Map<Fqn,NodeSPI> getLookedUpNodes()

Retrieves a map of nodes looked up within the current invocation's scope.

Returns:

a map of looked up nodes.

Since:

3.0

setLocalRollbackOnly

public void setLocalRollbackOnly(boolean localRollbackOnly)

Marks teh context as only rolling back.

Parameters:

localRollbackOnly - if true, the context is only rolling back.

getTransaction

public Transaction getTransaction()

Retrieves the transaction associated with this invocation

Returns:

The transaction associated with this invocation

setTransaction

public void setTransaction(Transaction transaction)

Sets a transaction object on the invocation context.

Parameters:

transaction - transaction to set

getTransactionContext

public TransactionContext getTransactionContext()

Returns:

the transaction entry associated with the current transaction, or null if the current thread is not associated with a transaction.

Since:

2.2.0

setTransactionContext

public void setTransactionContext(TransactionContext transactionContext)

Sets the transaction context to be associated with the current thread.

Parameters:

transactionContext - transaction context to set

Since:

2.2.0

getGlobalTransaction

public GlobalTransaction getGlobalTransaction()

Retrieves the global transaction associated with this invocation

Returns:

the global transaction associated with this invocation

setGlobalTransaction

public void setGlobalTransaction(GlobalTransaction globalTransaction)

Sets the global transaction associated with this invocation

Parameters:

globalTransaction - global transaction to set

getOptionOverrides

public Option getOptionOverrides()

Retrieves the option overrides associated with this invocation

Returns:

the option overrides associated with this invocation

isOptionsUninitialised

public boolean isOptionsUninitialised()

Returns:

true of no options have been set on this context, false otherwise.

setOptionOverrides

public void setOptionOverrides(Option optionOverrides)

Sets the option overrides to be associated with this invocation

Parameters:

optionOverrides - options to set

isOriginLocal

public boolean isOriginLocal()

Tests if this invocation originated locally or from a remote cache.

Returns:

true if the invocation originated locally.

getLocks

public List getLocks()

Returns an immutable, defensive copy of the List of locks currently maintained for the current scope.

Note that if a transaction is in scope, implementations should retrieve these locks from the TransactionContext. Retrieving locks from this method should always ensure they are retrieved from the appropriate scope.

Note that currently (as of 3.0.0) this list is unchecked. This is to allow support for both MVCC (which uses Fqns as locks) as well as legacy Optimistic and Pessimistic Locking schemes (which use NodeLock as locks). Once support for legacy node locking schemes are dropped, this method will be more strongly typed to return List.

Returns:

locks held in current scope.

addAllLocks

public void addAllLocks(List locks)

Adds a List of locks to the currently maintained collection of locks acquired.

Note that if a transaction is in scope, implementations should record locks on the TransactionContext. Adding locks using this method should always ensure they are applied to the appropriate scope.

Note that currently (as of 3.0.0) this list is unchecked. This is to allow support for both MVCC (which uses Fqns as locks) as well as legacy Optimistic and Pessimistic Locking schemes (which use NodeLock as locks). Once support for legacy node locking schemes are dropped, this method will be more strongly typed to accept List.

Parameters:

locks - locks to add

addLock

public void addLock(Object lock)

Adds a lock to the currently maintained collection of locks acquired.

Note that if a transaction is in scope, implementations should record this lock on the TransactionContext. Using this method should always ensure that the appropriate scope is used.

Note that currently (as of 3.0.0) this lock is weakly typed. This is to allow support for both MVCC (which uses Fqns as locks) as well as legacy Optimistic and Pessimistic Locking schemes (which use NodeLock as locks). Once support for legacy node locking schemes are dropped, this method will be more strongly typed to accept Fqn.

Parameters:

lock - lock to add

removeLock

public void removeLock(Object lock)

Removes a lock from the currently maintained collection of locks acquired.

Note that if a transaction is in scope, implementations should remove this lock from the TransactionContext. Using this method should always ensure that the lock is removed from the appropriate scope.

Note that currently (as of 3.0.0) this lock is weakly typed. This is to allow support for both MVCC (which uses Fqns as locks) as well as legacy Optimistic and Pessimistic Locking schemes (which use NodeLock as locks). Once support for legacy node locking schemes are dropped, this method will be more strongly typed to accept Fqn.

Parameters:

lock - lock to remove

clearLocks

public void clearLocks()

Clears all locks from the currently maintained collection of locks acquired.

Note that if a transaction is in scope, implementations should clear locks from the TransactionContext. Using this method should always ensure locks are cleared in the appropriate scope.

Note that currently (as of 3.0.0) this lock is weakly typed. This is to allow support for both MVCC (which uses Fqns as locks) as well as legacy Optimistic and Pessimistic Locking schemes (which use NodeLock as locks). Once support for legacy node locking schemes are dropped, this method will be more strongly typed to accept Fqn.

hasLock

public boolean hasLock(Object lock)

Note that if a transaction is in scope, implementations should test this lock from on TransactionContext. Using this method should always ensure locks checked in the appropriate scope.

Parameters:

lock - lock to test

Returns:

true if the lock being tested is already held in the current scope, false otherwise.

isLockingSuppressed

public boolean isLockingSuppressed()

Returns:

true if options exist to suppress locking - false otherwise. Note that this is only used by the PessimisticLockInterceptor.

setOriginLocal

public void setOriginLocal(boolean originLocal)

If set to true, the invocation is assumed to have originated locally. If set to false, assumed to have originated from a remote cache.

Parameters:

originLocal - flag to set

isLocalRollbackOnly

public boolean isLocalRollbackOnly()

Returns:

true if the current transaction is set to rollback only.

reset

public void reset()

Resets the context, freeing up any references.

copy

public abstract InvocationContext copy()

This is a "copy-factory-method" that should be used whenever a clone of this class is needed. The resulting instance is equal() to, but not ==, to the InvocationContext invoked on. Note that this is a shallow copy with the exception of the Option object, which is deep, as well as any collections held on the context such as locks. Note that the reference to a TransactionContext, if any, is maintained.

Returns:

a new InvocationContext

setState

public void setState(InvocationContext template)

Sets the state of the InvocationContext based on the template context passed in

Parameters:

template - template to copy from

getMethodCall

@Deprecated
public MethodCall getMethodCall()

Deprecated.

Returns:

the method call associated with this invocation

setMethodCall

@Deprecated
public void setMethodCall(MethodCall methodCall)

Deprecated. not used anymore. Interceptors will get a ReplicableCommand instance passed in along with an InvocationContext.

Sets the method call associated with this invocation.

Parameters:

methodCall - methodcall to set

getLockAcquisitionTimeout

public long getLockAcquisitionTimeout(long timeout)

If the lock acquisition timeout is overridden for current call using an option, then return that one. If not overridden, return default value.

Parameters:

timeout - timeout to fall back to

Returns:

timeout to use

setCommand

@Deprecated
public void setCommand(VisitableCommand cacheCommand)

Deprecated.

This is only used for backward compatibility with old interceptors implementation and should NOT be use by any new custom interceptors. The commands is now passed in as the second param in each implementing handlers (handler = method in ChainedInterceptor class)

Parameters:

cacheCommand - command to set

getCommand

@Deprecated
public VisitableCommand getCommand()

Deprecated.

Returns:

command that is in scope

See Also:

setCommand(org.jboss.cache.commands.VisitableCommand)

isValidTransaction

public boolean isValidTransaction()

Returns:

true if there is current transaction associated with the invocation, and this transaction is in a valid state.

throwIfNeeded

public void throwIfNeeded(Throwable e)
                   throws Throwable

Throws the given throwable provided no options suppress or prevent this from happening.

Parameters:

e - throwable to throw

Throws:

Throwable - if allowed to throw one.

doCopy

protected void doCopy(InvocationContext copy)

addFqnLoaded

public void addFqnLoaded(Fqn fqn)

Adds an Fqn to the set of Fqns loaded by the cache loader interceptor. Instantiates the set lazily if needed.

Parameters:

fqn - fqn to add

getFqnsLoaded

public Set<Fqn> getFqnsLoaded()

Returns:

Set of Fqns loaded by the cache loader interceptor. Only recorded if needed, such as by the ActivationInterceptor

setFqnsLoaded

public void setFqnsLoaded(Set<Fqn> fqnsLoaded)

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object