Skip to content

Commit

Permalink
docu
Browse files Browse the repository at this point in the history
  • Loading branch information
@rsoika
rsoika committed Dec 10, 2024
1 parent 68e52d2 commit b73a62d
Show file tree
Hide file tree
Showing 16 changed files with 376 additions and 368 deletions.
40 changes: 20 additions & 20 deletions src/site/markdown/engine/adminp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,29 +92,29 @@ The following fields part of the Job description are defined by the AdminP servi
A JobHandler may throw a AdminPException if something went wrong. See the following example of a JobHandler implementation:

```java
public class JobHandlerDemo implements JobHandler {
@Inject
DocumentService documentService;

@Override
public ItemCollection run(ItemCollection adminp) throws AdminPException {
// find documents...
List<ItemCollection> result=documentService.fine("type:'workitem'",0,100);
// do something...
try {
....
} catch (Exception e) {
// throw exception if something went wrong
throw new AdminPException("ERROR", "Error...", e);
}
public class JobHandlerDemo implements JobHandler {
@Inject
DocumentService documentService;

@Override
public ItemCollection run(ItemCollection adminp) throws AdminPException {
// find documents...
List<ItemCollection> result=documentService.fine("type:'workitem'",0,100);
// do something...
try {
....
// more work to do?
if (... more work ...) {
adminp.replaceItemValue(JobHandler.ISCOMPLETED, true);
}
return adminp;
} catch (Exception e) {
// throw exception if something went wrong
throw new AdminPException("ERROR", "Error...", e);
}
....
// more work to do?
if (... more work ...) {
adminp.replaceItemValue(JobHandler.ISCOMPLETED, true);
}
return adminp;
}
}
```

To start the JobHandler via the AdminP Service interface the attribute 'job' must be set to the class name of the CDI Bean.
Expand Down
17 changes: 10 additions & 7 deletions src/site/markdown/engine/configsource.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,21 @@ If the same property is defined in multiple ConfigSources, based on the ordinal

Each individual property can be injected directly. The injected value is static and the value is fixed on application starting.

@Inject @ConfigProperty(name="lucence.indexDir")
String lucenePath;
```java
@Inject @ConfigProperty(name="lucence.indexDir")
String lucenePath;
```

### Config Object Injection

The config object can also be injected. With this object you can use the getValue() method to retrieve an individual property at runtime.

@Inject Config config;
...
String lucenePath = config.getValue("lucence.indexDir", String.class);
....

```java
@Inject Config config;
...
String lucenePath = config.getValue("lucence.indexDir", String.class);
....
```

## Deployment:

