docu, refactoring

issue imixs#346

imixs-workflow-jax-rs/src/main/java/org/imixs/workflow/jaxrs/DocumentRestService.java

@@ -58,6 +58,7 @@
 import org.imixs.workflow.ItemCollection;
 import org.imixs.workflow.WorkflowKernel;
 import org.imixs.workflow.engine.DocumentService;
+import org.imixs.workflow.engine.lucene.LuceneSearchService;
 import org.imixs.workflow.engine.lucene.LuceneUpdateService;
 import org.imixs.workflow.exceptions.AccessDeniedException;
 import org.imixs.workflow.exceptions.InvalidAccessException;
@@ -89,6 +90,23 @@ public class DocumentRestService {
 
 	private static Logger logger = Logger.getLogger(DocumentRestService.class.getName());
 
+	@GET
+	@Produces(MediaType.APPLICATION_XHTML_XML)
+	@Path("/")
+	public StreamingOutput getRoot() {
+
+		return new StreamingOutput() {
+			public void write(OutputStream out) throws IOException, WebApplicationException {
+
+				out.write("<div class=\"root\">".getBytes());
+				out.write("<a href=\"/{uniqueid}\" type=\"application/xml\" rel=\"{uniqueid}\"/>".getBytes());
+
+				out.write("</div>".getBytes());
+			}
+		};
+
+	}
+
 	@GET
 	@Produces("text/html")
 	@Path("/help")
@@ -175,6 +193,35 @@ public DocumentCollection findDocumentsByQuery(@PathParam("query") String query,
 		return new DocumentCollection();
 	}
 
+	/**
+	 * Returns a resultset for a JPQL statement
+	 * 
+	 * @param query
+	 * @param pageSize
+	 * @param pageIndex
+	 * @param items
+	 * @return
+	 */
+	@GET
+	@Path("/jpql/{query}")
+	public DocumentCollection findDocumentsByJPQL(@PathParam("query") String query,
+			@DefaultValue("" + LuceneSearchService.DEFAULT_PAGE_SIZE) @QueryParam("pageSize") int pageSize,
+			@DefaultValue("0") @QueryParam("pageIndex") int pageIndex, @QueryParam("items") String items) {
+		Collection<ItemCollection> col = null;
+		try {
+			// decode query...
+			String decodedQuery = URLDecoder.decode(query, "UTF-8");
+			// compute first result....
+			int firstResult = pageIndex * pageSize;
+
+			col = documentService.getDocumentsByQuery(decodedQuery, firstResult, pageSize);
+			return XMLItemCollectionAdapter.putCollection(col, getItemList(items));
+		} catch (Exception e) {
+			e.printStackTrace();
+		}
+		return new DocumentCollection();
+	}
+
 	/**
 	 * Returns a total hits for a lucene Search Query
 	 * 
@@ -243,6 +290,7 @@ public XMLCount countTotalPagesByQuery(@PathParam("query") String query,
 	 * @return
 	 */
 	@POST
+	@PUT
 	@Path("/")
 	@Produces(MediaType.APPLICATION_XML)
 	@Consumes({ MediaType.APPLICATION_XML, MediaType.TEXT_XML })

src/site/markdown/engine/documentservice.md

@@ -54,7 +54,7 @@ A document can be marked as immutable with the flag
 
 In this case the document will be protected from further changes. The flag can not be removed once the document was created or updated with this flag. Though deleting a document with the immutable flag is allowed. 
 
-## Query Documents
+## Search Documents
 
 The _DocumentService_ provides a [Lucene Index](https://lucene.apache.org/) to query documents by an individual search query. A document is automatically added into the index when the document is saved. 
 The find() method of the _DocumentService_ can be used to query documents by a Lucene search term. 
@@ -103,6 +103,25 @@ The method *countPages(String,int)* can be used to compute the total pages of a
 ### 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 
+
+All documents are managed by the Java Persistece API (JPA). The Java Persistence Query Language (JPQL) can be used to select documents by the Document entity schema independent from the existence of the Lucene search index. The following example selects all documents from the type='workitem': 
+
+	SELECT document FROM Document AS document 
+	WHERE document.type='workitem' 
+
+ JPQL can be used to sort documents by one of the attributes 'id', 'type', 'modified' or 'created'. These are the attributtes of the Document Entity Bean. The following example sorts the result by the creation date:
+
+	SELECT document FROM Document AS document 
+	WHERE document.type='workitem' 
+	ORDER BY document.created DESC
+
+
 ## 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. 
 

src/site/markdown/restapi/documentservice.md

@@ -1,61 +1,97 @@
 # The Document Service
-The resource _/documents_ provides methods to read, create and modify documents through the Imixs-Rest API.
+The resource _/documents_ provides methods to read, create and modify documents.
 
+Imixs-Workflow controls the access for each document by individual access list. The result of a GET request will return only documents which are not read protected or the current user has sufficient read access. 
+A POST/PUT request will be rejected if the current user has insufficient write access.
+See the section [ACL](../engine/acl.html) for details.  
 
 ## GET Document
-The GET method is used to read a document resource:
+The GET method can be used to read a single document resource by its UniqueID:
 
 
 | URI                     | Method | Description                                                        | 
-|-------------------------|--------|------------------------------------------------------------|
-| /{uniqueid}             | GET    | returns a single document defined by $uniqueid                     |
+|-------------------------|--------|--------------------------------------------------------------------|
+| /{uniqueid}             | GET    | returns a single document resource defined by its $uniqueid        |
+
+**Example:**
+
+	/rest-service/documents/ed8ad2c7-f460-113d-a9b5-bb71bf61cf09
+
+## GET Document Collection
+The sub-resource _/search/_ can be used to search for a set of documents using the [search index](../engine/luceneservice.html):
+
+
+| URI                     | Method | Description                                                        | 
+|-------------------------|--------|--------------------------------------------------------------------|
+| /search/{query}         | GET    | Returns a result set of documents by a lucene search query         |
+
+
+**Example:**
+
+	/rest-service/documents/search/type:"workitem"
+
 
-## GET Documents by a Search Phrase 
-The GET method is used to read and search for a document resource or a set of documents:
 
 ### Resource Options
 With the following optional URI parameters the GET request can be filtered and sorted:
 
 | option      | description                       | example             		|
 |-------------|---------------- ------------------|-----------------------------|
-| pagesize    | number of documents returned      | ..?pagesize=10           	|
-| pageindex   | page index to start               | ..?pageindex=5&pagesize=10  |
+| pageSize    | number of documents returned      | ..?pagesize=10           	|
+| pageIndex   | page index to start               | ..?pageindex=5&pagesize=10  |
 | sortBy	  | sort item 					      | ..&sortBy=txtworkflowstatus |
 | sortReverse | sort direction (ascending/descending)   | ..&sourtReverse=true		|
 
+
+**Example:**
+
+	/rest-service/documents/search/type:"workitem"?pageSize=10&pageIndex=2
+
 See details about the search in the section [Search Index](../engine/luceneservice.html).
 
-## GET Documents by JPQL
-Optional the  resource _/documents_ provides the sub-resource _/jpql_ to select a set of documents  selected by a JPQL statement:
+
+
+### Count documents
+
+With the _sub-resouces_ '/count/' and '/countpages/' the result size can be requested:
+
+| URI                     | Method | Description                                                        | 
+|-------------------------|--------|--------------------------------------------------------------------|
+| /count/{query}    | GET    | the total hits of lucene search query                        		    |
+| /countpages/{query}?pagesize= | GET    | the total pages of lucene search query for a given page size |
+
+
+
+
+
+### GET Documents by Java Persistence Query Language
+Optional the  resource _/documents_ provides the sub-resource _/jpql_ to select a set of documents using the Java Persistence Query Language (JPQL). JPQL can be used to select documents independent from the existence of the Lucene search index.
 
 
 | URI                     | Method | Description                                                | 
 |-------------------------|--------|------------------------------------------------------------|
 | /jpql/{query}           | GET    | Returns a result set of documents by a JQPL statement      |
 
 
-### Resource Options
-With the following optional URI parameters a sub result can be selected:
 
-| option      | description                             | example               |
-|-------------|---------------- ------------------------|-----------------------|
-| firstResult | 1st element of the query to be returned | ..?firstResult=10     |
-| maxResult   | maximum number of documents returned    | ..?maxResult=5  		|
-
+Example:
+
+	/rest-service/documents/jpql/SELECT document FROM Document AS document WHERE document.type='workitem'
 
 See the [Document Service](../engine/documentservice.html) for details.
 
 
 
 
-## POST/DELETE a Document
-The methods PUT, POST and DELETE allow to create, modify and delete a document:
+## POST/PUT/DELETE a Document
+The methods POST, PUT and DELETE allow to create, modify and delete a document:
 
 
-| URI          | Method      | Description                               | 
-|--------------|-------------|------------|
-| /            | POST, PUT   | posts a document to be stored by the  DocumentService. The post data can be x-www-form-urlencoded or in xml format   |
-| /{uniqueid}  | POST, DELETE | updates ore deletes a document  |
+| URI          | Method | Description                              | 
+|--------------|--------|------------|-----------------------------|
+| /            | POST   | posts a new document to be stored by the  DocumentService. The post data can be x-www-form-urlencoded or in xml format   |
+| /{uniqueid}  | PUT	| updates  a document. The post data can be x-www-form-urlencoded or in xml format  					|
+| /{uniqueid}  | DELETE | deletes a document  						|
 
 
 
@@ -72,9 +108,5 @@ The Document Rest Service provides resource URIs for administrative purpose. To
 
 
 
-## The Access Control 
-
-
-Imixs-Workflow controls the access for each document by individual access lists see the section [ACL](../engine/acl.html). The result of a GET request will return only documents which are not read protected or the current user has sufficient read access.