svn commit: r1359520 - in /incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub: entityhub-overview.png index.mdtext managedsite.mdtext

[rw...@apache.org]

Author: rwesten
Date: Tue Jul 10 08:33:30 2012
New Revision: 1359520

URL: http://svn.apache.org/viewvc?rev=1359520&view=rev
Log:
updated Entityhub documentation; minor changes to the ManagedSite docu

Added:
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/entityhub-overview.png   (with props)
Modified:
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/index.mdtext
    incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/managedsite.mdtext

Added: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/entityhub-overview.png
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/entityhub-overview.png?rev=1359520&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/entityhub-overview.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/index.mdtext?rev=1359520&r1=1359519&r2=1359520&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/index.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/index.mdtext Tue Jul 10 08:33:30 2012
@@ -1,37 +1,20 @@
 Title: Entityhub
 
-The Entityhub provides two main services. The Entityhub provides the connection to external linked open data sites as well as using indexes of them locally. Its services allow to manage a __network of sites__ to consume entity information and to __manage entities locally__.  
+The Entityhub is the Stanbol component responsible for providing the information about Entities relevant to the users domain. The following figure tries to provide an overview about the features of the Entityhub.
 
-A small index of approx. 43k entities from dbpedia comes with the default installation.
+![Features of the Stanbol Entityhub](entityhub-overview.png)
 
-## Service Endpoints
+The main Features are the:
 
-The RESTful API of the Entityhub ist structured as follows:
+* __Entityhub__ (<code>/entityhub<code>): Allows to manage local entities as well as import entities from Sites or to define mappings from local Entities to Entities managed by Sites. An Apache Stanbol instance can only have a single Entityhub so if you want to manage multiple controlled vocabularies you should preferable use [ManagedSite](managedsite.html) instead.
+* __Site Manager__ (<code>/entityhub/sites</code>): The SiteManager provides a unified access to all currently active Sites - your Entity Network. Requests sent to this endpoint will be forwarded to all currently active Sites. Users should note that queries (requests to the <code>/entityhub/sites/find</code> and <code>/entityhub/sites/query</code> endpoints) might be slow as remote services might need to be called for answering those requests. Retrieval of Entities (requests to the <code>/entityhub/sites/entity</code> endpoint) and also LDpath requests should perform reasonable well.
+* __Sites__ (<code>/entityhub/site/{siteId}</code>): Sites represent entity sources that are integrated with the Stanbol Entityhub. There are two different types of Sites
+    * __ReferencedSite__: This site allows to refer remote services to dereference (Entity id based retrieval) and query entities. It also supports local caches and indexes. A local cache allows to locally store retrieved Entity data to speed-up retrieval on subsequent requests. A local index is a locally available index over all/some of the data of the remote dataset. If such an index is available all requests will be processed using the index. The remote services are only used as a fallback. Local Indexes are created by the Entityhub Indexing tool. The usage scenario [Working with Custom Vocabularies](../customvocabulary.html) provides a good overview on how to use this feature.
+    * __ManagedSite__: [ManagedSites](managedsite.html) allow users to manage their own entity by using the RESTful API of the Entityhub. They are very similar to the <code>/entityhub</code> endpoint but do not allow to manage mappings are to import Entities from other Sites.
 
-### Entity Network ("/entityhub/site*"):
+## RESTful services
 