Expand Down
147 changes: 73 additions & 74 deletions src/site/markdown/engine/documentservice.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,33 +10,33 @@ A Document in the Imixs-Workflow systems is represented by the [ItemCollection c
The following example shows how an instance of an ItemCollection can be saved using the _DocumentService_:

```java
@Inject
DocumentService documentService;
//...
ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument.setItemValue("weight",new Integer(500));
// save ItemCollection
myDocument=documentService.save(myDocument);
@Inject
DocumentService documentService;
//...

ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument.setItemValue("weight",new Integer(500));

// save ItemCollection
myDocument=documentService.save(myDocument);
```

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

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

```java
@Inject
DocumentService documentService;
//...
// save document
myDocument=documentService.save(myDocument);
// get ID from ItemCollection
String id=myDocument.getUniqueID();
// load the document from database
myDocument=documentService.load(id);
@Inject
DocumentService documentService;
//...
// save document
myDocument=documentService.save(myDocument);
// get ID from ItemCollection
String id=myDocument.getUniqueID();
// load the document from database
myDocument=documentService.load(id);
```

__Note:__ The method load() checks if the CallerPrincipal has read access to a document. If not, the method returns null. The method doesn't throw an AccessDeniedException if the user is not allowed to read the document. This is to prevent an aggressor with informations about the existence of that specific document.
Expand All @@ -45,28 +45,27 @@ __Note:__ The method load() checks if the CallerPrincipal has read access to a d

A document is categorized by the item 'type'. The type attribute can be used to group document or select documents by its type.


ItemCollection myDocument=new ItemCollection;
myDocument.settemValue("type","product");
....
// save ItemCollection
myDocument=documentService.save(myDocument);
// select documents by type...
List<ItemCollection> products=documentService.getDocumentsByType("product");

```java
ItemCollection myDocument=new ItemCollection;
myDocument.settemValue("type","product");
....
// save ItemCollection
myDocument=documentService.save(myDocument);

// select documents by type...
List<ItemCollection> products=documentService.getDocumentsByType("product");
```


### Creation and Modified Date

The _DocumentService_ also creates TimeStamps to mark the creation and last modified date of a document. These properties are also part of the document returned by the save method. The items are named "$created" and "$modified".

```java
//...
// save ItemCollection
myDocument=documentService.save(myDocument);
Date created=myDocument.getItemValueDate("$Created");
Date modified=myDocument.getItemValueDate("$Modified");
// save ItemCollection
myDocument=documentService.save(myDocument);
Date created=myDocument.getItemValueDate("$Created");
Date modified=myDocument.getItemValueDate("$Modified");
```

### Immutable Documents
Expand All @@ -85,15 +84,15 @@ The find() method of the _DocumentService_ can be used to query documents by a L
The following example returns all documents starting with the search term 'Imixs':

```java
String serachTerm="(imixs*)";
result=documentService.find(serachTerm);
String serachTerm="(imixs*)";
result=documentService.find(serachTerm);
```

To query for a specific subset of documents, it is also possible to add individual attributes to the search term. The follwoing example will return all documents with the serach term 'imixs' and the Type 'workitem':

```java
String serachTerm="(type:'workitem')(imixs*)";
result=documentService.find(serachTerm);
String serachTerm="(type:'workitem')(imixs*)";
result=documentService.find(serachTerm);
```

See the section [Query Syntax](queries.html) for details about how to search for documents.
Expand All @@ -103,9 +102,9 @@ See the section [Query Syntax](queries.html) for details about how to search for
The _DocumentService_ finder method can also be called by providing a pagesize and a pageindex. With these parameters navigate by pages through a search result. See the following example:

```java
String serachTerm="(imixs*)";
// return only the first 10 documents
result=documentService.find(serachTerm,10,0);
String serachTerm="(imixs*)";
// return only the first 10 documents
result=documentService.find(serachTerm,10,0);
```

Note that the pageindex starts with 0.
Expand All @@ -115,18 +114,18 @@ Note that the pageindex starts with 0.
Per default the search result is sorted by the lucene internal score of each document returned by the index. To sort the documents by a specific attribute a sortItem and a sort direction can be given:

```java
String serachTerm="(imixs*)";
// return only the first 10 documents
// sort by $created descending
result=documentService.findStubs(serachTerm,10,0,'$created',true);
String serachTerm="(imixs*)";
// return only the first 10 documents
// sort by $created descending
result=documentService.findStubs(serachTerm,10,0,'$created',true);
```

### Document Stubs

The Imixs Search Index provides a feature to store parts of a document directly into the index. This feature allows you to search for the so called 'Document Stubs'. A Document stub contains only a subset of Items from the full Document. This search method is much faster and can be used to display a preview of a document in the result-set like you know it from the Internet search.

```java
result = documentService.findStubs(query, 100, 0, '$created' , true);
result = documentService.findStubs(query, 100, 0, '$created' , true);
```

You can later load the full document by the $uniqueid which is part of the document stub.
Expand Down Expand Up @@ -164,22 +163,22 @@ All documents are managed by the Java Persistece API (JPA). The Java Persistence
Additional the _DocumentService_ allows to restrict the read- and write access for a document by providing a [ACL](.acl.html). The items '$readaccess' and '$writeaccess' can be added into a document to restrict the access. The items can provide a list of UserIds or Roles.

```java
@Inject
DocumentService documentService;
//...
ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument.setItemValue("weight",new Integer(500));
// restrict read access to 'bob'
myDocument.setItemValue("$readaccess","bob");
// restrict write access to 'anna'
myDocument.setItemValue("$readaccess","anna");
// save ItemCollection
myDocument=documentService.save(myDocument);
@Inject
DocumentService documentService;
//...

ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument.setItemValue("weight",new Integer(500));

// restrict read access to 'bob'
myDocument.setItemValue("$readaccess","bob");
// restrict write access to 'anna'
myDocument.setItemValue("$readaccess","anna");

// save ItemCollection
myDocument=documentService.save(myDocument);
```

For further details read the [section ACL](./acl.html).
Expand All @@ -200,11 +199,11 @@ Based on CDI Events your can inject custom user groups from your own application
The typically implementation of this mechanism is done by an CDI observer pattern:

```java
public void onUserGroupEvent(@Observes UserGroupEvent userGroupEvent) {
List<String> customGroups = new ArrayList<String>();
customGroups.add("my-group");
userGroupEvent.setGroups(customGroups);
}
public void onUserGroupEvent(@Observes UserGroupEvent userGroupEvent) {
List<String> customGroups = new ArrayList<String>();
customGroups.add("my-group");
userGroupEvent.setGroups(customGroups);
}
```

## The CDI DocumentEvent
Expand All @@ -226,13 +225,13 @@ The class _DocumentEvent_ defines the following event types:
This _DocumentEvent_ can be consumed by another Session Bean or managed bean implementing the @Observes annotation:

```java
@Stateless
public class DocumentServiceListener {
public void onEvent(@Observes DocumentEvent documentEvent){
ItemCollection document=documentEvent.getDocument();
System.out.println("Received DocumentEvent Type = " + documentEvent.getType());
}
@Stateless
public class DocumentServiceListener {
public void onEvent(@Observes DocumentEvent documentEvent){
ItemCollection document=documentEvent.getDocument();
System.out.println("Received DocumentEvent Type = " + documentEvent.getType());
}
}
```

In both event types, an observer client can change the data of the document.
42 changes: 21 additions & 21 deletions src/site/markdown/engine/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,10 @@ Further more, all services are subject to the [Imixs-Workflow Security Model](./
The `WorkflowService` is the core service to create, update and read a process instance. To create a process instance a workitem is assigned to a BPMN 2.0 model definition managed by the `ModelService`.

```java
@Inject
WorkflowService workflowService;
ItemCollection workitem=new ItemCollection().model("1.0.0").task(100).event(10);
workitem=workflowService.processWorkItem(workitem);
@Inject
WorkflowService workflowService;
ItemCollection workitem=new ItemCollection().model("1.0.0").task(100).event(10);
workitem=workflowService.processWorkItem(workitem);
```

Read more about in the section [Imixs WorkflowService](../engine/workflowservice.html).
Expand All @@ -29,18 +29,18 @@ The `DocumentService` is the general persistence layer of the Imixs-Workflow eng
The `DocumentService` is independent from the workflow engine and can not only be used to persist a process instance (`workitem`), but also any other kind of business data, not necessarily associated with the workflow engine (e.g configuration data).

```java
@Inject
DocumentService documentService;
ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument=documentService.save(myDocument);
@Inject
DocumentService documentService;
ItemCollection myDocument=new ItemCollection;
myDocument.setItemValue("type","product");
myDocument.setItemValue("name","coffee");
myDocument=documentService.save(myDocument);
```

The `DocumentService` provides also a [Full-Text-Search](./luceneservice.html). In this way documents can be accessed through a search query:

```java
List<ItemCollection> result=documentService.find("(type:'workitem')(imixs*)");
List<ItemCollection> result=documentService.find("(type:'workitem')(imixs*)");
```

Read more about in the section [DocumentService](../engine/documentservice.html).
Expand All @@ -49,25 +49,25 @@ Read more about in the section [DocumentService](../engine/documentservice.html)
The _ModelService_ provides methods to manage BPMN model definitions. A model can be created with the Eclipse based modeling tool [Imixs-BPMN](../modelling/index.html).

```java
@Inject
ModelService modelService;
InputStream inputStream = new FileInputStream(new File("ticket.bpmn"));
ticketModel = BPMNParser.parseModel(inputStream, "UTF-8");
modelService.addModel(model);
@Inject
ModelService modelService;
InputStream inputStream = new FileInputStream(new File("ticket.bpmn"));
ticketModel = BPMNParser.parseModel(inputStream, "UTF-8");
modelService.addModel(model);
```

The `ModelService` is used internally by the `WorkflowService` but can also be used by your application to navigate through a model definition.

```java
@Inject
ModelService modelService;
Model ticketModel = modelService.getModel("ticket-1.0.0");
List<ItemCollection> tasks = modelService.findAllTasks();
@Inject
ModelService modelService;
Model ticketModel = modelService.getModel("ticket-1.0.0");
List<ItemCollection> tasks = modelService.findAllTasks();
```

Read more about in the section [ModelService](../engine/modelservice.html).

### The ReportService

The _ReportService_ component supports methods to create, find and execute business reports created with the Eclipse based [Imixs-Workflow Modeler](../modelling/index.html). A report is used to generate aggregated information from data objects managed by the `DocumentService`.
The `ReportService` component supports methods to create, find and execute business reports created with the Eclipse based [Imixs-Workflow Modeler](../modelling/index.html). A report is used to generate aggregated information from data objects managed by the `DocumentService`.

Loading

0 comments on commit b73a62d

Please sign in to comment.