org.jboss.ejb
Interface EntityPersistenceStore

All Superinterfaces:

AllowedOperationsFlags, ContainerPlugin, org.jboss.system.Service

All Known Subinterfaces:

JDBCEntityPersistenceStore

All Known Implementing Classes:

CMPFilePersistenceManager, CMPInMemoryPersistenceManager, JDBCStoreManager, JDBCStoreManager2

public interface EntityPersistenceStore
extends ContainerPlugin

This interface is implemented by any EntityBean persistence Store.

These stores just deal with the persistence aspect of storing java objects. They need not be aware of the EJB semantics. They act as delegatees for the CMPEntityPersistenceManager class.

Version:

$Revision: 57209 $

Author:

Rickard Öberg, Marc Fleury, Simone Bordet

See Also:

EntityPersistenceManager

Field Summary

Fields inherited from interface org.jboss.ejb.AllowedOperationsFlags

IN_AFTER_BEGIN, IN_AFTER_COMPLETION, IN_BEFORE_COMPLETION, IN_BUSINESS_METHOD, IN_EJB_ACTIVATE, IN_EJB_CREATE, IN_EJB_FIND, IN_EJB_HOME, IN_EJB_LOAD, IN_EJB_PASSIVATE, IN_EJB_POST_CREATE, IN_EJB_REMOVE, IN_EJB_STORE, IN_EJB_TIMEOUT, IN_INTERCEPTOR_METHOD, IN_SERVICE_ENDPOINT_METHOD, IN_SET_ENTITY_CONTEXT, IN_SET_MESSAGE_DRIVEN_CONTEXT, IN_SET_SESSION_CONTEXT, IN_UNSET_ENTITY_CONTEXT, NOT_ALLOWED

Method Summary

void	activateEntity(EntityEnterpriseContext instance) This method is called when an entity shall be activated.
Object	createBeanClassInstance() Returns a new instance of the bean class or a subclass of the bean class.
Object	createEntity(Method m, Object[] args, EntityEnterpriseContext instance) This method is called whenever an entity is to be created.
Collection	findEntities(Method finderMethod, Object[] args, EntityEnterpriseContext instance, GenericEntityObjectFactory factory) This method is called when collections of entities are to be found.
Object	findEntity(Method finderMethod, Object[] args, EntityEnterpriseContext instance, GenericEntityObjectFactory factory) This method is called when single entities are to be found.
void	initEntity(EntityEnterpriseContext ctx) Initializes the instance context.
boolean	isModified(EntityEnterpriseContext instance) This method is used to determined whether the instance was modified.
boolean	isStoreRequired(EntityEnterpriseContext instance) This method is used to determine if an entity should be stored.
void	loadEntity(EntityEnterpriseContext instance) This method is called whenever an entity shall be load from the underlying storage.
void	passivateEntity(EntityEnterpriseContext instance) This method is called when an entity shall be passivate.
Object	postCreateEntity(Method m, Object[] args, EntityEnterpriseContext instance) This method is called after the createEntity.
void	removeEntity(EntityEnterpriseContext instance) This method is called when an entity shall be removed from the underlying storage.
void	storeEntity(EntityEnterpriseContext instance) This method is called whenever an entity shall be stored to the underlying storage.

Methods inherited from interface org.jboss.ejb.ContainerPlugin

setContainer

Methods inherited from interface org.jboss.system.Service

create, destroy, start, stop

Method Detail

createBeanClassInstance

Object createBeanClassInstance()
                               throws Exception

Returns a new instance of the bean class or a subclass of the bean class.

Returns:

the new instance

Throws:

Exception

initEntity

void initEntity(EntityEnterpriseContext ctx)

Initializes the instance context.

This method is called before createEntity, and should resetStats the value of all cmpFields to 0 or null.

Parameters:

ctx -

createEntity

Object createEntity(Method m,
                    Object[] args,
                    EntityEnterpriseContext instance)
                    throws Exception

This method is called whenever an entity is to be created. The persistence manager is responsible for handling the results properly wrt the persistent store.

Parameters:

m - the create method in the home interface that was called

args - any create parameters

instance - the instance being used for this create call

Returns:

The primary key computed by CMP PM or null for BMP

