org.imixs.workflow.jee.ejb
Class EntityService

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

All Implemented Interfaces:

EntityServiceRemote

@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 EntityService
extends Object
implements EntityServiceRemote

The EntityService is used to save and load instances of ItemCollections into a Database. The EntityService throws an AccessDeniedException if the CallerPrincipal is not allowed to save or read a specific ItemCollection from the database. So the EntityService can be used to save business objects into a database with individual read- or writeAccess restrictions.

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

static String	ACCESSLEVEL_AUTHORACCESS
static String	ACCESSLEVEL_EDITORACCESS
static String	ACCESSLEVEL_MANAGERACCESS
static String	ACCESSLEVEL_NOACCESS
static String	ACCESSLEVEL_READERACCESS
static int	TYP_CALENDAR
static int	TYP_DOUBLE
static int	TYP_INT
static int	TYP_TEXT
static String	UNIQUEID

Constructor Summary

EntityService()

Method Summary

void	addIndex(String stitel, int ityp) Adds an Index for a property provided by ItemCollection objects.
Collection<org.imixs.workflow.ItemCollection>	findAllEntities(String query, int startpos, int count) The method returns a collection of ItemCollections.
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 child ItemCollection.
String	getAccessRoles() Returns additional AccessRoles defined for the EJB instance
Collection<EntityIndex>	getIndices() The method returns a list of EntityIndex which defines external properties
String	getReadAccessFields() Returns additional ReadAccessFields defined for the EJB instance.
String	getWriteAccessFields() Returns additional WriteAccessFields defined for the EJB instance.
org.imixs.workflow.ItemCollection	load(String id) This method loads an ItemCollection from the Database.
void	remove(org.imixs.workflow.ItemCollection itemcol) This method 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 into a database.

Methods inherited from class java.lang.Object

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

Field Detail

TYP_TEXT

public static final int TYP_TEXT

See Also:

Constant Field Values

TYP_INT

public static final int TYP_INT

See Also:

Constant Field Values

TYP_DOUBLE

public static final int TYP_DOUBLE

See Also:

Constant Field Values

TYP_CALENDAR

public static final int TYP_CALENDAR

See Also:

Constant Field Values

ACCESSLEVEL_NOACCESS

public static final String ACCESSLEVEL_NOACCESS

See Also:

Constant Field Values

ACCESSLEVEL_READERACCESS

public static final String ACCESSLEVEL_READERACCESS

See Also:

Constant Field Values

ACCESSLEVEL_AUTHORACCESS

public static final String ACCESSLEVEL_AUTHORACCESS

See Also:

Constant Field Values

ACCESSLEVEL_EDITORACCESS

public static final String ACCESSLEVEL_EDITORACCESS

See Also:

Constant Field Values

ACCESSLEVEL_MANAGERACCESS

public static final String ACCESSLEVEL_MANAGERACCESS

See Also:

Constant Field Values

UNIQUEID

public static String UNIQUEID

Constructor Detail

EntityService

public EntityService()

Method Detail

getAccessRoles

public String getAccessRoles()

Returns additional AccessRoles defined for the EJB instance

Specified by:

getAccessRoles in interface EntityServiceRemote

Returns:

getReadAccessFields

public String getReadAccessFields()

Returns additional ReadAccessFields defined for the EJB instance. Default=$ReadAccess

Specified by:

getReadAccessFields in interface EntityServiceRemote

Returns:

getWriteAccessFields

public String getWriteAccessFields()

Returns additional WriteAccessFields defined for the EJB instance. Default=$WriteAccess

Specified by:

getWriteAccessFields in interface EntityServiceRemote

Returns:

save

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

This Method saves an ItemCollection into a database. If the ItemCollection is saved the first time the method generates a uniqueID ('$uniqueid') which can be used to identify the ItemCollection by its ID. If the ItemCollection was saved before the method updates the ItemCollection stored in the database. The Method returns an updated instance of the ItemCollection containing the attributes $modified, $created, and $uniqueid

The method throws an AccessDeniedException if the CallerPrincipal is not allowed to save or update the ItemCollection in the database. The CallerPrincipial should have at least the access Role org.imixs.ACCESSLEVEL.AUTHORACCESS

Specified by:

save in interface EntityServiceRemote

Parameters:

ItemCollection - to be saved

Returns:

updated ItemCollection

Throws:

org.imixs.workflow.exceptions.AccessDeniedException

org.imixs.workflow.exceptions.InvalidWorkitemException

load

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

This method loads an ItemCollection from the Database. The method expects a valid $unqiueID to identify the ItemCollection saved before into the database. The method returns null if no ItemCollection with the corresponding ID exists.

The method checks if the CallerPrincipal has read access to ItemCollection stored in the database. If not the method returns null. The method dose not throw an AccessDeniedException if the user is not allowed to read the entity to prevent a aggressor with informations about the existence of that specific ItemCollection.

CallerPrincipial should have at least the access Role org.imixs.ACCESSLEVEL.READACCESS

Specified by:

load in interface EntityServiceRemote

Parameters:

id - - the $unqiueid of the ItemCollection to be loaded

Returns:

ItemCollection object or null if the ItemColleciton dose not exist or the CallerPrincipal hat insufficient read access.

remove

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

This method removes an ItemCollection from the database. If the CallerPrincipal is not allowed to access the ItemColleciton the method throws an AccessDeniedException.

The CallerPrincipial should have at least the access Role org.imixs.ACCESSLEVEL.AUTHORACCESS

Also the method removes all existing relation ships of the entity. This is necessary becaus of the FetchType.LAZY used for most relations.

Specified by:

remove in interface EntityServiceRemote

Parameters:

ItemCollection - to be removed

Throws:

Exception

org.imixs.workflow.exceptions.AccessDeniedException

org.imixs.workflow.exceptions.InvalidWorkitemException

addIndex

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

Adds an Index for a property provided by ItemCollection objects. An existing Index can be used to select ItemCollections using a JPQL statement. @see findEntitesByQuery The method throws an AccessDeniedException if the CallerPrinciapal is not in the role org.imixs.ACCESSLEVEL.MANAGERACCESS.

Specified by:

addIndex in interface EntityServiceRemote

Parameters:

name - of a property (not case sensetive)

ityp - - Type of EntityIndex

Throws:

Exception

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 "org.imixs.ACCESSLEVEL.MANAGERACCESS". 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:

removeIndex in interface EntityServiceRemote

Parameters:

stitel - - will be automatical lowercased!

Throws:

Exception

getIndices

public Collection<EntityIndex> getIndices()

The method returns a list of EntityIndex which defines external properties

Returns:

findAllEntities

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

The method returns a collection of ItemCollections. The method expects an valid jPQL statement. 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. The jPQL Statement must match the conditions of the JPA Object Class Entity

Specified by:

findAllEntities in interface EntityServiceRemote

Parameters:

query -

startpos -

count -

Returns:

See Also:

org.imixs.workfow.jee.jpa.Entity

findParentEntity

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

The method returns the parent ItemCollection to a given child ItemCollection. A parent ItemCollection is referenced by a child ItemCollection through the property $uniqueidRef which is equals the parent entity's $uniqueID.

Specified by:

findParentEntity in interface EntityServiceRemote

Parameters:

childentity -

Returns:

parententity

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 EntityServiceRemote

Parameters:

parententity -

startpos -

count -

Returns:

See Also:

findParentEntity