-- The Referenced Site Manager @ [/entityhub/sites](http://localhost:8080/entityhub/sites) allows to manages sites and retrieve/search Entities in all sites of the Entity Network.
-- A Referenced Site @ /entityhub/site/{siteName} refers to a single site of the Referenced Site Manager and allows to retrieve all active sites. Referenced sites provide the same interface as the referenced site manager.
+The documentation of the RESTful services provided by the Stanbol Entityhub is served by the Web UI of your Stanbol instance. If you do not have a running Stanbol server [this introduction](../tutorial.html) provides you with all necessary information. You can also try to access the documentation on the Stanbol demo server available on the [IKS development server](http://dev.iks-project.eu/) at [http://dev.iks-project.eu:8081/entityhub](http://dev.iks-project.eu:8081/entityhub).
 
- For both services, several features are available:
-
- - [__Referenced__](http://localhost:8080/entityhub/sites/referenced) returns a json array containing the IDs of all available sites. Sites returned by this method can be accessed via the site service endpoint.
-
- - [__Entity__](http://localhost:8080/entityhub/sites/entity) searches all referenced sites for the entity with the parsed URI.
-
- - [__Find__](http://localhost:8080/entityhub/sites/find) provides a label based search service over all sites.
-
- - [__Query__](http://localhost:8080/entityhub/sites/query) allows to parse JSON serialized field queries to the sites endpoint.
-
- Currently active referenced sites at the demo server are available and running for [dbpedia](http://dev.iks-project.eu:8080/entityhub/site/dbpedia/), [dplp](http://dev.iks-project.eu:8080/entityhub/site/dblp/) and [geonames](http://dev.iks-project.eu:8080/entityhub/site/geonames/).
-       
-
-### Entityhub ("/entityhub"):
-
-- Local Entities @/entityhub/entity: Full CRUD operations on Entities managed by the Entityhub
-- Entity Mappings @ /entityhub/mapping: Lookup mappings from local Entities to Entities managed by a Referenced Site
-- Local Search @/entityhub/find: Find locally managed Entities by label based search.
-- Local Query @/entityhub/query: Find locally managed Entities by parsing queries
-- Entity Lookup @/entityhub/lookup: Lookup Entities by id. This supports also to lookup Entities managed by Referenced Sites and the import of found Entities to the Entityhub.
 
 

Modified: incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/managedsite.mdtext
URL: http://svn.apache.org/viewvc/incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/managedsite.mdtext?rev=1359520&r1=1359519&r2=1359520&view=diff
==============================================================================
--- incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/managedsite.mdtext (original)
+++ incubator/stanbol/site/trunk/content/stanbol/docs/trunk/entityhub/managedsite.mdtext Tue Jul 10 08:33:30 2012
@@ -21,12 +21,14 @@ The following Example shows how to uploa
 This example assumes that Stanbol is running on 'localhost' port '8080' and that a ManagedSite with the id 'iptc' was configured. The uploaded file 'subject-code.rdf' contains the IPTC [subject-codes](http://cv.iptc.org/newscodes/subjectcode/). To upload also the vocabulary containing the [genre](http://cv.iptc.org/newscodes/genre/)s one needs to call
 
     :::bash
-    curl -i -X PUT -H "Content-Type: application/rdf+xml" -T genre.rdf "http://localhost:8080/site/iptc/entity"
+    curl -i -X PUT -H "Content-Type: application/rdf+xml" -T genre.rdf \
+        "http://localhost:8080/site/iptc/entity"
 
 Calls like that will create/update all Entities contained in the parsed RDF data. If one wants to ensure that only a single Entity is created/updated one can specify the 'id' parameter.
 
     :::bash
-    curl -i -X PUT -H "Content-Type: application/rdf+xml" -T genre.rdf "http://localhost:8080/site/iptc/entity?id=http://cv.iptc.org/newscodes/genre/Exclusive"
+    curl -i -X PUT -H "Content-Type: application/rdf+xml" -T genre.rdf \
+        "http://localhost:8080/site/iptc/entity?id=http://cv.iptc.org/newscodes/genre/Exclusive"
 
 This will ignore all other RDF data but only update the 'genre:Exclusive' entity.
 
@@ -51,7 +53,7 @@ The above figure shows a typical SolrYar
 
 * __ID__: This MUST BE unique to all other Yards. It is recommended to use "{siteId}Yard".
 * __Solr Index/Core__: This is the name of the SolrCore that will be used to store the data. Here it is recommended to use the same name as the {siteId}. This is because the RESTful API of the SolrCore is published under <code>http://{stanbol-instance}/solr/default/{solrCore}</code>. So using the same name as {siteId} and {solrCore} makes it easier for map the RESTful API of the SolrCore with the ManagedSite published under <code>http://{stanbol-instance}/entityhub/stite/{siteId}</code>.
-* __Use default SolrCore configuration__: If enabled the SolrCore will be automatically created by using the default configuration. Users will typically want to use this option. Only users that want to use a special SolrCore configuration will need to deactivate this option and to provide a <code>{solrCore}.solrindex.zip</code> archive containing the special configuration in the <code>{stanbol-workingdir}/stanbol/datafiles</code> directory. See the[Managing Solr Indexes](../utils/commons-solr.html#managingsolrindexes) section for detailed information. 
+* __Use default SolrCore configuration__: If enabled the SolrCore will be automatically created by using the default configuration. Users will typically want to use this option. Only users that want to use a special SolrCore configuration will need to deactivate this option and to provide a <code>{solrCore}.solrindex.zip</code> archive containing the special configuration in the <code>{stanbol-workingdir}/stanbol/datafiles</code> directory. See the[Managing Solr Indexes](../utils/commons-solr.html#managing-solr-indexes) section for detailed information. 
 
 #### Configuration of a ClerezzaYard: