org.imixs.workflow.engine

Class DocumentService

java.lang.Object

org.imixs.workflow.engine.DocumentService

@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 DocumentService
extends Object

The DocumentService is used to save and load instances of ItemCollections into a Database. The DocumentService throws an AccessDeniedException if the CallerPrincipal is not allowed to save or read a specific Document from the database. So the DocumentService 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.jpa' to manage the Document entity bean class. The Document entity bean is 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 DocumentService 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 Document Object.

The load() and find() 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 find() method using EQL syntax.

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'. The DocumentService verifies in each call of the save() load(), remove() and find() 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.

Version:

1.0

Author:

rsoika

See Also:

Document

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACCESSLEVEL_AUTHORACCESS
static String	ACCESSLEVEL_EDITORACCESS
static String	ACCESSLEVEL_MANAGERACCESS
static String	ACCESSLEVEL_NOACCESS
static String	ACCESSLEVEL_READERACCESS
protected javax.enterprise.event.Event<DocumentEvent>	documentEvents
static String	IMMUTABLE
static String	INVALID_PARAMETER
static String	INVALID_UNIQUEID
static String	ISAUTHOR
static String	NOINDEX
static String	OPERATION_NOTALLOWED
static String	READACCESS
static String	USER_GROUP_LIST
protected javax.enterprise.event.Event<UserGroupEvent>	userGroupEvents
static String	WRITEACCESS

Constructor Summary

Constructors

Constructor and Description
DocumentService()

Method Summary

Modifier and Type	Method and Description
void	backup(String query, String filePath) This method creates a backup of the result set form a Lucene search query.
int	count(String searchTerm) Returns the total hits for a given search query.
int	count(String sSearchTerm, int maxResult) Returns the total hits for a given search query.
int	countPages(String searchTerm, int pageSize) Returns the total pages for a given search term and a given page size.
List<ItemCollection>	find(String searchTerm, int pageSize, int pageIndex) The method returns a list of ItemCollections by calling the LuceneSearchService.
List<ItemCollection>	find(String searchTerm, int pageSize, int pageIndex, String sortBy, boolean sortReverse) The method returns a sorted list of ItemCollections by calling the LuceneSearchService.
List<ItemCollection>	findDocumentsByRef(String uniqueIdRef, int pageSize, int pageIndex) The method returns a collection of ItemCollections referred by a $uniqueid.
String	getAccessRoles() Returns a comma separated list of additional Access-Roles defined for this service
Boolean	getDisableOptimisticLocking()
List<ItemCollection>	getDocumentsByQuery(String query) Returns all documents of by JPQL statement
List<ItemCollection>	getDocumentsByQuery(String query, int maxResult) Returns all documents of by JPQL statement.
List<ItemCollection>	getDocumentsByQuery(String query, int firstResult, int maxResult) Returns all documents of by JPQL statement.
List<ItemCollection>	getDocumentsByType(String type) Returns an unordered list of all documents of a specific type.
List<String>	getUserNameList() This method returns a list of user names, roles and application groups the user belongs to.
boolean	isUserContained(List<String> nameList) This method returns true, if at least one element of the current UserNameList is contained in a given name list.
boolean	isUserInRole(String rolename) Test if the caller has a given security role.
ItemCollection	load(String id) This method loads an ItemCollection from the Database.
void	remove(ItemCollection document) This method removes an ItemCollection from the database.
void	restore(String filePath) This method restores a backup from the file system and imports the Documents into the database.
ItemCollection	save(ItemCollection document) This Method saves an ItemCollection into the database.
ItemCollection	saveByNewTransaction(ItemCollection itemcol) This method saves a workitem in a new transaction.
void	setAccessRoles(String accessRoles)
void	setDisableOptimisticLocking(Boolean disableOptimisticLocking) returns the disable optimistic locking status

Methods inherited from class java.lang.Object

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

Field Detail

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

READACCESS

public static final String READACCESS

See Also:

Constant Field Values

WRITEACCESS

public static final String WRITEACCESS

See Also:

Constant Field Values

ISAUTHOR

public static final String ISAUTHOR

See Also:

Constant Field Values

NOINDEX

public static final String NOINDEX

See Also:

Constant Field Values

IMMUTABLE

public static final String IMMUTABLE

See Also:

