org.ow2.jonas.lib.ejb21
Class JEntitySwitch

java.lang.Object
  org.ow2.jonas.lib.ejb21.JEntitySwitch

Direct Known Subclasses:

JEntitySwitchCRC, JEntitySwitchCST, JEntitySwitchDB

public abstract class JEntitySwitch
extends Object

JEntitySwitch is used internally to synchronize accesses to the entity context and thus to the entity bean instance. All parts common to EJBObject and EJBLocalObject should be here. Different policies can be applied to manage context/instance pairs: - only 1 pair (container manages the transaction isolation) - 1 pair for each transaction (transaction isolation managed by DataBase) - 2 pairs (1 for transactional accesses, 1 for non transaction accesses)

Author:

Philippe Durieux, Philippe Coq

Field Summary

protected JEntityFactory	bf The Factory for this bean
protected ArrayList<Transaction>	blockedtx List of all transactions currently blocked by runningtx
protected static int	counter
protected int	countIH nb of non transacted requests running
protected int	countIT nb of transacted requests running
protected long	deadlockTimeout
protected long	estimestamp timestamp used to free objects when not used for a specified time.
protected static long	FEW_SECONDS
protected String	ident
protected long	inactivityTimeout time in millisec.
protected boolean	inDirtyList True if this instance may have been modified outside transactions.
protected boolean	isdetached True if this object is no longer referenced by its factory, i.e.
protected boolean	isremoved True if this object will be garbaged and must not be used any longer.
protected boolean	lazyregister true if we can differ the registration at first write.
protected JEntityLocal	local The EJBLocalObject, or null if bean has no local interface.
protected int	lockpolicy Lock policy used for this entity bean.
protected boolean	mustReload True if instance has been modified by a Transaction.
protected boolean	mustStore True if a TX need this instance currently used outside tx When the last release is done, we must store this instance.
protected TimerService	myTimerService The Timer Service
protected Object	pk The Primary Key for this bean instance.
protected long	readTimeout time in millisec.
protected boolean	reentrant reentrant=true if a bean instance can be accessed concurrently in the same transaction, or outside transaction.
protected JEntityRemote	remote The EJBObject, or null if bean has no remote interface.
protected Transaction	runningtx transaction on which a Context has been registered.
protected boolean	shared shared=true if the bean can be modify outside this container.
protected boolean	todiscard True when context/instance has been discarded, to avoids that passivate store its state on storage.
protected boolean	txUpdates True if a transaction is mandatory for all modifying methods.
protected int	waiters nb of threads waiting (synchronization)
protected Transaction	writingtx transaction that has modified an instance

Constructor Summary

JEntitySwitch()
empty constructor.

Method Summary

void	bindICtx(Transaction tx, JEntityContext bctx) bind a JEntityContext for a create method.
protected void	detachPk() Detach entity switch from PK list.
protected void	discardContext(Transaction tx, boolean forgetpk, boolean pool) Discard instance/Context and free all objects.
abstract void	endIH() Called only for CS policy, after passivateIH
void	forceDiscardICtx(Transaction tx)
JFactory	getBeanFactory()
Transaction	getBlockingTx(Transaction testedtx) Look if the specified transaction is blocked.
TimerService	getEntityTimerService() Obtains the TimerService associated for this Entity Bean (one / pk)
JEntityContext	getICtx(Transaction tx, boolean checkr) Get a context/instance associated with this transaction Called at each request on the bean (including remove)
JEntityContext	getICtx(Transaction tx, JEntityContext newctx) bind a JEntityContext for a remove method.
JEntityLocal	getLocal()
int	getPolicy()
Object	getPrimaryKey()
JEntityRemote	getRemote()
abstract int	getState()
void	init(JEntityFactory bf, Object pk) constructor.
protected abstract void	initpolicy(JEntityFactory bf)
boolean	lazyRegistering()
JEntityContext	mapICtx(Transaction tx, JEntityContext bctx, boolean forced, boolean holdit, boolean checkreentrance) Map a context and its instance.
void	notifyTimeout(Timer timer) Notify a timeout for this bean and this Pk
void	notifyWriting(Transaction tx, JEntityContext bctx) This transaction has just modified this instance.
abstract int	passivateIH(boolean store, boolean passivate)
protected boolean	registerCtx(Transaction tx, JEntityContext bctx) register a Context on the transaction, as a Synchronization.
void	releaseICtx(Transaction tx, boolean discard) Release a context/instance at end of request.
boolean	terminate(Transaction tx) Release completely this object, since another one will be used.
boolean	tryBindICtx(Transaction tx, JEntityContext bctx, boolean simple) Try to bind a JEntityContext if none already bound.
void	txCompleted(Transaction tx, boolean committed) This transaction is now over.

