Examples
In the following section we will give you some examples how the IX JEE Workflow Components can be used in a JEE Application (Web or EJB Modul)
The best way to get a general overview about how to build a JEE Workflow Application is found in our Tutorial "Building a Workflow Application ". This tutorial is divided into tree parts which explains how to setup, model and implement a JEE based workflow application based on this project. Also see further tutorials on imixs.org project homepage. If you miss something or have questions contact us and give us your feedback.
The ItemCollection
An ItemCollection is a flexible data structure consisting of several Items (Attributes). The ItemCollection follows the Generic Data Object pattern. So you can store flexible data of a business object into seperate Item Data Objects unsing a ItemCollection. Each Item has a name/value pair. The ItemCollection itself implements class java.util.Hashtable without being centralized interface as this would not allow standardized data exchange between plug-ins of different frameworks. Through the ItemCollection, the programmer is provided with a very open data structure for easy access to individual values.
The follwoing Example shows how to work with an ItemCollection Object:
....
// create new ItemCollection
ItemCollection myValues=new ItemCollection();
myValues.replaceItemValue("$processid",new Integer(1));
myValues.replaceItemValue("txtworkflowstatus","created");
// store mulitple values into one item
Vector v=new Vector();
v.add("hans");
v.add("anna");
v.add("frank");
myValues.replaceItemValue("namTeam",v);
....
// read ItemCollection attribute
Integer iStatus=myValues.getItemValueInteger("$processid");
String s=myValues.getItemValueString("txtworkflowstatus");
Vector v=myValues.getItemValue("namteam");
....
As the ItemCollection is a Pojo you can use this object in any Java API independend to the JEE specification. The EntityService EJB The EntityService EJB is the most easiest way to work and persits the generic data object "ItemCollection". This statless session EJB allows you to persist, update and find ItemCollections in a easy way.
All the Example assume that you have created an ItemColleation with different Attributes. The ItemCollection is explaint in the IX Workflow API .
Create a new ItemCollection
import org.imixs.workflow.ItemCollection;
.....
ItemCollection itemCol=new ItemCollection();
itemCol.replaceItemValue("txtName", "Manfred");
itemCol.replaceItemValue("txtStreet", "Lindenstrasse");
itemCol.replaceItemValue("numAge", new Integer(30));
// store also multi values...
Vector v=new Vector();
v.addElement("Anna");
v.addElement("Eddy");
itemCol.replaceItemValue("namTeam",v);
Store the ItemCollection using the EntityService:
import org.imixs.workflow.ItemCollection;
.....
@EJB
org.imixs.workflow.jee.ejb.EntityService entityService;
....
workItem=entityService.save(workItem);
String sUniqueID=workItem.getItemValueString("$uniqueid");
Notice that it is usefull to save the $uniqueID of a newly created workitem.
After you have saved an ItemCollection you can load it using the $UniqueID attribute:
import org.imixs.workflow.ItemCollection;
.....
@EJB
org.imixs.workflow.jee.ejb.EntityService entityService;
....
workItem=entityService.load(sUniqueID);
Read and WirteAccess
It is importend to understand the the EntityService cares about the individual read and write access of the user calling the EntityService. This means that you have not to care about programatic security. If a user have no read access to a specific ItemCollection the load(id) method of the EntySevice will return null.
If a user tries to upate an existing ItemCollection using the save() method without the necessary author access the method will throw an exception. See the Access privilegs for more details.
You can ask the EntityManager if a user have write access to a specific ItemCollection before calling the save method to avoid the exeption:
import org.imixs.workflow.ItemCollection;
.....
@EJB
org.imixs.workflow.jee.ejb.EntityService entityService;
....
if (entityService.isAuthor(sUniqueID))
workItem=entityService.save(workItem);
else
// user is not allowed to update this item
.....
Query ItemCollections using the EntityService
Using the EntityService gives you an powerfull service to query ItemCollections using EQL Statements. To query a set of ItemCollections you define a EQL Statement and call the findAllEntities method of the EntiyService.
EQL alows you to by formulate conditions to different attributes stored into the ItemCollections before.
Notice that the EntityService cares about the individual read access of the user which is calling the findAllEntities method. This means that also when the query will contain a large set of ItemCollections the method returns only these ItemCollections the user have read access! See the Access privilegs for more details. Create an Index
First make sure that you have defined indexes for all the attributes which you add as conditions into your query. You can add an Index any time because all prious saved ItemCollections will be reorganized automaticaly by the IX JEE EntityPersistence Manager.
@EJB
org.imixs.workflow.jee.ejb.EntityService entityService;
.....
entityService.addIndex("type", EntityIndex.TYP_TEXT);
entityService.addIndex("namcreator", EntityIndex.TYP_TEXT);
entityService.addIndex("namteam", EntityIndex.TYP_TEXT);
You can add the addIndex calls directly into the @PostConstruct method of an EJB or into the init() method of a backing bean in JSF.
Query ItemCollections
you can use any kind of EQL Statement to query the ItemCollections stored using the EntityService. The following Example shows the source code of a query method to find the ItemCollection with an specifc ID:
@EJB
org.imixs.workflow.jee.ejb.EntityService entityService;
.....
public ItemCollection findProject(String id) {
String sQuery = "select project from Entity as project "
+ " where project.id = '" + id + "'";
Collection<ItemCollection> col = entityService.findAllEntities(sQuery,
0, -1);
if (col.size() > 0) {
ItemCollection aworkitem = col.iterator().next();
return aworkitem;
}
return null;
}
EQL Examples
You can use differnt select statemets to formulate complex querys. The following examples give you an idea of what is possible using the IX Entity Service
All the examples assumes that your have created an index for each named Item attribute used in the query. In these examples the index fileds are : type, namcreator, namteam, txtname. Simple Join
This query selects all Entities which an attribute "type" and the value "project"
SELECT project from Entity AS project JOIN project.textItems AS t WHERE t.itemName = 'type' AND t.itemValue = 'project' ORDER BY statement
This query is similar to the first query but add an order by clause to sort the result set by the attribute txtname
SELECT project FROM Entity as project join project.textItems as t1 join project.textItems as t2 WHERE t1.itemName = 'type' AND t1.itemValue = 'project' AND t2.itemName = 'txtname' ORDER BY t2.itemValue asc
Mulitible Joins
The following query formulates a multiple join to query different attributes and using the IN operator:
SELECT project FROM Entity AS project
JOIN project.textItems AS t1
JOIN project.textItems AS t2
JOIN project.textItems AS t3
WHERE t1.itemName = 'type'
AND t1.itemValue = 'project'
AND t3.itemName = 'txtname'
AND t2.itemName IN ('namcreator','namteam')
AND t2.itemValue = 'ronny'
ORDER BY t3.itemValue asc
Notice that as more joins you use as longer will take the query in the backend bean.
the following example selects show you you can speed up a query using the the sprecific readAccess attribute. The EntiyService selects in this case onyl the ItemCollections where the user is a named reader. So the EntitService have not to sort out results the user have no readAccess:
SELECT project FROM Entity AS project
JOIN project.textItems AS t1
JOIN project.readerItems AS t2
JOIN project.textItems AS t3
WHERE t1.itemName = 'type'
AND t1.itemValue = 'project'
AND t3.itemName = 'txtname'
AND t2.itemName = 'namworkflowreadaccess'
AND t2.itemValue = 'rsoika'
ORDER BY t3.itemValue asc
