svn commit: r1291389 - in /incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager: ontonet/index.mdtext registry/index.mdtext

[al...@apache.org]

Author: alexdma
Date: Mon Feb 20 17:53:24 2012
New Revision: 1291389

URL: http://svn.apache.org/viewvc?rev=1291389&view=rev
Log:
- Code samples and usage scenarios for Registry
- Fixed broken image src in ontonet.

Modified:
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/ontonet/index.mdtext
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/registry/index.mdtext

Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/ontonet/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/ontonet/index.mdtext?rev=1291389&r1=1291388&r2=1291389&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/ontonet/index.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/ontonet/index.mdtext Mon Feb 20 17:53:24 2012
@@ -6,7 +6,7 @@ Stanbol OntoNet implements the API secti
 
   <center>
     <figure>
-      <img width="500px" src="../../../images/ontologymanager/ontonet.png" alt="OntoNet ontology network structure">
+      <img width="500px" src="../../../../images/ontologymanager/ontonet.png" alt="OntoNet ontology network structure">
       <figcaption>Figure 1: an example of OntoNet setup for multiple ontology networks, showing the orthogonal layering of sessions, scopes and spaces.</figcaption>
     <figure>
   </center>

Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/registry/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/registry/index.mdtext?rev=1291389&r1=1291388&r2=1291389&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/registry/index.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/ontologymanager/registry/index.mdtext Mon Feb 20 17:53:24 2012
@@ -9,7 +9,9 @@ Registry management is a facility for St
 
 ## Usage Scenarios
 
-TODO
+Your CMS ca handle hundreds of vocabularies together for semantic annotation, but you do not want to clutter the system runtime by having all those vocabularies loaded altogether. You would like the ontology of a specific vocabulary to be loaded only when someone uses or requests it, and once it is loaded you would like it to be stored internally, rather than fetching it from the Web over and over again.
+
+The Ontology Registry Manager can help you with that. With a simple RDF document that references these hundreds of ontologies, it is possible to organize them into libraries, e.g. by topic ("user profile", "product", "event") or by provenance ("W3C", "Industrial standards", "nonstandard" etc.). If a user decides to annotate a content item using `schema.org`, she can choose to do so and the Registry Manager will automatically figure out that it is referenced by libraries "Industrial standards", "user profile" and "product"). None of these libraries has been preloaded yet, so Stanbol will automatically choose the smallest one, say "Industrial standards", and load it. The `schema.org` ontology will be available from that point on.
 
 ## Configuration
 
@@ -32,11 +34,59 @@ Note that not only can a single registry
 
 ### Access a cached ontology
 
-A cached ontology does not need to be loaded into an OntoNet scope or session in order to be available. It can be accessed at @/ontonet/{ontologyURI} .
+A cached ontology does not need to be loaded into an OntoNet scope or session in order to be available. It can be accessed at `@/ontonet/{ontologyURI}`, where `{ontologyURI}` can be either the ontology ID, if the ontology is named, of the physical URI it was retrieved from.
+
+### Load a library into OntoNet
+
+One useful application of ontology libraries is that they can be used to populate an OntoNet ontology collector (space or session) with multiple ontologies with a single command. There are two ways to do so.
+
+#### Java API
+
+The Registry Manager is an OSGi service component. To obtain the service reference:
+
+    @Reference
+    RegistryManager registryManager;
+
+Loading the contents of a library into an ontology collector is done in the same way as with loading single ontologies, i.e. by creating a suitable `OntologyInputSource`. This time, though, it is a special input source called `LibrarySource`. A `LibrarySource` creates a new blank ontology (or uses an existing one upon request) and appends all the contents of a library to it via `owl:imports` statements.
+
+Suppose we want to load the contents of a library called `http://stanbol.apache.org/ontologies/library/W3C_ontologies` into a scope called `AnnotationStandards` that already exists (so we'll have to use its custom space). First of all let us get a hold of the space:
+
+    @Reference
+    ONManager onManager;
+    
+    OntologyScope scope = onManager.getScopeRegistry().getScope("AnnotationStandards");
+    OntologySpace space = scope.getCustomSpace();
+
+Now create the `LibrarySource`:
+
+    IRI libraryID = IRI.create("http://stanbol.apache.org/ontologies/library/W3C_ontologies");
+    OntologyInputSource<?,?> libSrc = new LibrarySource(libraryID, registryManager);
+
+Note that all `LibrarySource` constructors require that a `RegistryManager` be passed to them. This is because ontology input sources in general are not OSGi components and cannot trade service references.
+
+Also note that building a `LibrarySource` will cause the contents of the corresponding library to be loaded and stored into the ontology manager, assuming the _lazy loading policy_ option is set and the library had not been loaded earlier. Creating library sources is one way to "touch" an ontology library and get the Registry Manager to load it.
+
+Finally, add the input source to the custom space. Simple as that:
+
+    space.addOntology(libSrc);
+
+Note that we called `addOntology()` although this resulted in adding multiple ontologies. This is because a `LibrarySource` "fools" OntoNet into thinking a single ontology is being loaded, i.e. the _root_ ontology that depends on the library contents. It will still possible to access a single imported ontology, though.
+
+#### REST API
+
+When using the REST API, an ontology library can be loaded into a scope the very moment the scope is created.
+
+To load the contents of library `http://stanbol.apache.org/ontologies/library/W3C_ontologies` into a _new_ scope called `AnnotationStandards`:
+
+    curl -X PUT http://localhost:8080/ontonet/ontology/AnnotationStandards?corereg=http://stanbol.apache.org/ontologies/library/W3C_ontologies
+
+### Load selected ontologies from library
+
+We are working on that. Stay tuned.
 
 ### Service Endpoints
 
-Because the configuration of registries is a task for __administrators__ and is performed through the Felix administration console, there are no RESTful services for modifying ontology registries. It is however possible to browse the known ontology libraries.
+Because the configuration of registries is a task for __administrators__ and is performed through the Felix administration console, there are no RESTful services for modifying ontology registries. It is however possible to browse the known ontology _libraries_.
 
 - [__Libraries__](http://localhost:8080/ontonet/registry). If called from a Web browser, shows a list of known ontology libraries, and for each of them the caching state and the number of referenced ontologies. _Note that this service does not provide information on the registries that describe these libraries; that is classified information for administrators._ This endpoint supports only GET with no parameters, and generates text/html only.