Methods inherited from class java.lang.Object

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

Field Detail

bf

protected JEntityFactory bf

The Factory for this bean

pk

protected Object pk

The Primary Key for this bean instance.

local

protected JEntityLocal local

The EJBLocalObject, or null if bean has no local interface.

remote

protected JEntityRemote remote

The EJBObject, or null if bean has no remote interface.

inactivityTimeout

protected long inactivityTimeout

time in millisec. to keep objects in memory when not used. After this time, objects are freed, if instances have been passivated before.

readTimeout

protected long readTimeout

time in millisec. to keep objects in memory without rereading them (for RO policy only)

shared

protected boolean shared

shared=true if the bean can be modify outside this container.

lockpolicy

protected int lockpolicy

Lock policy used for this entity bean. Possible values are :

0 = LOCK_CONTAINER_READ_UNCOMMITTED (1 instance)

1 = LOCK_CONTAINER_SERIALIZED (1 instance)

2 = LOCK_CONTAINER_READ_COMMITTED (2 instances)

3 = LOCK_DATABASE (n instances)

4 = LOCK_READ_ONLY (1 instance)

5 = LOCK_CONTAINER_READ_WRITE (1 instance)

6 = LOCK_CONTAINER_SERIALIZED_TRANSACTED (1 instance)

txUpdates

protected boolean txUpdates

True if a transaction is mandatory for all modifying methods. In this case, all methods outside tranction is considered as read-only. Only CS policy has txUpdates=false.

myTimerService

protected TimerService myTimerService

The Timer Service

countIH

protected int countIH

nb of non transacted requests running

countIT

protected int countIT

nb of transacted requests running

waiters

protected int waiters

nb of threads waiting (synchronization)

inDirtyList

protected boolean inDirtyList

True if this instance may have been modified outside transactions. Avoids to put it twice in dirty list. Only used for CS policy (non transacted modifying methods)

mustReload

protected boolean mustReload

True if instance has been modified by a Transaction. This means that reading outside transaction should reload it before use. Only used for DB and CRC policies (non transacted instance)

mustStore

protected boolean mustStore

True if a TX need this instance currently used outside tx When the last release is done, we must store this instance. Only used when txUpdate is false (i.e. CS policy)

todiscard

protected boolean todiscard

True when context/instance has been discarded, to avoids that passivate store its state on storage.

runningtx

protected Transaction runningtx

transaction on which a Context has been registered. Registration may be differed at first write in case of lazyregister=true. This ref is reset to null when the transaction is completed.

writingtx

protected Transaction writingtx

transaction that has modified an instance

deadlockTimeout

protected long deadlockTimeout

blockedtx

protected ArrayList<Transaction> blockedtx

List of all transactions currently blocked by runningtx

isremoved

protected boolean isremoved

True if this object will be garbaged and must not be used any longer.

isdetached

protected boolean isdetached

True if this object is no longer referenced by its factory, i.e. it is no longer in the PK list.

counter

protected static int counter

ident

protected String ident

estimestamp

protected long estimestamp

timestamp used to free objects when not used for a specified time.

FEW_SECONDS

protected static final long FEW_SECONDS

See Also:

Constant Field Values

lazyregister

protected boolean lazyregister

true if we can differ the registration at first write. Cannot be true if shared or prefetch.

reentrant

protected boolean reentrant

reentrant=true if a bean instance can be accessed concurrently in the same transaction, or outside transaction.

Constructor Detail

JEntitySwitch

public JEntitySwitch()

empty constructor. Object is initialized via init() because it is implemented differently according to jorm mappers.

Method Detail

initpolicy

protected abstract void initpolicy(JEntityFactory bf)

passivateIH

public abstract int passivateIH(boolean store,
                                boolean passivate)

Parameters:

store - True if want to store instance first (CS policy)

passivate - True if we want to passivate instance

Returns:

result of operation: ALL_DONE, STORED, or NOT_DONE

endIH

public abstract void endIH()

Called only for CS policy, after passivateIH

init

public void init(JEntityFactory bf,
                 Object pk)

constructor. A new object is build when a new PK is known in the container, either when a new bean is created, or when a find occurs. For create(), PK is not known yet when this object is build.

Parameters:

bf - The Entity Factory

pk - The Primary Key

lazyRegistering

public boolean lazyRegistering()

Returns:

true if lazy registering enabled.

getLocal

public JEntityLocal getLocal()

