How to use CommitableMGraph

CommitableMGaph supports the developer to commit modifications of a graph at once. Therefore if  an error occured during modifcation the changes are not persistent and are rolled back.

We have written an example in org.clerezza.examples project in the package org.clerezza.examples.commit. Download the example from http://scm.trialox.org/examples/

First example is about creating a person requesting http://localhost:8080/examles/commit/create-person. For the sake of convenience it is a GET request to create an agent instead of a POST request. When activating the bundle a graph http://tpf.localhost/example-person.graph is created to store the persons.

To get the graph http://localhost:8080/examples/commit/graph can be requested. 

Copy the following uri into your browser 

http://localhost:8080/examples/commit/create-person?personUri=http://localhost:8080/John.Doe&name=John%20Doe&mbox=john.doe@example.com&age=24

=> A User with name John Doe, mbox john.doe@example.com and age 24 is created

http://localhost:8080/examples/commit/create-person?personUri=http://localhost:8080/Jane.Doe&name=John%20Doe&mbox=jane.doe@examplecom&age=24

=> No user is created. A Bad Request is returned because the email address is not valid (should be  jane.doe@example.com).The validation is implemented in the jaxrs method with path "create-person". If the email address doesn't pass the validation test a Response with status 400 is created.

http://localhost:8080/examples/commit/create-person?personUri=http://localhost:8080/Marco.Mueller&name=Marco%20Doe&mbox=marco.mueller@example.com

=> No user is created. A server error is returned because the query parameter age is not set.

To delete a user the following uri can be entered

http://localhost:8080/examples/commit/delete-person?personUri=http://localhost:8080/John.Doe

=> The user is deleted. Response ok is returned.

http://localhost:8080/examples/commit/person-list

=> lists all users in the graph.

Notice:

Call CommitableMGraph.filter returns a ClosableIterator, which has an additionally method close to "unlock" the graph. Locks must not be set manually with a CommitableMGraph. To iterate the block has to be surrounded by try and ends with finally  (ClosableIterator.close())

Caching

The caching example is in the package org.clerezza.examples.cahce (project org.clerezza.examples). The following example demonstrates how to cache java objects. First a new cache has to be created.The CacheManager service is located in the org.clerezza.cms.cache project.

@Reference
CacheManager cacheManager

To use the cache functionality the abstract class Cachable has to be extended, implementing CachableId, who identifies the Cachable object and implementing the CachableHandler to define when the Cachable object is not feasible/valid any more.

Renderlet Caching

The caching renderlet allows to cache rendering results produced by the clerezza platform typerendering. To cache a rendering result you have to append the "-cache" suffix to the rendering mode used. There can be several option be specified:

• -ignoreRes: When specifying this option, then the rendered resource is not used for identifying the rendering result. As a consequence resources with the same rdf type, rendered with the same mode and media type will return the same cached object.
• -perUser: Specifies that the user will be used to identify the cached object. Therefore with this option set each user will have its own cached object.
• -time [seconds]: Specifies how long the cached object should be kept (default is 30 minutes).

 
A cache object may be used only as long as a underlying condition holds true.  E.g. a blog page should be re-rendered if a new blog entry was made. For this kind of advanced cache handling, you can implement a  RenderingResultHandler and expose it as OSGi service. The CachingRenderlet will bind all handlers and call their isFeasible()-method to determine the feasibility of a cached rendering result.

Example:

{render(context,"menu-cache -ignoreRes -perUser")}

{render(context,"wide-cache")}

Request Handler

Introduction

The RequestHandler is a class provided by the package org.clerezza.utils.jaxrs.requesthandler. which allows the execution of a specified method of a java object triggered by a HTTP request [1], for example a POST request sent over an HTML form. The request handler takes also care of creating an appropriate JAX-RS [2] response. What kind of response is created depends on configuration parameters and the return-value as well as the name of the executed method (this will be explained later).

RequestHandler.handle()

The RequestHandler has a single public method called hanlde which takes two arguments:

1. Target object: The object whose method will be executed. The name of the method is specified in the second parameter "Parameters"
2. Parameters: The parameters containing the name of the method to be executed, the values of the arguments for this method, and further configuration parameters which tells the request handler what to do after the executed method finished (e.g. what to do with the returned object).

 Object

The object argument can be any java object.

Parameters

The parameters are provided by an object that implements the interface HandlerParameter. There is currently one implementation FormParams which extracts the handler parameters from a string of the format: name1=value1&name2=value2 and so on (a list of name value pairs). This is also the format used by html forms.

The following names of the above mentioned name value pairs are supported by the request handler:

• "action" whose value is the name of the method to be invoked.
• "actionArgs" is a string containing a comma-separated list of parameter names whose values will be used as arguments when invoking the action. The parameter values will be used in the same order as arguments as the parameter names are ordered. These parameters have to be also provided over the HandlerParameter object and therefore MUST have different names than the parameters described in this list.
• "useReturnValue" whose value is a boolean which indicates if the return value of the invoked method should be returned or a response code should be sent. Default is set to false.
• "redirectToResource" indicates that a SEE OTHER (303) response should be sent to the location specified by the returned object. The returned object has to be one of URI, UriRef, or GraphNode so that the request handler is able to redirect to it. Additionally the value of "redirectToResource" (which is a string) is used as query parameters for the redirected URL.
• "redirect" is a string indicates that in case of a successful request, ie no exception is thrown by the invoked method, a SEE OTHER (303) to the URL which is the value of "redirect" should be sent as response.

Only one of the three parameters: useReturnValue, redirectToResource, and redirect can be specified at once.

Response Generation

The request handler tries generates an appropriate response (see all possible http responses here [3]) . In the following table you can see what response you can expect:

* A creation prefix is a word that indicates that something was created. Here is the full list of creation prefixes : "assemble", "build", "breed", "clone", "conjure", "constitute", "construct", "copy", "create", "duplicate", "engineer", "erect", "evoke", "fabricate", "generate", "install", "instantiate", "manufacture", "make", "move", "originate", "procreate", "produce", "replaceWith", "reproduce", "setup", "spawn", "summon"

If the invoked method throws a RuntimeException then a SERVER ERROR (500) response will be returned. Only exception is the IllegalArgumentException, which will cause a BAD REQUEST (400) response. If the invoked method throws a checked exception then this will also cause a BAD REQUEST (400) response.

[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5

[2] https://jsr311.dev.java.net/

[3] http://www.w3.org/Protocols/rfc2616/rfc2616.html