Author: enridaga
Date: Mon Feb 13 09:41:50 2012
New Revision: 1243454
URL: http://svn.apache.org/viewvc?rev=1243454&view=rev
Log:
Minor updates to the README file (STANBOL-462)
Modified:
incubator/stanbol/trunk/reasoners/README.md
Modified: incubator/stanbol/trunk/reasoners/README.md
URL:
http://svn.apache.org/viewvc/incubator/stanbol/trunk/reasoners/README.md?rev=1243454&r1=1243453&r2=1243454&view=diff
==============================================================================
--- incubator/stanbol/trunk/reasoners/README.md (original)
+++ incubator/stanbol/trunk/reasoners/README.md Mon Feb 13 09:41:50 2012
@@ -61,6 +61,8 @@ Tasks description:
This is how the endpoint behave:
+Foreground operations
+---------------------
GET (same if POST and Content-type: application/x-www-form-urlencoded)
params:
* url // Loads the input from url
@@ -83,67 +85,86 @@ Supported output formats:
Supported return formats are all classic RDF types (n3,turtle,rdf+xml) and
HTML.
For HTML the returned statements are provided in Turtle (Jena) or OWL
Manchester syntax (OWLApi), wrapped in the stanbol layout. It would be nice to
have all in the latter, which is very much readable (todo).
-Recently added
-=============
+Long term operations
+--------------------
+To run a task as background job, you can use the same interface described
above, appending 'job' to the resource path.
+For example:
+$ curl
"http://localhost:8080/reasoners/owl2/classify/job?url=http://xmlns.com/foaf/0.1/";
-* Support for long-term operations.
+Notes (to be known)
+=============
+Differences between Jena and OWLApi services:
+* CHECK have different meaning with respect to the reasoning service
implementation
-Todo
+More examples
=============
+### Basic GET calls to the reasoning services.
+#### Send a URL and the service will return the inferred triples
+##### Classify the FOAF ontology, getting it from the web using the Jena OWL
reasoner, result in turtle
+curl -v -H "Accept: application/turtle"
"http://localhost:8080/reasoners/owl/classify?url=http://xmlns.com/foaf/0.1/";
-* Support for return types json and json-ld (need to write jersey writers)
-* The front service actually returns only inferred statements. It is useful
also to have the complete set of input+inferred statements
-* Decouple input preparation from the rest endpoint resource, creating
something like an InputProvider SCR api; each InputProvider is bound to a set
of additional parameters.
-This have several benefits:
-** Remove of additional optional parameters, bound to specific input sources
from the default rest api (ex, session, scope, recipe)
-** Remove dependencies to ontonet, rules and other modules which are not
needed for standard usage. They could be implemented as InputProvider/s, bound
to specific parameters.
-** Allow the addition of other input sources (for example 'graph', 'entity' or
'site')
-* Implement a Custom Jena ReasoningService, to use a Jena rules file or a
stanbol recipe (when implemented the toJena() functionality in the rules
module) from configuration. This could be done as multiple SCR instance, as it
is now for entityhub sites, for example.
-* Provide a validation report in case of task CHECK (validity check).
-* Implement a progress monitor, relying on the jena and owlapi apis, which
have this feature, for debugging purpose
-* Implement a benchmark endpoint, relying on OWL manchester syntax, to setup
benchmark tests in the style of the one made for the enhancer
-* Implementing owllink client reasoning service
-* Implement additional data preparation steps, for example to implement a
"consistent refactoring" task. For example, giving a parameter
'refactor=<recipe-id>' the service could refactor the graph before execute the
task.
-* Implement off the shelf reasoning services (for example, targeted to resolve
only owl:sameAs links)
+##### Classify the FOAF ontology, getting it from the web using the Jena OWL
reasoner, result in n3
+ curl -v -H "Accept: text/n3"
"http://localhost:8080/reasoners/owl/classify?url=http://xmlns.com/foaf/0.1/";
-General issues
-=============
-The main problem is performance, which decrease while the input data grows, in
some cases dramatically. This could be faced (IMHO), in two directions:
-* Improve input preparation. In particular, the preparation of input form
ontonet scope/session needs to stream the ontologies, in cases of more input
(url provided) twice!, and this have some drawback on performance.
-* Support long-term operations, to start the process from the REST call and
then ping it's process through a dedicated endpoint
+##### Enrich the FOAF ontology, getting it from the web using the Jena RDFS
reasoner, run as background job
-Notes (to be known)
-=============
-Differences between Jena and OWLApi services:
-* CHECK have different meaning with respect to the reasoning service
implementation
+ curl -v
"http://localhost:8080/reasoners/owl/classify/job?url=http://xmlns.com/foaf/0.1/";
+this will return a 201 Created response, with the Location header pointing to
the Job url:
+ \> GET /reasoners/owl/classify/job?url=http://xmlns.com/foaf/0.1/
HTTP/1.1
+ \> User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7
OpenSSL/0.9.8r zlib/1.2.3
+ \> Host: localhost:8080
+ \> Accept: \*/\*
+ \>
+ \< HTTP/1.1 201 Created
+ \< Location: http://localhost:8080/jobs/Z63Clmt49yekaYIgXk8vmw
+ \< Content-Type: text/html
+ \< Transfer-Encoding: chunked
+ \< Server: Jetty(6.1.x)
+ \<
+
+then, ping the job at the given location, in our example:
-Examples
-=============
-#
-# Basic GET calls to the reasoning services.
-# Send a URL and the service will return the inferred triples
-#
-# Classify the FOAF ontology, getting it from the web using the Jena OWL
reasoner, result in turtle
-curl -v -H "Accept: application/turtle"
"http://localhost:8080/reasoners/owl/classify?url=http://xmlns.com/foaf/0.1/";
+ curl -v http://localhost:8080/jobs/Z63Clmt49yekaYIgXk8vmw
+
+response is:
+
+ \< HTTP/1.1 200 OK
+ \< Content-Length: 169
+ \< Content-Type: application/json
+ \< Server: Jetty(6.1.x)
+ \<
+ {
+ "status": "finished",
+ "outputLocation":
"http://localhost:8080/reasoners/jobs/Z63Clmt49yekaYIgXk8vmw";,
+ "messages": [
+ "You can remove this job using DELETE",
+ ]
+ }
+
+Status cane 'ready' or 'running'. If ready, you can get the output in this
way:
+
+ curl -v -H "Accept: text/n3"
http://localhost:8080/reasoners/jobs/Z63Clmt49yekaYIgXk8vmw
+
+Data will be there until you DELETE the job:
-# Classify the FOAF ontology, getting it from the web using the Jena OWL
reasoner, result in n3
-curl -v -H "Accept: text/n3"
"http://localhost:8080/reasoners/owl/classify?url=http://xmlns.com/foaf/0.1/";
+ curl -X DELETE http://localhost:8080/jobs/Z63Clmt49yekaYIgXk8vmw
-# Enrich the FOAF ontology, getting it from the web using the Jena RDFS
reasoner, result in rdf/xml
-curl -v -H "Accept: application/rdf+xml"
"http://localhost:8080/reasoners/owl/classify?url=http://xmlns.com/foaf/0.1/";
+##### Check consistency of the FOAF ontology, getting it from the web using
the Jena OWL reasoner, result in turtle
-# Check consistency of the FOAF ontology, getting it from the web using the
Jena OWL reasoner, result in turtle
-curl -v
"http://localhost:8080/reasoners/owl/check?url=http://xmlns.com/foaf/0.1/";
+ curl -v
"http://localhost:8080/reasoners/owl/check?url=http://xmlns.com/foaf/0.1/";
-# Check consistency of the FOAF ontology, getting it from the web using the
Hermit OWL2 reasoner, result in turtle
-curl -v
"http://localhost:8080/reasoners/owl2/check?url=http://xmlns.com/foaf/0.1/";
-
-# Trying with an ontology network (large ontology composed by a set of little
ontologies connected through owl:import statements)
-curl -v
"http://localhost:8080/reasoners/owl2/check?url=http://www.cnr.it/ontology/cnr/cnr.owl";
-# or
-curl -v
"http://localhost:8080/reasoners/owl2/enrich?url=http://www.cnr.it/ontology/cnr/cnr.owl";
+##### Check consistency of the FOAF ontology, getting it from the web using
the Hermit OWL2 reasoner, result in turtle
+
+ curl -v
"http://localhost:8080/reasoners/owl2/check?url=http://xmlns.com/foaf/0.1/";
+
+##### Trying with an ontology network (large ontology composed by a set of
little ontologies connected through owl:import statements)
+ curl -v
"http://localhost:8080/reasoners/owl2/check?url=http://www.cnr.it/ontology/cnr/cnr.owl";
+
+ or
+
+ curl -v
"http://localhost:8080/reasoners/owl2/enrich?url=http://www.cnr.it/ontology/cnr/cnr.owl";
#
# POST calls (send a file)
@@ -160,3 +181,23 @@ curl "http://localhost:8080/reasoners/ow
# or, posting a file
curl -X POST -H "Content-type: multipart/form-data" -F file=@foaf.rdf -F
target=example-rdfs-inferences "http://localhost:8080/reasoners/rdfs/enrich";
+
+Todo notes
+=============
+This list includes some notes about improvements that can be done.
+Please refer to Stanbol issue tracker for a concrete workplan.
+* Support for return types json and json-ld (need to write jersey writers)
+* The front service actually returns only inferred statements. It is useful
also to have the complete set of input+inferred statements
+* Decouple input preparation from the rest endpoint resource, creating
something like an InputProvider SCR api; each InputProvider is bound to a set
of additional parameters.
+This have several benefits:
+** Remove of additional optional parameters, bound to specific input sources
from the default rest api (ex, session, scope, recipe)
+** Remove dependencies to ontonet, rules and other modules which are not
needed for standard usage. They could be implemented as InputProvider/s, bound
to specific parameters.
+** Allow the addition of other input sources (for example 'graph', 'entity' or
'site')
+* Implement a Custom Jena ReasoningService, to use a Jena rules file or a
stanbol recipe (when implemented the toJena() functionality in the rules
module) from configuration. This could be done as multiple SCR instance, as it
is now for entityhub sites, for example.
+* Provide a validation report in case of task CHECK (validity check).
+* Implement a progress monitor, relying on the jena and owlapi apis, which
have this feature, for debugging purpose
+* Implement a benchmark endpoint, relying on OWL manchester syntax, to setup
benchmark tests in the style of the one made for the enhancer
+* Implementing owllink client reasoning service
+* Implement additional data preparation steps, for example to implement a
"consistent refactoring" task. For example, giving a parameter
'refactor=<recipe-id>' the service could refactor the graph before execute the
task.
+* Implement off the shelf reasoning services (for example, targeted to resolve
only owl:sameAs links)
+