Constant Field Values

USER_GROUP_LIST

public static final String USER_GROUP_LIST

See Also:

Constant Field Values

OPERATION_NOTALLOWED

public static final String OPERATION_NOTALLOWED

See Also:

Constant Field Values

INVALID_PARAMETER

public static final String INVALID_PARAMETER

See Also:

Constant Field Values

INVALID_UNIQUEID

public static final String INVALID_UNIQUEID

See Also:

Constant Field Values

documentEvents

@Inject
protected javax.enterprise.event.Event<DocumentEvent> documentEvents

userGroupEvents

@Inject
protected javax.enterprise.event.Event<UserGroupEvent> userGroupEvents

Constructor Detail

DocumentService

public DocumentService()

Method Detail

getAccessRoles

public String getAccessRoles()

Returns a comma separated list of additional Access-Roles defined for this service

Returns:

setAccessRoles

public void setAccessRoles(String accessRoles)

setDisableOptimisticLocking

public void setDisableOptimisticLocking(Boolean disableOptimisticLocking)

returns the disable optimistic locking status

getDisableOptimisticLocking

public Boolean getDisableOptimisticLocking()

getUserNameList

public List<String> getUserNameList()

This method returns a list of user names, roles and application groups the user belongs to.

A client can extend the list of user groups associated with a userId by reacting on the CDI event 'UserGrouptEvent'.

Returns:

See Also:

UserGroupEvent

isUserContained

public boolean isUserContained(List<String> nameList)

This method returns true, if at least one element of the current UserNameList is contained in a given name list. The comparison is case sensitive!

Parameters:

nameList -

Returns:

isUserInRole

public boolean isUserInRole(String rolename)

Test if the caller has a given security role.

Parameters:

rolename -

Returns:

true if user is in role

save

public ItemCollection save(ItemCollection document)
                    throws AccessDeniedException

This Method saves an ItemCollection into the 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 existing 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

The method adds/updates the document into the lucene index.

