org.exolab.castor.persist
Class ClassMolder

java.lang.Object
  org.exolab.castor.persist.ClassMolder

public class ClassMolder

extends java.lang.Object

ClassMolder is a 'binder' for one type of data object and its corresponding Persistence. For example, when ClassMolder is asked to load an object, it acquires the field values from Persistence and binds them into the target object.

It resolves relations via TransactionContext and subsequently binds these related objects into the target object, too.

Apart from loading, ClassMolder is also responsible for storing, removing, creating an object to and from a persistence storage, as well as reverting an object to its previous state.

Each instance of ClassMolder deals with exactly one persistable type, interacts with one instance of Persistent and belongs to one LockEngine.

Author:

Thomas Yip, Bruce Snyder, Werner Guttmann

Field Summary

boolean

_isKeyGenUsed Is a key kenerator used for the base class?

Constructor Summary

(package private)

ClassMolder(DatingService ds, org.exolab.castor.mapping.loader.AbstractMappingLoader loader, LockEngine lock, org.exolab.castor.mapping.ClassDescriptor clsDesc, Persistence persist) Creates an instance of this class.

Method Summary

(package private) void	addDependent(ClassMolder dep) Mutator method to add a dependent ClassMolder.
(package private) void	addExtendent(ClassMolder ext) Mutator method to add a extent ClassMolder.
Identity	create(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Create an object of the base class with specified identity into the persistence storage.
void	delete(TransactionContext tx, OID oid) Delete an object of the base type from the persistence storage.
void	expireCache(TransactionContext tx, ObjectLock locker) Inspect the fields stored in the object passed as an argument for contained objects.
org.exolab.castor.mapping.AccessMode	getAccessMode(org.exolab.castor.mapping.AccessMode txMode) Get the effective accessMode of the the base type.
Identity	getActualIdentity(java.lang.ClassLoader loader, java.lang.Object o) Get the identity from a object of the base type.
Identity	getActualIdentity(TransactionContext tx, java.lang.Object o) Get the identity from a object of the base type.
java.util.Properties	getCacheParams() Returns the active cache parameters.
CallbackInterceptor	getCallback() Get the callback interceptor of the base type.
org.exolab.castor.mapping.ClassDescriptor	getClassDescriptor()
ClassMolder	getDepends() Get the depends class' ClassMolder.
ClassMolder	getExtends() Get the extends class' ClassMolder.
FieldMolder[]	getFields() Get the FieldMolder of the fields of the base type, except the identity fields.
Identity	getIdentity(TransactionContext tx, java.lang.Object o) Get the identity from a object of the base type.
FieldMolder[]	getIds() Get the FieldMolders of the identity fields.
java.lang.Class	getJavaClass(java.lang.ClassLoader loader) Get the base class of this ClassMolder given a ClassLoader.
LockEngine	getLockEngine() Get the LockEngine which this ClassMolder belongs to.
java.lang.String	getName() Get the fully qualified name of the base type of this ClassMolder.
java.lang.String	getNamedQuery(java.lang.String name) Returns the actual (OQL) statement for the specified named query.
Persistence	getPersistence() Get the Persisetence of the base type.
int	getPriority() Determines the create priority of the data object class represented by this ClassMolder.
boolean	isAssignableFrom(java.lang.Class cls) check if the current ClassModlder is assignable from the class instance.
boolean	isDefaultIdentity(Identity identity) Test if the specified identity is the default value of the type.
boolean	isDependent() Return true if the base type of this ClassMolder is an dependent class.
boolean	isKeyGeneratorUsed() Return true if a key generator is used for the base type of this ClassMolder.
boolean	isKeyGenUsed() Return true if a key generator is used for the base type of this ClassMolder.
java.lang.Object	load(TransactionContext tx, OID oid, DepositBox locker, ProposedEntity proposedObject, org.exolab.castor.mapping.AccessMode suggestedAccessMode) Load an object with specified identity from the persistent storage.
java.lang.Object	load(TransactionContext tx, OID oid, DepositBox locker, ProposedEntity proposedObject, org.exolab.castor.mapping.AccessMode suggestedAccessMode, QueryResults results)
void	markCreate(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Walk the object model and mark object that should be created.
void	markDelete(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Prepare to delete an object with the specified identity.
java.lang.Object	newInstance(java.lang.ClassLoader loader) Return a new instance of the base class with the provided ClassLoader object.
boolean	preStore(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object, int timeout) Check the object for modification.
boolean	removeRelation(TransactionContext tx, java.lang.Object object, ClassMolder relatedMolder, java.lang.Object relatedObject) Remove the reference of a related object from an object of the base class.
void	resetResolvers()
void	revertObject(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Revert the object back to the state of begining of the transaction If the object is loaded, it will be revert as it was loaded.
(package private) void	setDepends(ClassMolder dep) Mutator method to set the depends ClassMolder.
(package private) void	setExtends(ClassMolder ext) Mutator method to set the extends ClassMolder.
void	setFieldsNull(java.lang.Object object) Set all persistence fields of object of the base type to null.
void	setIdentity(TransactionContext tx, java.lang.Object object, Identity identity) Set the identity into an object.
void	setPersistence(Persistence persist) Mutator method to set the PersistenceEngine of.
void	store(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Store a data object into the persistent storage of the base class of this ClassMolder.
java.lang.String	toString()
boolean	update(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object, org.exolab.castor.mapping.AccessMode suggestedAccessMode) Update the object which loaded or created in the other transaction to the persistent storage.
void	updateCache(TransactionContext tx, OID oid, DepositBox locker, java.lang.Object object) Update the dirty checking cache.

Methods inherited from class java.lang.Object

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

Field Detail

_isKeyGenUsed

public boolean _isKeyGenUsed

Is a key kenerator used for the base class?

Constructor Detail

ClassMolder

ClassMolder(DatingService ds,
            org.exolab.castor.mapping.loader.AbstractMappingLoader loader,
            LockEngine lock,
            org.exolab.castor.mapping.ClassDescriptor clsDesc,
            Persistence persist)
      throws java.lang.ClassNotFoundException,
             org.exolab.castor.mapping.MappingException

Creates an instance of this class.

Parameters:

ds - is the helper class for resolving depends and extends relationship among all the ClassMolder in the same LockEngine.

loader - the mapping loader.

lock - the lock engine.

clsDesc - the classDescriptor for the base class.

persist - the Persistence for the base class.

Throws:

java.lang.ClassNotFoundException - If a class cannot be loaded.

org.exolab.castor.mapping.MappingException - if an error occured with analysing the mapping information.

Method Detail

getClassDescriptor

public org.exolab.castor.mapping.ClassDescriptor getClassDescriptor()

removeRelation

public boolean removeRelation(TransactionContext tx,
                              java.lang.Object object,
                              ClassMolder relatedMolder,
                              java.lang.Object relatedObject)

Remove the reference of a related object from an object of the base class.

If the related object is PersistanceCapable, the field will be set null. If the related object is a Collection, then the related object will be removed from the Collection.

If any changed occured, transactionContext.markModified will be called, to indicate the object is modified.

It method will iterate thur all of the object's field and try to remove all the occurrence.

Parameters:

tx - the TransactionContext of the transaction in action

object - the target object of the base type of this ClassMolder

relatedMolder - the ClassMolder of the related object to be removed from the object

relatedObject - the object to be removed

getPriority

public int getPriority()

Determines the create priority of the data object class represented by this ClassMolder. Concpetually, this method determines the order of which data object should be created. A priority of 0 indicates that an object represented by this ClassMolder can be created independently, without having to consider any other data object. This method should only be called after DatingService is closed.

load

public java.lang.Object load(TransactionContext tx,
                             OID oid,
                             DepositBox locker,
                             ProposedEntity proposedObject,
                             org.exolab.castor.mapping.AccessMode suggestedAccessMode)
                      throws PersistenceException

Load an object with specified identity from the persistent storage.

Parameters:

tx - the TransactionContext in action

oid - the object identity of the desired object

locker - the DepositBox of the object which is used to store the dirty checking cache of the object.

suggestedAccessMode - the acessMode for the object

Returns:

the object stamp for the object in the persistent storage

Throws:

PersistenceException

load

public java.lang.Object load(TransactionContext tx,
                             OID oid,
                             DepositBox locker,
                             ProposedEntity proposedObject,
                             org.exolab.castor.mapping.AccessMode suggestedAccessMode,
                             QueryResults results)
                      throws PersistenceException

Throws:

PersistenceException

create

public Identity create(TransactionContext tx,
                       OID oid,
                       DepositBox locker,
                       java.lang.Object object)
                throws PersistenceException

Create an object of the base class with specified identity into the persistence storage.

Parameters:

tx - transaction in action

oid - the object identity of the object to be created.

locker - the dirty checking cache of the object

object - the object to be created

Returns:

the identity of the object

Throws:

PersistenceException

markCreate

public void markCreate(TransactionContext tx,
                       OID oid,
                       DepositBox locker,
                       java.lang.Object object)
                throws PersistenceException

Walk the object model and mark object that should be created.

Parameters:

tx - transaction in action

oid - the object identity of the object to be created.

locker - the dirty checking cache of the object

object - the object to be created

Throws:

PersistenceException

preStore

public boolean preStore(TransactionContext tx,
                        OID oid,
                        DepositBox locker,
                        java.lang.Object object,
                        int timeout)
                 throws PersistenceException

Check the object for modification. If dpendent object is dereferenced, it method will remove the object thru the transaction. If an related object is dereferenced, it method will make sure the formally object will be dereferenced from the other side as well. This method is called in prepare (for commit) state of the transaction. This method indicates if the object needed to be persist or cache should be update using TransactionContext.markDelete.

Parameters:

tx - transaction in action

oid - the object identity of the object

locker - the dirty check cache for the object

object - the data object to be checked

timeout - timeout of updating the lock if needed

Returns:

true if the object is modified

Throws:

PersistenceException

store

public void store(TransactionContext tx,
                  OID oid,
                  DepositBox locker,
                  java.lang.Object object)
           throws PersistenceException

Store a data object into the persistent storage of the base class of this ClassMolder.

Parameters:

tx - Transaction in action

oid - the object identity of the stored object

locker - the dirty check cache of the object

object - the object to be stored

Throws:

PersistenceException

update

public boolean update(TransactionContext tx,
                      OID oid,
                      DepositBox locker,
                      java.lang.Object object,
                      org.exolab.castor.mapping.AccessMode suggestedAccessMode)
               throws PersistenceException

Update the object which loaded or created in the other transaction to the persistent storage.

Parameters:

tx - Transaction in action

oid - the object identity of the stored object

locker - the dirty check cache of the object

object - the object to be stored

Returns:

boolean true if the updating object should be created

Throws:

PersistenceException

updateCache

public void updateCache(TransactionContext tx,
                        OID oid,
                        DepositBox locker,
                        java.lang.Object object)

Update the dirty checking cache. This method is called after a transaction completed successfully.

Parameters:

tx - - transaction in action

oid - - object's identity of the target object

locker - - the dirty checking cache of the target object

object - - the target object

delete

public void delete(TransactionContext tx,
                   OID oid)
            throws PersistenceException

Delete an object of the base type from the persistence storage. All object to be deleted by this method will be markDelete before it method is called.

Parameters:

tx - - transaction in action

oid - - the object identity of the target object

Throws:

PersistenceException

markDelete

public void markDelete(TransactionContext tx,
                       OID oid,
                       DepositBox locker,
                       java.lang.Object object)
                throws PersistenceException

Prepare to delete an object with the specified identity. If any sub-object should be deleted along with the target object, it should be deleted by this method.

Parameters:

tx - - transaction in action

oid - - object's identity of the target object

locker - - the dirty checking cache of the target object

object - - the target object

Throws:

PersistenceException

revertObject

public void revertObject(TransactionContext tx,
                         OID oid,
                         DepositBox locker,
                         java.lang.Object object)
                  throws PersistenceException

Revert the object back to the state of begining of the transaction If the object is loaded, it will be revert as it was loaded. If the object is created, it will be revert as it was just created.

Parameters:

tx - - transaction in action

oid - - the object identity of the target object

locker - - the dirty checking cache of the target object

object - - the target object

Throws:

PersistenceException

newInstance

public java.lang.Object newInstance(java.lang.ClassLoader loader)
                             throws java.lang.InstantiationException,
                                    java.lang.IllegalAccessException,
                                    java.lang.ClassNotFoundException

Return a new instance of the base class with the provided ClassLoader object.

Parameters:

loader - the ClassLoader object to use to create a new object.

Returns:

Object the object reprenseted by this ClassMolder, and instanciated with the provided ClassLoader instance.

Throws:

java.lang.ClassNotFoundException

java.lang.IllegalAccessException

java.lang.InstantiationException

getAccessMode

public org.exolab.castor.mapping.AccessMode getAccessMode(org.exolab.castor.mapping.AccessMode txMode)

Get the effective accessMode of the the base type.

Parameters:

txMode - - the default transaction accessMode.

Returns:

the effective acessMode of the base type.

getCallback

public CallbackInterceptor getCallback()

Get the callback interceptor of the base type.

isDefaultIdentity

public boolean isDefaultIdentity(Identity identity)

Test if the specified identity is the default value of the type.

getIdentity

public Identity getIdentity(TransactionContext tx,
                            java.lang.Object o)

Get the identity from a object of the base type. If object isn't persistent and key generator is used, returns null.

Parameters:

tx - the transaction context.

o - - object of the base type.

Returns:

return an Object[] which contains the identity of the object.

getActualIdentity

public Identity getActualIdentity(TransactionContext tx,
                                  java.lang.Object o)

Get the identity from a object of the base type.

Parameters:

tx - the transaction context.

o - - object of the base type.

Returns:

return an Object[] which contains the identity of the object.

getActualIdentity

public Identity getActualIdentity(java.lang.ClassLoader loader,
                                  java.lang.Object o)

Get the identity from a object of the base type.

Parameters:

loader - the current class loader.

o - - object of the base type.

Returns:

return an Object[] which contains the identity of the object.

setIdentity

public void setIdentity(TransactionContext tx,
                        java.lang.Object object,
                        Identity identity)
                 throws PersistenceException

Set the identity into an object.

Parameters:

tx - the transaction context.

object - the object to set the identity.

identity - the new identity for the object.

Throws:

PersistenceException

getPersistence

public Persistence getPersistence()

Get the Persisetence of the base type.

setPersistence

public void setPersistence(Persistence persist)

Mutator method to set the PersistenceEngine of.

getJavaClass

public java.lang.Class getJavaClass(java.lang.ClassLoader loader)

Get the base class of this ClassMolder given a ClassLoader.

Parameters:

loader - the classloader.

Returns:

the Class instance.

isAssignableFrom

public boolean isAssignableFrom(java.lang.Class cls)

check if the current ClassModlder is assignable from the class instance.

Parameters:

cls - the Class to check the assignation

Returns:

true if assignable

getName

public java.lang.String getName()

Get the fully qualified name of the base type of this ClassMolder.

getFields

public FieldMolder[] getFields()

Get the FieldMolder of the fields of the base type, except the identity fields.

getIds

public FieldMolder[] getIds()

Get the FieldMolders of the identity fields.

getExtends

public ClassMolder getExtends()

Get the extends class' ClassMolder.

getDepends

public ClassMolder getDepends()

Get the depends class' ClassMolder.

getLockEngine

public LockEngine getLockEngine()

Get the LockEngine which this ClassMolder belongs to.

getCacheParams

public java.util.Properties getCacheParams()

Returns the active cache parameters.

Returns:

Active cache parameters.

isDependent

public boolean isDependent()

Return true if the base type of this ClassMolder is an dependent class.

setFieldsNull

public void setFieldsNull(java.lang.Object object)

Set all persistence fields of object of the base type to null.

Parameters:

object - - target object

addExtendent

void addExtendent(ClassMolder ext)

Mutator method to add a extent ClassMolder.

addDependent

void addDependent(ClassMolder dep)

Mutator method to add a dependent ClassMolder.

setExtends

void setExtends(ClassMolder ext)

Mutator method to set the extends ClassMolder.

setDepends

void setDepends(ClassMolder dep)

Mutator method to set the depends ClassMolder.

toString

public java.lang.String toString()

isKeyGenUsed

public boolean isKeyGenUsed()

Return true if a key generator is used for the base type of this ClassMolder.

isKeyGeneratorUsed

public boolean isKeyGeneratorUsed()

Return true if a key generator is used for the base type of this ClassMolder.

expireCache

public void expireCache(TransactionContext tx,
                        ObjectLock locker)
                 throws PersistenceException

Inspect the fields stored in the object passed as an argument for contained objects. Request an expireCache for each contained object.

Parameters:

tx - The TransactionContext

locker - The object that contains the fields to be inspected

Throws:

PersistenceException

resetResolvers

public void resetResolvers()

getNamedQuery

public java.lang.String getNamedQuery(java.lang.String name)

Returns the actual (OQL) statement for the specified named query.

Parameters:

name - Named query name.

Returns:

The actual (OQL) statement