Imixs Workflow ...the open source workflow technology for business applications

Engine

The EntityService Interface

The Imixs EntityService is used to save and load instances of the Imixs Data Object org.imixs.workflow.ItemCollection into a Database. The Service Bean is based on the Java Persistence API (JPA) which provides a simple and powerful API to store and load Entity Beans.

The org.imixs.workflow.ItemCollection is the general Data Object used by the Imixs Workflow API. Each Workitem processed by the Imixs Workflow Manager is represented as an ItemCollection. But you can also store any other type of document structure with this service EJB. The Imixs EntityService provides also methods to query ItemCollection Objects using JPQL statements. This makes the service EJB very flexible to access datasets of ItemCollections. Additional the EntityService can be used to restrict the read- and write access for ItemCollection objects by providing accessvalues.

The following example shows how an instance of an ItemCollection can be saved using the Imixs EntityService:

  @EJB
  org.imixs.workflow.jee.ejb.EntityService entityService;
  //...

  ItemCollection myItemCollection=new ItemCollection;
  myItemCollection.replaceItemValue("type","product");
  myItemCollection.replaceItemValue("name","coffee");
  myItemCollection.replaceItemValue("weight",new Integer(500));
        
  // save ItemCollection
  myItemCollection=entityService.save(myItemCollection);

In this example a new ItemCollection is created and two properties ('name' and 'age') are stored into the ItemCollection. The save() method stores the ItemCollection into the database. If the ItemCollection is stored the first time, the method generates an ID which can be used to identify the ItemCollection for later access. This ID is provided in the property '$uniqueid' which will be added by the Entity Service. If the ItemCollection was saved before the method updates the ItemCollection stored in the database.

The following example shows how to use the $uniqueid of a stored ItemCollection to load the ItemCollection from the EntityService. For this the ID is passed to the load() method.

  @EJB
  org.imixs.workflow.jee.ejb.EntityService entityService;
  //...
  // save ItemCollection
  myItemCollection=entityService.save(myItemCollection);
  // get ID from ItemCollection 
  String id=myItemCollection.getItemValueString("$uniqueid");
  // load ItemCollection from database
  myItemCollection=entityService.load(id);

The Imixs EntityService also create TimeStamps to mark the creation and last modified date. These properties are also included in the ItemCollection returned by the save method. The properties are named "$created" and "$modified".

  //...
  // save ItemCollection
  myItemCollection=entityService.save(myItemCollection);
  Date created=myItemCollection.getItemValueDate("$Created");
  Date modified=myItemCollection.getItemValueDate("$Modified");

Query ItemCollection Objects

As the Imixs EntityService stores the org.imixs.workflow.ItemCollection using the Java Persistence API (JPA), it is also possible to use the Java Persitence Query Language (JPQL) so select a collection of ItemCollection objects. In the example before the ItemCollection saved by the Imixs EntityService provides the property "type" with the value "product". With the following example you can select all ItemCollection Objects of this type:

  //...
  String sQuery = "SELECT wi FROM Entity as wi WHERE wi.type='product' ";
  Collection<ItemCollection> col = entityService.findAllEntities(sQuery, 0, -1);
  for (ItemCollection aworkitem : colEntities) {
    //.....
  }

You can also create complex queries to select a subset of ItemCollection objects with specific properties. The following query selects all products with a weight of 500

  SELECT product from Entity AS product
  JOIN product.integerItems AS t
  WHERE product.type='product'
  AND t.itemName = 'weight'
  AND t.itemValue = '500'

See the Query example for more details.

Note:
If you work with the Imixs WorkflowService EJB there is no need to access a workitem through the EntityService EJB. The WorkflowService provides a lot of methods to load a single workitem or a lists of workitems. See the WorkflowService example