org.imixs.workflow.jee.ejb
Class EntityServiceBean

java.lang.Object
  org.imixs.workflow.jee.ejb.EntityServiceBean

All Implemented Interfaces:

org.imixs.workflow.jee.ejb.EntityService

@DeclareRoles(value={"org.imixs.ACCESSLEVEL.NOACCESS","org.imixs.ACCESSLEVEL.READERACCESS","org.imixs.ACCESSLEVEL.AUTHORACCESS","org.imixs.ACCESSLEVEL.EDITORACCESS","org.imixs.ACCESSLEVEL.MANAGERACCESS"})
@RolesAllowed(value={"org.imixs.ACCESSLEVEL.NOACCESS","org.imixs.ACCESSLEVEL.READERACCESS","org.imixs.ACCESSLEVEL.AUTHORACCESS","org.imixs.ACCESSLEVEL.EDITORACCESS","org.imixs.ACCESSLEVEL.MANAGERACCESS"})
public class EntityServiceBean
extends Object
implements org.imixs.workflow.jee.ejb.EntityService

The EntityServiceBean is the a stateless session EJB implementation of the Interface org.imixs.workflow.jee.ejb.EntityService

This session bean is used to persist and find instances of the generic value transfer object org.imixs.workflow.ItemCollection. The Bean holds an instance of an EntityPersistenceManager for the persistence unit 'org.imixs.workflow.jee.ejb' to manage the following Entity EJBs:

• Entity,
• EntityIndex,
• TextIndex,
• IntegerIndex,
• DoubleIndex,
• CalendarIndex,
• ReadAccessEntity
• WriteAccessEntity

< These Entity EJBs are used to store the attributes of a ItemCollection into the connected database.

The save() method persists any instance of an ItemCollection. If a ItemCollection is saved the first time the EntityServiceBean generates the attribute $uniqueid which will be included in the ItemCollection returned by this method. If a ItemCollection was saved before the method updates the corresponding Entity Object.

The load() and findAllEntities() methods are used to read ItemCollections from the database. The remove() Method deletes a saved ItemCollection from the database.

All methods expect and return Instances of the object org.imixs.workflow.ItemCollection which is no entity EJB. So these objects are not managed by any instance of an EntityPersistenceManager.

A collection of ItemCollections can be read using the findAllEntites() method using EQL syntax.

This EntityServiceBean has methods to brand out different Attributes of a ItemCollection into external properties (TextIndex, IntegerIndex, DoubleIndex, CalendarIndex) With these functionality a client can query a set of ItemCollections later with EJB Query Language (EQL).

To define which attributes should be expended into external properties the Session EJB supports the method addIndex(). This method creates an index entry and ensures that every Entity saved before will be updated and future calls of the save() method will care about the new index to separate attributes into the Index Properties.

So each call of the save method automatically disassemble a ItemCollection into predefined Index properties and stores attributes which have an Index into a corresponding IndexData Object (TextIndex, IntegerIndex, DoubleIndex, CalendarIndex). On the other hand the load() method reassembles the ItemCollection including all attributes form the data property an any external index property. The EntiyService did not allow to access a managed Entity EJB directly. This simplifies the usage as a client works only with ItemCollections and so there is no need to handle managed and detached entity EJB instances.

Additional to the basic functionality to save and load instances of the object org.imixs.workflow.ItemCollection the method also manages the read- and writeAccess for each instance of an ItemCollection. Therefore the save() method scans an ItemCollection for the attributes '$ReadAccess' and '$WriteAccess' and saves these informations into the Entity EJBs ReadAccessEntity and WriteAccessEntity controlled by each instance of the EJB Entity. The EntityServiceBean implementation verifies in each call of the save() load(), remove() and findAllEntities() methods if the current callerPrincipal is granted to the affected entities. If an ItemCollection was saved with read- or writeAccess the access to an Instance of a saved ItemCollection will be protected for a callerPrincipal with missing read- or writeAccess. The default Read- and WriteAccess attributes '$ReadAccess' and '$WriteAccess' can be overwritten by the environment settings 'READ_ACCESS_FIELDS' and 'WRITE_ACCESS_FIELDS'