The method returns a itemCollection without the $VersionNumber from the persisted entity. (see issue #226)

issue #230: The document will be marked as 'saved' so that the methods load() and getDocumentsByQuery() can evaluate this flag. Depending on the state, the methods can decide the correct behavior. In general we detach a document in the load() and getDocumentsByQuery() method. This is for performance reasons and the fact, that a ItemCollection can hold byte arrays which will be copied by reference. In cases where these methods are called after a document was saved (document is now managed), in one single transaction, the detach call will discard the changes made by the save() method. For that reason we flag the entity and evaluate this flag in the load method evaluates the save status.

Parameters:

ItemCollection - to be saved

Returns:

updated ItemCollection

Throws:

AccessDeniedException

saveByNewTransaction

public ItemCollection saveByNewTransaction(ItemCollection itemcol)
                                    throws AccessDeniedException

This method saves a workitem in a new transaction. The method can be used by plugins to isolate a save request from the current transaction context. To call this method a EJB session context is necessary: workitem= sessionContext.getBusinessObject(EntityService.class) .saveByNewTransaction(workitem);

Parameters:

itemcol -

Returns:

Throws:

AccessDeniedException

load

public ItemCollection load(String id)

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

The method checks if the CallerPrincipal has read access to Document stored in the database. If not, the method returns null.

Note: 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 Document.

The CallerPrincipial need to have at least the access level org.imixs.ACCESSLEVEL.READACCESS

issue #230 In case a document is not flagged (not saved during same transaction), we detach the loaded entity. In case a document is flagged (saved during save transaction) we may not detach it, but make a deepCopy (clone) of the document instance. This will avoid the effect, that data written to a document get lost in a long running transaction with save and load calls.

Parameters:

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

Returns:

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

remove

public void remove(ItemCollection document)
            throws AccessDeniedException

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 the document form the lucene index.

Parameters:

ItemCollection - to be removed

Throws:

AccessDeniedException

count

public int count(String searchTerm)
          throws QueryException

Returns the total hits for a given search query. The provided search term will be extended with a users roles to test the read access level of each workitem matching the search term. The usernames and user roles will be search lowercase!

Parameters:

sSearchTerm -

Returns:

total hits of search result

Throws:

QueryException - in case the searchterm is not understandable.

See Also:

search(String, int, int, Sort, Operator)

count

public int count(String sSearchTerm,
                 int maxResult)
          throws QueryException

Returns the total hits for a given search query. The provided search term will be extended with a users roles to test the read access level of each workitem matching the search term. The usernames and user roles will be search lowercase! The optional param 'maxResult' can be set to overwrite the DEFAULT_MAX_SEARCH_RESULT.

Parameters:

sSearchTerm -

maxResult - - max search result

defaultOperator - - optional to change the default search operator

Returns:

total hits of search result

Throws:

QueryException - in case the searchterm is not understandable.

See Also:

search(String, int, int, Sort, Operator)

countPages

public int countPages(String searchTerm,
                      int pageSize)
               throws QueryException

Returns the total pages for a given search term and a given page size.

Parameters:

searchTerm -

pageSize -

Returns:

total pages of search result

Throws:

QueryException - in case the searchterm is not understandable.

See Also:

count(String sSearchTerm)

find

public List<ItemCollection> find(String searchTerm,
                                 int pageSize,
                                 int pageIndex)
                          throws QueryException

The method returns a list of ItemCollections by calling the LuceneSearchService. The method expects an valid Lucene search term.

The method returns only ItemCollections which are readable by the CallerPrincipal. With the pageSize and pageNumber it is possible to paginate.

Parameters:

searchTerm - - Lucene search term

pageSize - - total docs per page

pageIndex - - number of page to start (default = 0)

Returns:

list of ItemCollection elements

Throws:

QueryException

See Also:

LuceneSearchService

find

public List<ItemCollection> find(String searchTerm,
                                 int pageSize,
                                 int pageIndex,
                                 String sortBy,
                                 boolean sortReverse)
                          throws QueryException

The method returns a sorted list of ItemCollections by calling the LuceneSearchService. The result list can be sorted by a sortField and a sort direction.

The method expects an valid Lucene search term. The method returns only ItemCollections which are readable by the CallerPrincipal. With the pageSize and pageNumber it is possible to paginate.

Parameters:

searchTerm - - Lucene search term

pageSize - - total docs per page

pageIndex - - number of page to start (default = 0)

sortBy - -optional field to sort the result

sortReverse - - optional sort direction

Returns:

list of ItemCollection elements

Throws:

QueryException

See Also:

LuceneSearchService

findDocumentsByRef

public List<ItemCollection> findDocumentsByRef(String uniqueIdRef,
                                               int pageSize,
                                               int pageIndex)

The method returns a collection of ItemCollections referred by a $uniqueid.

The method returns only ItemCollections which are readable by the CallerPrincipal. With the pageSize and pageNumber it is possible to paginate.

Parameters:

uniqueIdRef - - $uniqueId to be referred by the collected documents

pageSize - - total docs per page

pageIndex - - number of page to start (default = 0)

Returns:

resultset

getDocumentsByType

public List<ItemCollection> getDocumentsByType(String type)

Returns an unordered list of all documents of a specific type. The method throws an InvalidAccessException in case no type attribute is defined.

Parameters:

type -

Returns:

Throws:

InvalidAccessException

getDocumentsByQuery

public List<ItemCollection> getDocumentsByQuery(String query)

Returns all documents of by JPQL statement

Parameters:

query - - JPQL statement

Returns:

getDocumentsByQuery

public List<ItemCollection> getDocumentsByQuery(String query,
                                                int maxResult)

Returns all documents of by JPQL statement.

Parameters:

query - - JPQL statement

maxResult - - maximum result set

Returns:

getDocumentsByQuery

public List<ItemCollection> getDocumentsByQuery(String query,
                                                int firstResult,
                                                int maxResult)

Returns all documents of by JPQL statement.

Parameters:

query - - JPQL statement

maxResult - - maximum result set

Returns:

backup

public void backup(String query,
                   String filePath)
            throws IOException,
                   QueryException

This method creates a backup of the result set form a Lucene search query. The document list will be stored into the file system. The method stores the Map from the ItemCollection to be independent from version upgrades. To manage large dataSets the method reads the documents in smaller blocks

Parameters:

entities -

Throws:

IOException

QueryException

restore

public void restore(String filePath)
             throws IOException

This method restores a backup from the file system and imports the Documents into the database.

Parameters:

filepath -

Throws:

IOException