Throws:

Exception

postCreateEntity

Object postCreateEntity(Method m,
                        Object[] args,
                        EntityEnterpriseContext instance)
                        throws Exception

This method is called after the createEntity. The persistence manager is responsible for handling the results properly wrt the persistent store.

Parameters:

m - the ejbPostCreate method in the bean class that was called

args - any create parameters

instance - the instance being used for this create call

Returns:

null

Throws:

Exception

findEntity

Object findEntity(Method finderMethod,
                  Object[] args,
                  EntityEnterpriseContext instance,
                  GenericEntityObjectFactory factory)
                  throws Exception

This method is called when single entities are to be found. The persistence manager must find out whether the wanted instance is available in the persistence store, if so it returns the primary key of the object.

Parameters:

finderMethod - the find method in the home interface that was called

args - any finder parameters

instance - the instance to use for the finder call

Returns:

a primary key representing the found entity

Throws:

RemoteException - thrown if some system exception occurs

Exception - thrown if some heuristic problem occurs

findEntities

Collection findEntities(Method finderMethod,
                        Object[] args,
                        EntityEnterpriseContext instance,
                        GenericEntityObjectFactory factory)
                        throws Exception

This method is called when collections of entities are to be found. The persistence manager must find out whether the wanted instances are available in the persistence store, and if so it must return a collection of primaryKeys.

Parameters:

finderMethod - the find method in the home interface that was called

args - any finder parameters

instance - the instance to use for the finder call

Returns:

an primary key collection representing the found entities

Throws:

RemoteException - thrown if some system exception occurs

Exception - thrown if some heuristic problem occurs

activateEntity

void activateEntity(EntityEnterpriseContext instance)
                    throws RemoteException

This method is called when an entity shall be activated.

With the PersistenceManager factorization most EJB calls should not exists However this calls permits us to introduce optimizations in the persistence store. Particularly the context has a "PersistenceContext" that a PersistenceStore can use (JAWS does for smart updates) and this is as good a callback as any other to set it up.

Parameters:

instance - the instance to use for the activation

Throws:

RemoteException - thrown if some system exception occurs

loadEntity

void loadEntity(EntityEnterpriseContext instance)
                throws RemoteException

This method is called whenever an entity shall be load from the underlying storage. The persistence manager must load the state from the underlying storage and then call ejbLoad on the supplied instance.

Parameters:

instance - the instance to synchronize

Throws:

RemoteException - thrown if some system exception occurs

isStoreRequired

boolean isStoreRequired(EntityEnterpriseContext instance)
                        throws Exception

This method is used to determine if an entity should be stored.

Parameters:

instance - the instance to check

Returns:

true, if the entity has been modified

Throws:

Exception - thrown if some system exception occurs

isModified

boolean isModified(EntityEnterpriseContext instance)
                   throws Exception

This method is used to determined whether the instance was modified. NOTE, even if the method returns true the isStoreRequired for this same instance might return false, e.g. a CMR field that doesn't have a foreign key was modified.

Parameters:

instance -

Returns:

Throws:

Exception

storeEntity

void storeEntity(EntityEnterpriseContext instance)
                 throws RemoteException

This method is called whenever an entity shall be stored to the underlying storage. The persistence manager must call ejbStore on the supplied instance and then store the state to the underlying storage.

Parameters:

instance - the instance to synchronize

Throws:

RemoteException - thrown if some system exception occurs

passivateEntity

void passivateEntity(EntityEnterpriseContext instance)
                     throws RemoteException

This method is called when an entity shall be passivate. The persistence manager must call the ejbPassivate method on the instance.

See the activate discussion for the reason for exposing EJB callback calls to the store.

Parameters:

instance - the instance to passivate

Throws:

RemoteException - thrown if some system exception occurs

removeEntity

void removeEntity(EntityEnterpriseContext instance)
                  throws RemoteException,
                         javax.ejb.RemoveException

This method is called when an entity shall be removed from the underlying storage. The persistence manager must call ejbRemove on the instance and then remove its state from the underlying storage.

Parameters:

instance - the instance to remove

Throws:

RemoteException - thrown if some system exception occurs

javax.ejb.RemoveException - thrown if the instance could not be removed