Some useful links about the oneToMany Relationship http://www.avaje.org/manydatatypes.html http://thomas-schuett.de/2008/11/14/ordered-lists-in-jpa-do-it-yourself/ http: //javaehrsson.blogspot.com/2005/10/ejb3-onetomany-and-orderby-set-versus.html http://forums.java.net/jive/thread.jspa?threadID=30869&start=0&tstart=0

Version:

1.0

Author:

rsoika

See Also:

org.imixs.workflow.jee.ejb.EntityPersistenceManager

Field Summary

Fields inherited from interface org.imixs.workflow.jee.ejb.EntityService

TYP_AUTHOR, TYP_CALENDAR, TYP_DOUBLE, TYP_INT, TYP_READER, TYP_TEXT

Constructor Summary

EntityServiceBean()

Method Summary

void	addIndex(String stitel, int ityp) This method adds a new index field to the current index list and updates existing entities.
Collection<org.imixs.workflow.ItemCollection>	findAllEntities(String query, int startpos, int count) returns a collection of ItemCollections defined by a query.
Collection<org.imixs.workflow.jee.jpa.EntityIndex>	findAllEntityIndices() returns a collection of all defined entityIndex fields.
Collection<org.imixs.workflow.ItemCollection>	findChildEntities(org.imixs.workflow.ItemCollection child, int start, int count) The method returns a collection of child ItemCollections.
org.imixs.workflow.ItemCollection	findParentEntity(org.imixs.workflow.ItemCollection child) The method returns the parent ItemCollection to a given ItemCollection.
String	getAccessRoles()
String	getReadAccessFields()
String	getWriteAccessFields()
org.imixs.workflow.ItemCollection	load(String id) This method loads a entity by its id and assembles all existing index attributes which were breaded out to subdata objects into one single ItemCollection.
void	remove(org.imixs.workflow.ItemCollection itemcol) removes an ItemCollection from the Database.
void	removeIndex(String stitel) This method removes an existing index from the current indexlist and updates existing entities.
org.imixs.workflow.ItemCollection	save(org.imixs.workflow.ItemCollection itemcol) This Method saves an ItemCollection as an Entity Bean Instance using the JPA EntityManager.

Methods inherited from class java.lang.Object

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

Constructor Detail

EntityServiceBean

public EntityServiceBean()

Method Detail

getAccessRoles

public String getAccessRoles()

Specified by:

getAccessRoles in interface org.imixs.workflow.jee.ejb.EntityService

getReadAccessFields

public String getReadAccessFields()

Specified by:

getReadAccessFields in interface org.imixs.workflow.jee.ejb.EntityService

getWriteAccessFields

public String getWriteAccessFields()

Specified by:

getWriteAccessFields in interface org.imixs.workflow.jee.ejb.EntityService

findAllEntityIndices

public Collection<org.imixs.workflow.jee.jpa.EntityIndex> findAllEntityIndices()

returns a collection of all defined entityIndex fields.

Specified by:

findAllEntityIndices in interface org.imixs.workflow.jee.ejb.EntityService

findAllEntities

public Collection<org.imixs.workflow.ItemCollection> findAllEntities(String query,
                                                                     int startpos,
                                                                     int count)

returns a collection of ItemCollections defined by a query. The method returns detached instances of new ItemCollection objects.