Returns:

the underlaying EJBLocalObject

getRemote

public JEntityRemote getRemote()

Returns:

the underlaying EJBObject

getEntityTimerService

public TimerService getEntityTimerService()

Obtains the TimerService associated for this Entity Bean (one / pk)

Returns:

a JTimerService instance.

notifyWriting

public void notifyWriting(Transaction tx,
                          JEntityContext bctx)

This transaction has just modified this instance. (CMP2 only) Called only if lazyRegister is set and not RO policy.

Parameters:

tx - transaction

notifyTimeout

public void notifyTimeout(Timer timer)

Notify a timeout for this bean and this Pk

Parameters:

timer - timer whose expiration caused this notification.

getPrimaryKey

public Object getPrimaryKey()

Returns:

the Primary Key Object for this instance.

bindICtx

public void bindICtx(Transaction tx,
                     JEntityContext bctx)

bind a JEntityContext for a create method.

Parameters:

tx - - the Transaction object

bctx - - the JEntityContext to bind

tryBindICtx

public boolean tryBindICtx(Transaction tx,
                           JEntityContext bctx,
                           boolean simple)
                    throws ObjectNotFoundException

Try to bind a JEntityContext if none already bound. Called by finder methods. This is actually kind of optimization. Can be bypassed if problems: just return false.

Parameters:

tx - - the Transaction object

bctx - The Entity Context

simple - True if simple finder method

Returns:

true if context has been bound to this EntitySwitch.

Throws:

ObjectNotFoundException

getICtx

public JEntityContext getICtx(Transaction tx,
                              JEntityContext newctx)

bind a JEntityContext for a remove method. called in case of remove(pk) or remove(handle)

Parameters:

tx - - the Transaction object

newctx - - the JEntityContext to bind

Returns:

the BeanContext

getICtx

public JEntityContext getICtx(Transaction tx,
                              boolean checkr)

Get a context/instance associated with this transaction Called at each request on the bean (including remove)

Parameters:

tx - - the Transaction object

checkr - - true if we must check non-reentrance.

Returns:

the BeanContext

terminate

public boolean terminate(Transaction tx)

Release completely this object, since another one will be used. this occurs in case of create, when another EntitySwitch exist already.

Parameters:

tx - - the Transaction object

mapICtx

public JEntityContext mapICtx(Transaction tx,
                              JEntityContext bctx,
                              boolean forced,
                              boolean holdit,
                              boolean checkreentrance)

Map a context and its instance.

Parameters:

tx - - the Transaction object

bctx - - the JEntityContext to bind if not null

forced - - force to take this context. (case of create)

holdit - - increment count to hold it, a release will be called later.

checkreentrance - - true if we must check non-reentrance.

Returns:

JEntityContext actually mapped

getBlockingTx

public Transaction getBlockingTx(Transaction testedtx)

Look if the specified transaction is blocked.

Parameters:

testedtx - Transaction we look for

Returns:

The blocking transaction

releaseICtx

public void releaseICtx(Transaction tx,
                        boolean discard)

Release a context/instance at end of request.

Parameters:

tx - - transaction associated to this context

discard - - instance must be discarded

forceDiscardICtx

public void forceDiscardICtx(Transaction tx)

txCompleted

public void txCompleted(Transaction tx,
                        boolean committed)

This transaction is now over. We can dispose of the instance for another transaction or discard it. A special implementation exists for RO policy

Parameters:

tx - the transaction object

committed - true if transaction was committed.

registerCtx

protected boolean registerCtx(Transaction tx,
                              JEntityContext bctx)

register a Context on the transaction, as a Synchronization. this will be used later to store instance state when needed : before a finder, or at beforeCompletion, and to release instance at commit.

Parameters:

tx - Transaction object

bctx - The Context to be registered

Returns:

boolean true if registered

detachPk

protected void detachPk()

Detach entity switch from PK list. This should trigger cleaning memory from all these objects by garbage collector.

discardContext

protected void discardContext(Transaction tx,
                              boolean forgetpk,
                              boolean pool)

Discard instance/Context and free all objects.

Parameters:

tx - - the Transaction object

forgetpk - - true if remove pk from the list

pool - - true if instance can be pooled.

getPolicy

public int getPolicy()

Returns:

lock policy for this bean

getState

public abstract int getState()

Returns:

State of this instance. State values are 0=in-tx, 1=out-tx, 2=idle, 3=passive, 4=removed. we don't synchronize this method to avoid jadmin blocks

getBeanFactory

public JFactory getBeanFactory()

Returns:

the JFactory