Skip to content

Commit

Permalink
docu
Browse files Browse the repository at this point in the history
  • Loading branch information
rsoika committed Dec 10, 2024
1 parent 2c9614d commit 68e52d2
Show file tree
Hide file tree
Showing 14 changed files with 170 additions and 152 deletions.
4 changes: 2 additions & 2 deletions src/site/markdown/core/adapter-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ The Imixs Adapter-API defines the call-back method '_execute_'. This method is c
The Imixs-Workflow Adapter API also supports CDI. In this way an EJB or Resource can be injected into an adapter class by the corresponding CDI annotation. See the following example:

```java
public class DemoAdapter implements org.imixs.workflow.SignalAdapter {
public class DemoAdapter implements SignalAdapter {
// inject services...
@EJB
@Inject
ModelService modelService;
...
@Override
Expand Down
7 changes: 4 additions & 3 deletions src/site/markdown/engine/adminp.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,9 +91,9 @@ 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 {
@EJB
@Inject
DocumentService documentService;

@Override
Expand All @@ -115,8 +115,9 @@ A JobHandler may throw a AdminPException if something went wrong. See the follow
return adminp;
}
}
```

To start the JobHandler via the AdminP Service interface the attriubte 'job' must be set to the class name of the CDI Bean.
To start the JobHandler via the AdminP Service interface the attribute 'job' must be set to the class name of the CDI Bean.


## Initialize an JobHandler via a Rest API call
Expand Down
56 changes: 39 additions & 17 deletions src/site/markdown/engine/documentservice.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@ 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_:

@EJB
org.imixs.workflow.jee.ejb.DocumentService documentService;
```java
@Inject
DocumentService documentService;
//...

ItemCollection myDocument=new ItemCollection;
Expand All @@ -20,24 +21,28 @@ The following example shows how an instance of an ItemCollection can be saved us

// 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:

@EJB
org.imixs.workflow.jee.ejb.DocumentService documentService;
```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);

```

__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.

### The Document Type

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


Expand All @@ -53,13 +58,16 @@ A document is categorized by the item 'type'. The type attribute can be used to


### 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");
```

### Immutable Documents

Expand All @@ -76,60 +84,67 @@ 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);
```

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);
```

See the section [Query Syntax](queries.html) for details about how to search for documents.



### Pagination
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);
```

Note that the pageindex starts with 0.

### Sorting

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);

```

### 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);
```

You can later load the full document by the $uniqueid which is part of the document stub.

### Count Total Hits
### Count Total Hits

The method *count(String)* can be used to compute the total hits of a specific serach term. The method expects the same search term as for the find() method but returns only the count of documents. The method counts only ItemCollections which are accessible by the CallerPrincipal.

### Count Total Pages

The method *countPages(String,int)* can be used to compute the total pages of a specific search term by a given page size. The method expects the same search term as for the find() method but returns only the count of documents. The method counts only ItemCollections which are accessible by the CallerPrincipal.


### Ignore Index

The DocumentService adds a document automatically into the Lucene search index. This default behavior can be deactivated on document level. To skip a document from indexing the item '$noindex' can be set to 'true'. In this case the document will not be added/updated in the lucene index. If the document is already indexed it will be removed from the index.







## Query Documents

Expand All @@ -148,8 +163,9 @@ All documents are managed by the Java Persistece API (JPA). The Java Persistence
## The Access Control List of a Document
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.

@EJB
org.imixs.workflow.jee.ejb.DocumentService documentService;
```java
@Inject
DocumentService documentService;
//...

ItemCollection myDocument=new ItemCollection;
Expand All @@ -164,6 +180,7 @@ Additional the _DocumentService_ allows to restrict the read- and write access f

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

For further details read the [section ACL](./acl.html).

Expand All @@ -182,19 +199,22 @@ 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);
}

```

## The CDI DocumentEvent

The DocumentService EJB provides an Observer Pattern based on CDI Events. The events are fired when a document is loaded or saved.
The Event is defined by the class:

```java
org.imixs.workflow.engine.DocumentEvent
```

The class _DocumentEvent_ defines the following event types:

Expand All @@ -205,12 +225,14 @@ 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());
}
}
```

In both event types, an observer client can change the data of the document.
68 changes: 0 additions & 68 deletions src/site/markdown/engine/entityservice.md

This file was deleted.

37 changes: 21 additions & 16 deletions src/site/markdown/engine/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,56 +13,61 @@ Further more, all services are subject to the [Imixs-Workflow Security Model](./


### The WorkflowService
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_.
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`.

@EJB
```java
@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).

### The DocumentService
The _DocumentService_ is the general persistence layer of the Imixs-Workflow engine and provides an interface to store, load and query data objects (_Documents_) within a database.
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).
The `DocumentService` is the general persistence layer of the Imixs-Workflow engine and provides an interface to store, load and query data objects (`Documents`) within a database.
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).

@EJB
```java
@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:
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*)");

```

Read more about in the section [DocumentService](../engine/documentservice.html).



### The ModelService
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).

@EJB
```java
@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.
The `ModelService` is used internally by the `WorkflowService` but can also be used by your application to navigate through a model definition.

@EJB
```java
@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 68e52d2

Please sign in to comment.