Unfortunately we need to call the manager.refresh() method to ensure that the entity will be synchronized with database. I saw situations with the remote session ejb where the entityManager returns old relationships :-(. The reason for this behavior is the second level cache of the TopLink driver.

Specified by:

findAllEntities in interface org.imixs.workflow.jee.ejb.EntityService

See Also:

://weblogs.java.net/blog/guruwons/archive/2006/09/understanding_t .html

findChildEntities

public Collection<org.imixs.workflow.ItemCollection> findChildEntities(org.imixs.workflow.ItemCollection child,
                                                                       int start,
                                                                       int count)

The method returns a collection of child ItemCollections. A child entity is defined by the property $uniqueidRef which points to a parent entity. The method returns only ItemCollections which are readable by the CallerPrincipal. With the startPos and count parameters it is possible to read chunks of entities.

Specified by:

findChildEntities in interface org.imixs.workflow.jee.ejb.EntityService

Parameters:

parententity -

startpos -

count -

Returns:

See Also:

findParentEntity

findParentEntity

public org.imixs.workflow.ItemCollection findParentEntity(org.imixs.workflow.ItemCollection child)

The method returns the parent ItemCollection to a given ItemCollection. A parent entity is referenced by an other entity by the property $uniqueidRef which points to a parent entity.

Specified by:

findParentEntity in interface org.imixs.workflow.jee.ejb.EntityService

Parameters:

childentity -

Returns:

parent entity

load

public org.imixs.workflow.ItemCollection load(String id)

This method loads a entity by its id and assembles all existing index attributes which were breaded out to subdata objects into one single ItemCollection. Notice: CalendarItems will be automatically converted into Date Objects. The method checks also if the callerprincipal has read access to the specific entity. if not the method returns null. The method dose not throw an exception if the user is not allowed to read the entity to prevent a aggressor with informations about the existence of that specific workitem. The returned entity also includes a temporaly attribute "isauthor" to indecate if the caller has write access to this entity.

Specified by:

load in interface org.imixs.workflow.jee.ejb.EntityService

Parameters:

id - of the entity to be loaded

Returns:

a detached Entity object or null if the entity dose not exist or the callerpincipal hat insufficient readaccess.

remove

public void remove(org.imixs.workflow.ItemCollection itemcol)
            throws org.imixs.workflow.exceptions.AccessDeniedException,
                   org.imixs.workflow.exceptions.InvalidWorkitemException

removes an ItemCollection from the Database. The method throws an Exception if the CallerPrincipal has less write Access

Specified by:

remove in interface org.imixs.workflow.jee.ejb.EntityService

Throws:

org.imixs.workflow.exceptions.AccessDeniedException

org.imixs.workflow.exceptions.InvalidWorkitemException

See Also:

#62

addIndex

public void addIndex(String stitel,
                     int ityp)
              throws Exception

This method adds a new index field to the current index list and updates existing entities. If the index already exists no changes where made. Notice that the index field name will be lowercased! Each EQL statement should use lower cased fieldnames! The method checks if the Caller is in Role "MANGER". Since the caller is no Manager there is no guarantee that the caller can update all existing Entities as maybe he can not read all entities. All existing Entities will be reorderd by this method call. So the method can take a long time to proceed

Specified by:

addIndex in interface org.imixs.workflow.jee.ejb.EntityService

Parameters:

stitel - - will be automatical transformed to lowercase!

ityp - - Type of EntityIndex

Throws:

Exception

See Also:

#62

removeIndex

public void removeIndex(String stitel)
                 throws Exception

This method removes an existing index from the current indexlist and updates existing entities. Notice that the index field name will be lowercased! Each EQL statement should use lower cased fieldnames! The method checks if the Caller is in Role "MANGER". Since the caller is no Manager there is no guarantee that the caller can update all existing Entities as maybe he can not read all entities. All existing Entities will be reorderd by this method call. So the methode can take a long time to proceed

Specified by:

removeIndex in interface org.imixs.workflow.jee.ejb.EntityService

Parameters:

stitel - - will be automatical lowercased!

Throws:

Exception

save

public org.imixs.workflow.ItemCollection save(org.imixs.workflow.ItemCollection itemcol)
                                       throws org.imixs.workflow.exceptions.AccessDeniedException

This Method saves an ItemCollection as an Entity Bean Instance using the JPA EntityManager. The method verifies if the corresponding Entity was persisted before by doing a search with the entity id ($uniqueid). If an entity instance with the corresponding id still exists this entity will be updated with the properties provided by the ItemColleciton.

If the ItemCollection dose not contain the property $uniqueid then the method will create a new Entity Bean instance calling the persist() method of the EntityManager. If the ItemColleciton contains a property $uniqueid but no Entity Bean instance with this ID exists in the database than a new Entity will be created using the provided $uniqueid as its primary key (id).

The method looks for a property "type" in the provided ItemCollection and maps this property to the corresponding Bean property. If no property with the name "type" is specified the method defaults this property to the value 'Entity'. The type property is used by the Entity Bean to categorize entities. @see org.imixs.workflow.jee.jpa.Entity

After persisting the provided ItemCollection the method returns a new updated instance of an ItemCollection containing the properties '$uniqueid' '$modified', '$created' and 'type'

Specified by:

save in interface org.imixs.workflow.jee.ejb.EntityService

Throws:

org.imixs.workflow.exceptions.AccessDeniedException