You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@stanbol.apache.org by bu...@apache.org on 2012/07/16 15:02:48 UTC
svn commit: r825985 [9/12] - in /websites/staging/stanbol/trunk/content: ./
stanbol/docs/trunk/ stanbol/docs/trunk/cmsadapter/
stanbol/docs/trunk/components/ stanbol/docs/trunk/components/cmsadapter/
stanbol/docs/trunk/components/contenthub/ stanbol/do...
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/entityhubandlinkeddata.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/entityhubandlinkeddata.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/entityhubandlinkeddata.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,317 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - </title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+ <div id="content">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/entityhub/">Entityhub</a>
+ </div>
+ <h1 class="title"></h1>
+ <h1 id="adopting-linked-media-principles-for-stanbol-entityhub">Adopting Linked Media principles for Stanbol Entityhub</h1>
+<p><a href="http://linkeddata.org/">Linked Data</a> describes the idea of linking - formally unconnected - bits of data over the web. Think about how hyperlinks are used to navigate within the Web of documents. Linked data tries to do the same for the Web of Data. This basic idea is also central to most of the Apache Stanbol Components. However Stanbol is not only concerned about about linking data but also with interlinking the web of documents with the web of data. Therefore <a href="http://lists.w3.org/Archives/Public/public-lod/2011May/0019.html">this proposal</a> to extend Linked Data principles to also support content and not just data seams like a natural fit for Apache Stanbol.</p>
+<p>This Documents first provides a short introduction to Linked Data and the proposed Linked Media extensions. The second part of the document analysis requirements of the Stanbol Entityhub related to Linked Data and Linked Media. The third section goes than into more details on how Linked Media principles could be implemented by Entityhub.</p>
+<h2 id="short-introduction-to-linked-data-and-proposed-linked-media-extensions">Short Introduction to Linked Data and proposed Linked Media extensions</h2>
+<p>from <a href="http://linkeddata.org/faq">linkeddata.org</a> </p>
+<blockquote>
+<h3 id="what-is-linked-data">What is Linked Data?</h3>
+<p>The Web enables us to link related documents. Similarly it enables us to link related data.
+The term Linked Data refers to a set of best practices for publishing and connecting structured data on the Web.
+Key technologies that support Linked Data are URIs (a generic means to identify entities or
+concepts in the world), HTTP (a simple yet universal mechanism for retrieving resources,
+or descriptions of resources), and RDF (a generic graph-based data model with which to
+structure and link data that describes things in the world).</p>
+</blockquote>
+<p>The following terminology is often used with with Linked Data:</p>
+<ul>
+<li>Resources: All items of interest that are to be published on the Web.</li>
+<li>Information Resources: All documents on the Web (test, imaged, videos ...)</li>
+<li>Non-Information Resources: Real-word-objects that exist outside of the Web (Persons, Organizations, Places ...) but also social concepts (Categories, Terminologies â¦).</li>
+<li>Resource Identifiers: Linked Data recommends to only use HTTP URIs as identifiers because this allows to directly accessing information about the resource over the web.</li>
+<li>Representation: A stream of bytes in a certain format that describes an Information Resource. Representations can be available in different formats.</li>
+<li>Dereferencing of HTTP URIs: For Information Resources the content is directly returned. For Non-Information Resources the HTTP status "303 See Other" with a link to the Information Resource describing the Non-Information resource is returned.</li>
+<li>Content Negotiation: Users can select the format (content type) of the returned Representations by setting the "Accept" header in requests. Linked data recommends to use different URIs for Representations of different content type to allow Bookmarking. The parsed "Accept" header is therefore used to decide about the URI parsed with an "303 See Other" response.</li>
+<li>URI Aliases: If different providers publish information about the same Non-Information Resource (e.g a famous Person, a Country, ...) than "<a href="http://www.w3.org/TR/owl-ref/#sameAs-def">owl:sameAs</a>" relations are used to tell clients that two different Resource Identifiers (HTTP URIs) identify the same Resource.</li>
+</ul>
+<p>A more detailed overview is provided by the <a href="http://www4.wiwiss.fu-berlin.de/bizer/pub/LinkedDataTutorial/">Linked Data Tutorial</a>.</p>
+<h3 id="linked-media">Linked Media</h3>
+<p>The <a href="http://lists.w3.org/Archives/Public/public-lod/2011May/0019.html">Linked Media proposal</a> tries to extend Linked Data by two features.</p>
+<ol>
+<li>Creating and updating of resources: Linked data currently covers only retrieval of information, which is sufficient for sites like <a href="http://dbpedia.org">DBpedia</a> or <a href="http://www.geonames.org">Geonames</a> where users are only able to consume data. When creating interactive (web) applications one needs to be able to create/update and remove information. Features that are currently not covered by linked data, but well defined for RESTful Services. The Linked Media proposal therefore suggest to use HTTP PUT, POST and DELETE request for this purpose.</li>
+<li>Handling both content and metadata: Linked Data uses Content Negotiation to select suitable content types. In addition it provides means to redirect to Information Resources about Non-Information Resources. However linked data does not differentiate between metadata and content. One can not explicitly ask first for an GIF Image and later for the metadata as RDF. Or first for an HTML blog post and later for its metadata formatted as HTML. Such a differentiation is only supported for Non-Information Resources. E.g. for a famous painting (Non-Information Resource) and a photo (Information Resource). Liked Media proposes to use the "rel" parameter of the Accept header to allow users to explicitly ask for content ("Accept: type/subtype; rel=content") or metadata ("Accept: type/subtype; rel=meta").</li>
+</ol>
+<p>For a more detailed description please follow the link to the <a href="http://lists.w3.org/Archives/Public/public-lod/2011May/0019.html">Linked Media proposal</a> [1] as posted by by Sebastian Schaffert on the linked open data mailing list of W3C. You might also be interested in reading the following discussion. Note also <a href="http://code.google.com/p/kiwi/source/browse/kiwi-core/src/main/java/kiwi/core/webservices/resource/ResourceWebService.java">ResourceWebService</a> [2] a first implementation of the Linked Media proposal based on the <a href="http://code.google.com/p/kiwi/">Kiwi2/Linked Media Framework</a> [3][4].<br />
+</p>
+<h2 id="requirements-of-the-stanbol-entityhub">Requirements of the Stanbol Entityhub</h2>
+<p>This section tries to identify requirements of the Stanbol Entityhub related to Linked Data and Linked Media. The goal of this analysis is to identify where it makes sense to adopt Linked Data/Media principles for the RESTful interface of the Entityhub.</p>
+<p>The Entityhub fulfills two requirements: </p>
+<ol>
+<li>it allows to define and manage network of referenced sites used to retrieve information about entities from. In addition the Entityhub also supports the use of local caches to speedup access and to get independency of the availability of remote services. </li>
+<li>it manages an own (local) site that is used to manage local entities. Such entities can be created locally but it is also possible to import them form any referenced site. Typical examples of locally managed entities are customers, employees, concepts of a company thesaurus, offices, meeting rooms ... </li>
+</ol>
+<h3 id="entity-model-of-the-entityhub">Entity Model of the Entityhub</h3>
+<p>Entities managed by the entityhub define first an unique ID. In case the referenced site follows linked data principles this will be the HTTP URI of the Non-Information resource. However this might be any valid URI (including URNs). The URI prefix of locally managed entities are configureable. Therefore the URI type of locally managed entities depends on the configuration. The Entity itself represents a Non-Information Resource. Each Entity comes with a Representation. The representation holds all information known by the site about the entity. In Linked Data terminology the Representation is the Information Resource a User needs to be redirected when he requests the Entity (Non-Information Resource). Finally an Entity also links to the ID of the (referenced) site managing it. This allows users to track who is providing the information for an Entity.</p>
+<p>Currently the Entityhub distinguish three different types of Entities:</p>
+<ol>
+<li>Sign: All Entities managed by referenced sites</li>
+<li>Symbol: All locally managed Entities. Symbols hold additional metadata such as a preferred label, a state.</li>
+<li>EntityMapping: Mappings form Symbols to Signs. Linked Data typically uses owl:sameAs to define such mappings however in case of the Entityhub such mappings need to hold additional meta information such as the state, expire data of the mapping ...</li>
+</ol>
+<p>Metadata such as license, copyright statements, attributions as well as informations about the organization managing a referenced site are managed with referenced sites and not with single entities.</p>
+<p>All the additional information provided by this three Entity types as well as the additional metadata provided for referenced sites are based on Linked Data principles metadata about the Information Resource - the Representation - and not about the Non-Information Resource - the Entity.</p>
+<p>Therefore the Entityhub manages:</p>
+<ul>
+<li>Non-Information Resources: All the Entities of referenced Sites as well as locally managed Entities</li>
+<li>Content: All Representations about Entities</li>
+<li>Metadata: Additional information about Representations such as license, copyrights, attributions as well as mappings to other entities.</li>
+</ul>
+<h3 id="restful-services-of-the-entityhub">RESTful Services of the Entityhub</h3>
+<p>The Entityhub defines the following service endpoints:</p>
+<ol>
+<li>The (referenced) Site Manager: Provides retrieval and search over all referenced sites.</li>
+<li>(referenced) Site Endpoint: Provides the same interface but for a specific referenced site.</li>
+<li>The Entityhub Endpoint: Provides full read/write and retrieval access for locally managed Entities.</li>
+</ol>
+<p>Therefore the Entityhub needs to support read only access for Entities managed by referenced sites and full read/write access (CRUD) locally managed Entities.</p>
+<h3 id="summary">Summary</h3>
+<p>Consuming Linked Data:</p>
+<ul>
+<li>Consume Linked Data from remote sites</li>
+<li>Search resources on remote sites based on labels/language and type (by using SPARQL)</li>
+</ul>
+<p>Referenced Entities (Entities of Referenced Sites)</p>
+<ul>
+<li>Support local management of additional metadata for referenced entities (e.g. mappings to local entities)</li>
+<li>Support merging of remote metadata (e.g. defined by "foaf:primaryTopic") with local ones (e.g. mappings to local entities)</li>
+<li>Provide Content + Metadata - as proposed by Linked Media - even for referenced entities.</li>
+<li>Support Search for Entities based on labels/language and type</li>
+</ul>
+<p>Local Entities (Entities managed by the Entityhub)</p>
+<ul>
+<li>Provide local Entities as Linked Media (full CRUD support; management of Content and Metadata)</li>
+<li>Support creation of local entities based on referenced one</li>
+<li>Support finding of additional mappings based on owl:sameAs relations</li>
+<li>Support importing of metadata for mapped entities (e.g. to correctly handle attribution requirements)</li>
+<li>Support Enabling/disabling the use of redirects</li>
+<li>Support Search for Entities based on labels/language and type</li>
+</ul>
+<p>Based on this evaluation of the Model and the Services provided by the Entityhub the proposed Linked Media extension to the Linked Data principles would be sufficient to cover most of the functionalities exposed by the Entityhub as RESTful services. While for referenced Sites only the distinction between Metadata and Content is needed for locally managed Entities also the possibility to create, update and remove Entities, their Representation (content) and metadata is of central importance. The main functionalities not covered is the import of Entities from referenced sites. Also for functionalities like the creation of mappings and the management of the Entity workflow special additions to the generic Linked Media/Linked Data API would be useful.</p>
+<h2 id="specific-considerations">Specific Considerations</h2>
+<p>This section contains Entityhub specific considerations about some of the principles defined for Linked Data and Linked Media. </p>
+<h3 id="resource-identifier">Resource Identifier</h3>
+<p>Linked data defines the principle to use HTTP URIs as Resource Indetifier so that one can retrieve data by directly accessing the URI of a resource. This does not work out for the Entityhub because it needs to also manage remote entities and also for local entities this will not always be an option. Because of that the RESTful interface needs also to support an alternative that allows to parse the URI of an entity as a parameter. This is also a requirement to don't affect the IDs of entities when the Entityhub is deployed on an different host of even by using localhost. In addition this allows to use use other URI types (mainly URNs but also other protocols such as LDAP) as identifiers for locally managed entities.</p>
+<h3 id="redirects-for-content-negotiation">Redirects for Content Negotiation</h3>
+<p>It is important to consider that Entities are Non-Information Resources and based on Linked Data Principles requests for Non-Information resources need to be answered with redirects ("303 See Other") to the URI of the Information Resource. In practice such redirects are for two things:</p>
+<ol>
+<li>
+<p>To allow Users to directly access (and bookmark) URIs of a specific format and therefore bypass content negotiation. This is mainly because Browsers do not allow to define the "Accept" headers. Because of that without this indirection typical users would be unable to retrieve other formats that HTML.</p>
+<p>For the Entityhub where most of the requests will be issued by clients that support the usage of "Accept" headers, the usage of redirects seems unfavorable because: First it will double the numbers of requests and also adds an additional RTT (round trip time). Secound browsers always issue a GET request when following an redirect independent of the type for the initial request. This can cause problems when returning redirects for POST, PUT and DELETE requests. Because of this for the Entityhub it would make sense to provide the possibility to deactivate/activate the usage of redirects (e.g. via a configuration, a request property or even a header field).</p>
+</li>
+<li>
+<p>To attach metadata of the Information Resources. As an example take the <a href="http://data.nytimes.com">Linked Data endpoint of the New York Times</a>. It uses "http://data.nytimes.com/{uuid}" for Entities and "http://data.nytimes.com/{uuid}.rdf" for the RDF XML representations. When looking at the representations provided for Entities (e.g. take <a href="http://data.nytimes.com/N25800450843199534421">North Carolina</a> one can see that triples using "http://data.nytimes.com/{uuid}" as subject are data about North Carolina where triples that use "http://data.nytimes.com/{uuid}.rdf" as subject represent metadata. Note also that the metadata is also connected to the representation of North Carolina by the <a href="http://xmlns.com/foaf/0.1/primaryTopic">foaf:primaryTopic</a> relation. </p>
+<p>When using extensions proposed by Linked Media, than it would be possible to directly refer to the metadata by setting the "rel" parameter of the "Accept" header to "meta". Therefore a request defining "Accept: application/rdf+xml; rel=meta" would - assuming that redirects are deactivated - directly return the metadata for for the requested entity (e.g. the license) encoded as RDF XML. In case redirects are enabled it would return a "303 See Other" with the URI of the metadata.</p>
+<p>Note that - in principle - there are two kinds of redirects: (1) redirects between Resources. This includes redirects from Entities to Representation ("rel=content") as well as to the Metadata ("rel=meta"); (2) redirects used for Content Negotiation. Therefore it would be possible to provide the possibility to enable/disable this types separately. </p>
+<p>Also note that in cases where several redirects would be needed to reach the final resource (e.g. when requesting information about an Non-Information Resource in "text/html": Non-Information Resource -> Information resource -> HTML version) than the request will directly return the final destination. </p>
+</li>
+</ol>
+<h2 id="redesigning-the-entityhub">Redesigning the Entityhub</h2>
+<p>This section evaluates necessary changes to the Entityhub.</p>
+<h3 id="uri-scheme-for-resources">URI scheme for Resources</h3>
+<p>The support of Linked Data requires the use of a local URI. This is in contrast to the parameter based approach ("?id={remoteURI}") as currently used by the Entityhub. The goal is that the Entityhub allows both variants</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span> <span class="ow">and</span>
+<span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="o">/</span><span class="n">entity</span><span class="p">?</span><span class="n">uri</span><span class="o">=</span><span class="p">{</span><span class="n">uri</span><span class="p">}</span>
+</pre></div>
+
+
+<p>to refer an Entity. This requires that the Entityhub provides a local HTTP URI for any (local or remote) entity. The suggestion is to use the local name of the remote entity or the MD5 of the whole URI in cases where this is not possible.</p>
+<p>To support the redirects as defined by Linked Data it is also necessary to generate own URIs for Representations. To support the differentiation between Content and Metadata we need also an own URI for the metadata.</p>
+<p>The proposal is to use file extension like additions to the local name of Entities:</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span><span class="o">.</span><span class="n">rep</span>
+</pre></div>
+
+
+<p>is used to directly refer to the Representation of an Entity - in Linked Media terminology the Information Resource. Note that the local HTTP URI is use as base for the ".rep" extension. "?uri={uri}.rep" will not be supported. Users of the Entityhub can therefore use the ".rep" extension to directly access the content for an Entity. Note that content negotiation will still be needed when requesting this kind of URIs.</p>
+<p>Similar to the above the ".meta" extension will be used for constructing URIs for the metadata:</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span><span class="o">.</span><span class="n">meta</span>
+</pre></div>
+
+
+<p>For referenced entities such representations will be created by merging remote metadata with locally managed. Remote Metadata will be recognized by Resources with a <a href="http://xmlns.com/foaf/0.1/primaryTopic">foaf:primaryTopic</a> relation to the Entity. Local Metadata can include information known for the referenced site (e.g. license, copyright, attributions, information about the managing organization ...) as well as mappings to other (locally managed) entities.</p>
+<p>For locally managed Entities the metadata will also include all the additional information as currently defined by the Symbol API (state, predecessors, successors).</p>
+<p>Note that the URIs for Representations and Metadata are optional and will be omitted based on HTTP request headers in case redirects are disabled. However even in case that redirects are disabled it is still possible to use such URIs for requests.</p>
+<h3 id="uri-scheme-for-content-negotiation">URI scheme for Content Negotiation</h3>
+<p>To confirm with the Linked Data principles the Entityhub needs to provide unique HTTP URIs for any content type Information Resources (Content and Metadata Resoruces) can be serialized. As for the ".rep" and ".meta" extensions used to directly access Representations and their Metadata the proposal is also to use of file extensions to indicate the media type. In cases users wish to parse the remote URI as parameter it is also possible to parse the extension or the media type as parameter.</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span><span class="o">.</span><span class="p">{</span><span class="n">extension</span><span class="p">}</span> <span class="ow">or</span>
+<span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="o">/</span><span class="n">entity</span><span class="p">?</span><span class="n">uri</span><span class="o">=</span><span class="p">{</span><span class="n">uri</span><span class="p">}</span><span class="o">&</span><span class="nb">format</span><span class="o">=</span><span class="p">{</span><span class="n">extension</span><span class="p">}</span><span class="o">&</span><span class="n">mediaType</span><span class="o">=</span><span class="p">{</span><span class="n">mediatype</span><span class="p">}</span>
+</pre></div>
+
+
+<p>This shows the case that the extension is directly added to the local URI of the entity. In this case the "rel" parameter of the Accept header would be used to determine if the content - representation - or the metadata need to be encoded in the response. If not specified the representation will be returned.</p>
+<p>To allow also to directly address the representation or the metadata in a specific format the Entityhub also supports the following two variants: </p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span><span class="o">.</span><span class="n">rep</span><span class="o">.</span><span class="p">{</span><span class="n">extension</span><span class="p">}</span>
+<span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">host</span><span class="p">}</span><span class="sr">/entityhub/</span><span class="p">{</span><span class="n">site</span><span class="p">}</span><span class="sr">/entity/</span><span class="p">{</span><span class="n">localname</span><span class="p">}</span><span class="o">.</span><span class="n">meta</span><span class="o">.</span><span class="p">{</span><span class="n">extension</span><span class="p">}</span>
+</pre></div>
+
+
+<p>Note that the URIs used for content negotiation are optional and will be omitted based on HTTP request headers in case redirects are disabled. However even in case that redirects are disabled it is still possible to use such URIs for requests.</p>
+<h3 id="http-requestresponse-headers-with-special-use">HTTP Request/Response Headers with special use</h3>
+<p>This section provides information about header fields that are specially evaluated by the Entityhub. Normal evaluations of headers as specified by <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">RFC2616 section 14</a> e.g. the use of Content-Type to read data parsed by PUT/POST requests are not described.</p>
+<h4 id="accept-header"><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">Accept header</a></h4>
+<p>The Accept header allows to specify the media type of the content as expected by the client in the response. The <a href="http://lists.w3.org/Archives/Public/public-lod/2011May/0019.html">Linked Media proposal</a> suggests to use the "rel" parameter to specify if the response should return the data or the metadata of the requested resource. The semantics of the "rel" parameter is defined for the Link header by <a href="http://www.ietf.org/rfc/rfc5988.txt">RFC5988</a>. An related example can be found on the <a href="http://www.w3.org/wiki/LinkHeader">LinkHeader</a> page on the W3C wiki.</p>
+<p>The pattern useable for Accept header looks like</p>
+<div class="codehilite"><pre><span class="n">Accept:</span> <span class="p">{</span><span class="n">media</span><span class="o">-</span><span class="n">type</span><span class="p">}[;</span> <span class="n">rel</span><span class="o">=</span><span class="n">meta</span><span class="p">]</span>
+</pre></div>
+
+
+<p>If no "rel" pattern is specified the Entityhub will return the data (representation about the entity) as default. If users want to retrieve the the metadata they need to add "rel=meta". The {media-type} is always applied to the information selected by the "rel" parameter. </p>
+<h4 id="cache-control"><a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control</a></h4>
+<p>The Entityhub supports the following cache-request-directives to allow clients some control about local caching of entities managed by remote sites. Note that the Stanbol OFFLINE mode has precedence over Cache-Control specifications<br />
+</p>
+<ul>
+<li>no-cache: Entities are retrieved from the remote site even if a local cache exists (if Stanbol is not in OFFLINE mode)</li>
+<li>no-store: Entities retrieved from a remote side are not cached locally (if Stanbol is not in OFFLINE mode)</li>
+<li>no-transform: The Entityhub may be configured to transform/filter information from the remote site. This can be used to bypass this kind of transformations. In case transformations are used for the local cache, then this parameter will not work out if Stanbol is operates in OFFLINE mode</li>
+<li>only-if-cached: Representations are only returned if they are available in the local cache.</li>
+</ul>
+<h4 id="link-header"><a href="http://www.ietf.org/rfc/rfc5988.txt">Link Header</a></h4>
+<p>The Link header is central to Linked Data and Linked Media because it is used to expose internal structures defined in-between Resources (in-between Entities but also between Entities and there Representations and Metadata)</p>
+<p>The principle Syntax of Link headers is as follows:</p>
+<div class="codehilite"><pre><span class="n">Link:</span> <span class="o">&</span><span class="ow">lt</span><span class="p">;{</span><span class="n">uri</span><span class="p">}</span><span class="o">&</span><span class="ow">gt</span><span class="p">;;</span> <span class="n">rel</span><span class="o">=</span><span class="s">"{relation}"</span><span class="p">;</span> <span class="n">type</span><span class="o">=</span><span class="s">"{media-type}"</span>
+</pre></div>
+
+
+<p>The relation parameter defines the type of the relation. <a href="http://www.iana.org/assignments/link-relations/link-relations.xml">Registered relation types</a> are mainly used to improve the navigation of users. The values "content" and "meta" as suggested by the Linked Media proposal are currently not registered. In such cases <a href="http://www.ietf.org/rfc/rfc5988.txt">RFC5988</a> requires the use of absolute URIs as {relation}. This document will use "content" and "meta" instead of the full URIs as required by RFC5988.</p>
+<p>Regardless of that the values used for the "rel" parameter within the "Link" header by the Entityhub MUST BE the SAME as supported values for the "rel" parameter in the "Accept" header for requests. A pragmatic solution would be to support both the short form and a full URI.<br />
+</p>
+<p>The Entityhub will add the following Links (if applicable)</p>
+<ul>
+<li>
+<p>A reference to the Non-Information resource for the Entity by using the relation type "self". This will always use the local URI used for the resource. In case of remote entities there is also a link to the original resource.</p>
+<p>Link: http://{host}/entityhub/{site}/entity/{localname}; rel=self; </p>
+</li>
+<li>
+<p>A reference to the representation about the reference by using the relation type "content". Currently it is not intended to provide separate links to all available media types for content.</p>
+<p>Link: http://{host}/entityhub/{site}/entity/{localname}.ref; rel=content;</p>
+</li>
+<li>
+<p>A reference to the metadata about the representation about the Entity. Currently it is not intended to provide separate links to all available media types for metadata.</p>
+<p>Link: http://{host}/entityhub/{site}/entity/{localname}.meta; rel=meta;</p>
+</li>
+<li>
+<p>A reference to the source in case of referenced entities. This will be the URI of the entity</p>
+<p>Link: {uri}; rel=via</p>
+</li>
+<li>
+<p>A link to the license for the entity if present</p>
+<p>Link: {licenseURI}; rel=license</p>
+</li>
+</ul>
+<h3 id="entity-model">Entity Model</h3>
+<p>This changes to the RESTful API should be also reflected in the Java API. Currently on the API level there are three types of Entities: Sign, Symbol and EntityMapping. The only differentiation between those Entities are a different set of metadata. However there is no plan to distinguish such types on the RESTful API level.</p>
+<p>To streamline the domain model and to bring it more in line with the RESTful API the proposal is to drop the different Entity types. The Sign, Symbol and EnttiyMapping Interfaces will be replaced by a single Entity interface with the following Methods</p>
+<div class="codehilite"><pre><span class="n">Entity</span>
+ <span class="o">+</span> <span class="n">getId</span><span class="p">()</span> <span class="p">:</span> <span class="n">String</span>
+ <span class="o">+</span> <span class="n">getSite</span><span class="p">()</span> <span class="p">:</span> <span class="n">String</span>
+ <span class="o">+</span> <span class="n">getRepresentation</span><span class="p">()</span> <span class="p">:</span> <span class="n">Representation</span>
+ <span class="o">+</span> <span class="n">getMetadata</span><span class="p">()</span> <span class="p">:</span> <span class="n">Representation</span>
+</pre></div>
+
+
+<p>The use of the Representation interface also for the Metadata allows the use of the same parsers and serializes for both content and metadata. Functionality currently depending on the special APIs of Sign, Symbol and EntityMapping need to be adapted to retrieve the information via the Representation interface. This should be implemented by an utility class.</p>
+<h2 id="references">References</h2>
+<p>[1] http://lists.w3.org/Archives/Public/public-lod/2011May/0019.html</p>
+<p>[2] http://code.google.com/p/kiwi/source/browse/kiwi-core/src/main/java/kiwi/core/webservices/resource/ResourceWebService.java</p>
+<p>[3] Kiwi Project: http://www.kiwi-community.eu/ Blog: http://planet.kiwi-project.eu/</p>
+<p>[4] Kiwi Source Repository: http://code.google.com/p/kiwi/</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,116 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - Apache Entityhub</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+ <div id="content">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/entityhub/">Entityhub</a>
+ </div>
+ <h1 class="title">Apache Entityhub</h1>
+ <p>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.</p>
+<p><img alt="Features of the Stanbol Entityhub" src="entityhub-overview.png" /></p>
+<p>The main Features are the:</p>
+<ul>
+<li><strong>Entityhub</strong> (<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 <a href="managedsite.html">ManagedSite</a> instead.</li>
+<li><strong>Site Manager</strong> (<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.</li>
+<li><strong>Sites</strong> (<code>/entityhub/site/{siteId}</code>): Sites represent entity sources that are integrated with the Stanbol Entityhub. There are two different types of Sites<ul>
+<li><strong>ReferencedSite</strong>: 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 <a href="../customvocabulary.html">Working with Custom Vocabularies</a> provides a good overview on how to use this feature.</li>
+<li><strong>ManagedSite</strong>: <a href="managedsite.html">ManagedSites</a> 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.</li>
+</ul>
+</li>
+</ul>
+<h2 id="restful-services">RESTful services</h2>
+<p>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 <a href="../tutorial.html">this introduction</a> provides you with all necessary information. You can also try to access the documentation on the Stanbol demo server available on the <a href="http://dev.iks-project.eu/">IKS development server</a> at <a href="http://dev.iks-project.eu:8081/entityhub">http://dev.iks-project.eu:8081/entityhub</a>.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/managedsite.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/managedsite.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/entityhub/managedsite.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,189 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - ManagedSite</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+ <div id="content">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/entityhub/">Entityhub</a>
+ </div>
+ <h1 class="title">ManagedSite</h1>
+ <p>A ManagedSite allow users to manage a collection of Entities by using the RESTful API of the Entityhub. Other than the ReferencedSite implementation it does not allow to refer to remote services. Therefor all changes to Entities managed by a ManagedSite are preformed via the RESTful API of the Entityhub.</p>
+<p>Users can configure multiple ManagedSites with the Stanbol Entitiyhub. They are identified by their id and share the id-space with other Sites (e.g. other ReferencedSite). The RESTful services of a ManagedSite are available via the URL pattern</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">stanbol</span><span class="o">-</span><span class="n">instance</span><span class="p">}</span><span class="sr">/entityhub/si</span><span class="n">te</span><span class="o">/</span><span class="p">{</span><span class="n">siteId</span><span class="p">}</span>
+</pre></div>
+
+
+<p><em>NOTE:</em> To make this documentation less abstract it will use a scenario that assumes that someone wants to managing the <a href="http://www.iptc.org/cms/site/index.html?channel=CH0103#descrncd">IPTC Descriptive NewsCodes</a> by using a ManagedSite. Typical Stanbol users will want to manage their own Entities (e.g. Tags/Categories of their CMS) instead.</p>
+<h3 id="manage-entities-by-using-restful-services">Manage Entities by using RESTful services</h3>
+<p>The RESTful API of Managed Sites is the same as of other Sites only the "/entity" Endpoint does also support to create, update and delete Entities.</p>
+<p>The following Example shows how to upload a SKOS vocabulary to a ManagedSite:</p>
+<div class="codehilite"><pre>curl -i -X PUT -H <span class="s2">"Content-Type: application/rdf+xml"</span> -T subject-code.rdf <span class="se">\</span>
+ <span class="s2">"http://localhost:8080/site/iptc/entity"</span>
+</pre></div>
+
+
+<p>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 <a href="http://cv.iptc.org/newscodes/subjectcode/">subject-codes</a>. To upload also the vocabulary containing the <a href="http://cv.iptc.org/newscodes/genre/">genre</a>s one needs to call</p>
+<div class="codehilite"><pre>curl -i -X PUT -H <span class="s2">"Content-Type: application/rdf+xml"</span> -T genre.rdf <span class="se">\</span>
+ <span class="s2">"http://localhost:8080/site/iptc/entity"</span>
+</pre></div>
+
+
+<p>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.</p>
+<div class="codehilite"><pre>curl -i -X PUT -H <span class="s2">"Content-Type: application/rdf+xml"</span> -T genre.rdf <span class="se">\</span>
+ <span class="s2">"http://localhost:8080/site/iptc/entity?id=http://cv.iptc.org/newscodes/genre/Exclusive"</span>
+</pre></div>
+
+
+<p>This will ignore all other RDF data but only update the 'genre:Exclusive' entity.</p>
+<p>For the full documentation of the CRUD interface of the '/entity' endpoint of a ManagedSite please have a look at the RESTful API documentation served by the Web UI of the Stanbol Entityhub.</p>
+<h3 id="configuration-of-managedsites">Configuration of ManagedSites</h3>
+<p>Currently their is a single implementation of the ManagesSite interface that uses a <code>Yard</code> instance for managing the entities.</p>
+<p>For using a YardSite users need to configure two Services:</p>
+<ol>
+<li>Yard: The Entityhub currently includes two different Yard implementations. The SolrYard and the ClerezzaYard. The SolrYard is optimal for the use with the Stanbol Enhancer as it allows very fast label based retrieval of Entities. So if you plan to use the ManagedSite primarily with the Stanbol Enhancer this is definitely the Yard implementation to choose. The ClerezzaYard stores the managed Entities within a TripleStore. While the ClerezzaYard is not as efficient for the use with the StanbolEnhancer its data can be queried by using the SPARQL endpoint of Apache Stanbol.</li>
+<li>YardSite: This configures the ManagedSite. This configuration links to the configured Yard via its id.</li>
+</ol>
+<h4 id="configuration-of-a-solryard">Configuration of a SolrYard:</h4>
+<p>This describes how to configure an SolrYard to be used with an YardSite by using the Configuration tab of the Apache Felix Webconsole <a href="http://localhost:8080/system/console/configMgr">http://{stanbol-instance}/system/console/configMgr</a>.</p>
+<p><img alt="Typical SolrYard configuration for a YardSite" src="entityhub-manatedsite-solryard-config.png" /></p>
+<p>The above figure shows a typical SolrYard configuration for a YardSite. Important properties are </p>
+<ul>
+<li><strong>ID</strong>: This MUST BE unique to all other Yards. It is recommended to use "{siteId}Yard".</li>
+<li><strong>Solr Index/Core</strong>: 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>.</li>
+<li><strong>Use default SolrCore configuration</strong>: 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<a href="../utils/commons-solr.html#managing-solr-indexes">Managing Solr Indexes</a> section for detailed information. </li>
+</ul>
+<h4 id="configuration-of-a-clerezzayard">Configuration of a ClerezzaYard:</h4>
+<p>This describes how to configure an ClerezzaYard to be used with an YardSite by using the Configuration tab of the Apache Felix Webconsole <a href="http://localhost:8080/system/console/configMgr">http://{stanbol-instance}/system/console/configMgr</a>.</p>
+<p><img alt="Typical ClerezzaYard configuration for a YardSite" src="entityhub-managedsite-clerezzayard-config.png" /></p>
+<p>The above figure shows a typical ClerezzaYard configuration for a YardSite. Important properties are</p>
+<ul>
+<li><strong>ID</strong>: This MUST BE unique to all other Yards. It is recommended to use "{siteId}Yard".</li>
+<li><strong>Graph URI</strong>: This allows to configure the URI of the named graph used to store the RDF data. If a graph with this URL is already present than it will be reused by this Yard. Otherwise an empty graph with this URI is created using the Clerezza <a href="http://incubator.apache.org/clerezza/mvn-site/rdf.core/apidocs/org/apache/clerezza/rdf/core/access/TcManager.html">TcManager</a>. If this field is empty an URN will be used as default groph URI.</li>
+</ul>
+<p>The ClerezzaYard also registers the its RDF graph with the Apache Stanbol SPARQL service available at <code>http://{stanbol-instance}/sparql</code></p>
+<p>To query the RDF graph of a ClerezzaYard you need to specify the its configured Graph URI in SPARQL queries posted to the Stanbol SPARQL endpoint</p>
+<div class="codehilite"><pre>curl -i -X POST -d <span class="s2">"graphuri=http://cv.iptc.org/newscodes"</span> <span class="se">\</span>
+ --data-urlencode <span class="s2">"query@sparqlQuery.txt"</span> <span class="se">\</span>
+ <span class="s2">"http://localhost:8080/sparql"</span>
+</pre></div>
+
+
+<p>where 'sparqlQuery.txt' refers to a file containing the SPARQL query e.g.</p>
+<div class="codehilite"><pre><span class="n">PREFIX</span> <span class="n">skos:</span> <span class="sr"><http://www.w3.org/2004/02/skos/core#></span>
+<span class="n">SELECT</span> <span class="n">distinct</span> <span class="p">?</span><span class="n">concept</span> <span class="p">?</span><span class="n">prefLabel</span> <span class="p">?</span><span class="n">altLabel</span> <span class="p">?</span><span class="n">parent</span>
+<span class="n">WHERE</span> <span class="p">{</span>
+ <span class="p">?</span><span class="n">concept</span> <span class="n">a</span> <span class="n">skos:Concept</span> <span class="o">.</span>
+ <span class="p">?</span><span class="n">concept</span> <span class="n">skos:prefLabel</span> <span class="p">?</span><span class="n">prefLabel</span> <span class="o">.</span>
+ <span class="n">OPTIONAL</span> <span class="p">{</span>
+ <span class="p">?</span><span class="n">concept</span> <span class="n">skos:altLabel</span> <span class="p">?</span><span class="n">altLabel</span> <span class="o">.</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h4 id="configuration-of-the-yardsite">Configuration of the YardSite</h4>
+<p>Finally you need to configure the YardSite that uses the previously configured Yard instance (either SolrYard or ClerezzaYard). Again this will show how to configure the YardSite by using the Configuration tab of the Apache Felix Webconsole <a href="http://localhost:8080/system/console/configMgr">http://{stanbol-instance}/system/console/configMgr</a>.</p>
+<p><img alt="Typical YardSite configuration" src="entityhub-managedsite-yardsite-config.png" /></p>
+<p>The above figure shows the configuration of the YardSite. The important properties are</p>
+<ul>
+<li><strong>ID</strong>: This is the {siteId} used to map this ManagedSite to the RESTful API of the Stanbol Entityhub. Make sure that the ID is unique over all configured Sites.</li>
+<li><strong>Yard ID</strong>: Here you need to put the ID of the Yard configured in the previous step. If no Yard with that ID is active the ManagedSite will not be initialized and therefore be not available on the RESTful API</li>
+</ul>
+<p>The <strong>Entity Prefix(es)</strong> are an optional configuration. This is used by the SiteManager (the "/entityhub/sites" endpoint) if requested entities can be dereferenced via a registered site. If not present the SiteManager will try to dereference every request by using this ManagedSite. So correctly configuring this may slightly improve performance by avoiding unnecessary requests.</p>
+<p>The <strong>Field Mappings</strong> can be used to copy property values of created/updates Entities to other properties. The mappings used in the above figure ensure that SKOS preferred/alternate labels, FOAF (Friend of a Friend) names, Dublin Core titles as well as the name property of the schema.org ontology are copied over to rdfs:label. This configuration is the default as the Stanbol Enhancer uses <code>rdfs:label</code> as default property for linking entities based on their names.</p>
+<p>After completing all those steps you should see a new empty ManagedSite under</p>
+<div class="codehilite"><pre><span class="n">http:</span><span class="sr">//</span><span class="p">{</span><span class="n">stanbol</span><span class="o">-</span><span class="n">instance</span><span class="p">}</span><span class="sr">/entityhub/si</span><span class="n">te</span><span class="o">/</span><span class="n">iptc</span>
+</pre></div>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/implementation.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/implementation.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/implementation.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,112 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - FactStore Implementation Concept</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+ <div id="content">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/factstore/">Factstore</a>
+ </div>
+ <h1 class="title">FactStore Implementation Concept</h1>
+ <p>The <a href="specification.html">FactStore specification</a> is written with a certain kind of implementation in mind. Although the implementation of the specification is not pretended it might be useful to have a look at this simple implementation concept.</p>
+<h2 id="store-implementation">Store Implementation</h2>
+<p>The store implementation is based on the well known concept of relational databases. Each fact schema is a table in a relational database. Creating a new fact schema is equivalent to creating a new table with a number of String attributes, because we store IRIs, according to the schema. For performance reasons the attributes should be indexed.
+The store just needs to be able to create new schemata. It is not specified that a schema may be altered over time. This could be an improvement for the future.</p>
+<h2 id="query-implementation">Query Implementation</h2>
+<p>The JSON-LD query structure is designed to be mapped directly to valid SQL statements. If the store is implemented in a relational database all queries can be transformed to SQL queries to this database. For security reasons it is important to keep hacks like SQL injection in mind when transforming the JSON-LD query to SQL.</p>
+<p>As seen in the examples, queries may use attributes of entities to formulate the request. However, the FactStore does only store the IRIs of the entities not the entities with their attributes. Therefore, the FactStores needs an EntityHub to resolve entities specified by their attributes. The EntityHub must be able to query for entities by example.</p>
+<p>Note: Depending on the number of entities returned by the EntityHub for a certain request this architecture may lead to performance problems. It has to be evaluated where the limit of this approach is in terms of performance. However, the assumption is that in many (or most) scenarios this will not become a problem. If it becomes a problem, the type of allowed queries may be restricted, e.g. don't allow queries that use entity attributes in the "where" clause, to avoid performance or memory problems.</p>
+<hr />
+<p><em>Back to <a href="index.html">FactStore</a></em></p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Added: websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/index.html
==============================================================================
--- websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/index.html (added)
+++ websites/staging/stanbol/trunk/content/stanbol/docs/trunk/components/factstore/index.html Mon Jul 16 13:02:45 2012
@@ -0,0 +1,145 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE- 2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+ <link href="/stanbol/css/stanbol.css" rel="stylesheet" type="text/css">
+ <title>Apache Stanbol - Factstore</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <link rel="icon" type="image/png" href="/stanbol/images/stanbol-logo/stanbol-favicon.png"/>
+ <script type="text/javascript">
+ // Google Analytics Tracking Code
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-32086816-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+ </script>
+</head>
+
+<body>
+ <div id="logo"> <!-- do not scroll the logo -->
+ <a href="/stanbol/index.html"><img alt="Apache Stanbol" width="220" height="101" border="0" src="/stanbol/images/stanbol-logo/stanbol-2010-12-14.png"/></a></div>
+ <div id="navigation"> <!-- but auto scroll the menue -->
+ <h1 id="stanbol">Stanbol</h1>
+<ul>
+<li><a href="/stanbol/index.html">Home</a></li>
+<li><a href="/stanbol/docs/trunk/tutorial.html">Getting Started</a></li>
+<li><a href="/stanbol/docs/trunk/">Documentation</a><ul>
+<li><a href="/stanbol/docs/trunk/scenarios.html">Usage Scenarios</a></li>
+<li><a href="/stanbol/docs/trunk/components.html">Components</a></li>
+</ul>
+</li>
+<li><a href="/stanbol/development/">Development</a></li>
+</ul>
+<h1 id="project">Project</h1>
+<ul>
+<li><a href="/stanbol/docs/trunk/mailinglists.html">Mailing Lists</a></li>
+<li><a href="https://issues.apache.org/jira/browse/STANBOL">Issue Tracker</a></li>
+<li><a href="/stanbol/team.html">Project Team</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li>
+<li><a href="/stanbol/privacy-policy.html">Privacy Policy</a></li>
+</ul>
+<h1 id="downloads">Downloads</h1>
+<ul>
+<li><a href="/stanbol/downloads/">Overview</a><ul>
+<li><a href="/stanbol/downloads/releases.html">Releases</a></li>
+<li><a href="/stanbol/downloads/launchers.html">Launchers</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="archive">Archive</h1>
+<ul>
+<li><a href="/stanbol/docs/0.9.0-incubating/">0.9.0-incubating</a></li>
+</ul>
+<h1 id="the-asf">The ASF</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+<li><a href="http://www.apache.org/security/">Security</a></li>
+</ul>
+ </div>
+ <div id="content">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a href="/stanbol/">Stanbol</a> » <a href="/stanbol/docs/">Docs</a> » <a href="/stanbol/docs/trunk/">Trunk</a> » <a href="/stanbol/docs/trunk/components/">Components</a> » <a href="/stanbol/docs/trunk/components/factstore/">Factstore</a>
+ </div>
+ <h1 class="title">Factstore</h1>
+ <p>The FactStore is a component that let's use store relations between entities identified by their URIs. A relation between two or more entities is called a <em>fact</em>. The FactStore let's you store N-ary facts according to a user defined fact schema. In consequence you can store relations between N participating entities. The FactStore only stores the relation and not the entities itself. It only uses references to entities by using the entities' URI. The entities itself should be handled by another component, e.g. the <a href="../entityhub/">Entityhub</a>. A fact is defined by a fact schema which is defined over types of entities.</p>
+<p>A fact schema can be defined between an arbitrary number of entities. In most cases a fact schema is defined between two or three entities. For example, the fact schema 'works-for' can be defined as a relation between entities of type 'Person' and 'Organization'. The Fact Store interface allows the creation of custom fact schemata and to store facts according to these custom schemata. The Fact Store provides a simple way to define and store facts. This component is meant to be used in scenarios where a simple solution is sufficient and it is not required to define a complex ontology with reasoning support.</p>
+<p>Read on and have a look at a concrete example or go to the <a href="specification.html">FactStore specification</a> page for more details. If you need some information about its realization, read the notes about its <a href="implementation.html">implementation concept</a>.</p>
+<h2 id="example">Example</h2>
+<p>Imagine you want to store the fact that the person named John Doe works for the company Winzigweich. John Doe is represented by the URI http://www.doe.com/john and the company by http://www.winzigweich.de. This fact is stored as a relation between the entity http://www.doe.com/john and http://www.winzigweich.de.</p>
+<p>For this, we first need to create a so called fact schema that tells the FactStore what we would like to store. A fact schema has a unique name (often an URI is used) to identify it. To specify what kinds of entities we would like to store, we specify the type of the entities. Each type has an URI and should be defined by some ontology. For example, we can use the ontology specified by <a href="http://schema.org/">schema.org</a>.</p>
+<p>According to <a href="http://schema.org/">schema.org</a> is a person of type <a href="http://schema.org/Person">http://schema.org/Person</a> and an organization is of type <a href="http://schema.org/Organization">http://schema.org/Organization</a>. We will use these type information to specify the fact schema http://factschema.org/worksFor. The specification of a fact schema is written in JSON-LD, like this:</p>
+<div class="codehilite"><pre><span class="p">{</span>
+ <span class="s">"@context"</span> <span class="p">:</span> <span class="p">{</span>
+ <span class="s">"#types"</span> <span class="p">:</span> <span class="p">{</span>
+ <span class="s">"person"</span> <span class="p">:</span> <span class="s">"http://schema.org/Person"</span><span class="p">,</span>
+ <span class="s">"organization"</span> <span class="p">:</span> <span class="s">"http://schema.org/Organization"</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>To create this fact schema in the FactStore we have to store it in a *.json file, e.g. worksFor.json, and PUT it into the FactStore. The path to put the fact schema is <code>/factstore/facts/{factSchemaName}</code>. So for our example this would be <code>/factstore/facts/http://factschema.org/worksFor</code>. Unfortunately, this is not a valid URI so that we have to URL-encode the name of the fact schema. This leads to
+<code>/factstore/facts/http%3A%2F%2Ffactschema.org%2FworksFor</code>.</p>
+<p><em>Note</em>: If you want to avoid this URL-encoding step, you should chose another name for your fact schema that is not an URI by itself. You are free to do so!</p>
+<p>Now to PUT the <code>worksFor</code> fact schema we can use this cURL command.</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/factstore/</span><span class="n">facts</span><span class="o">/</span><span class="n">http</span><span class="nv">%3A%2F%2Ffactschema</span><span class="o">.</span><span class="n">org</span><span class="nv">%2FworksFor</span> <span class="o">-</span><span class="n">T</span> <span class="n">worksFor</span><span class="o">.</span><span class="n">json</span>
+</pre></div>
+
+
+<p>After creating the fact schema we can store the fact that John Doe works for Winzigweich by POSTing it to the FactStore. The fact is specified in JSON-LD syntax. The <code>@profile</code> defines the fact schema where this fact belongs to.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+ <span class="s">"@profile"</span> <span class="p">:</span> <span class="s">"http://factschema.org/worksFor"</span><span class="p">,</span>
+ <span class="s">"person"</span> <span class="p">:</span> <span class="p">{</span> <span class="s">"@iri"</span> <span class="p">:</span> <span class="s">"http://www.doe.com/john"</span> <span class="p">},</span>
+ <span class="s">"organization"</span> <span class="p">:</span> <span class="p">{</span> <span class="s">"@iri"</span> <span class="p">:</span> <span class="s">"http://www.winzigweich.de"</span><span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Now we can POST this fact, e.g. stored in fact.json, to the FactStore at <code>/factstore/facts</code>. By using cURL it would be this command:</p>
+<div class="codehilite"><pre><span class="n">curl</span> <span class="o">-</span><span class="n">d</span> <span class="nv">@fact</span><span class="o">.</span><span class="n">json</span> <span class="o">-</span><span class="n">H</span> <span class="s">"Content-Type: application/json"</span> <span class="n">http:</span><span class="sr">//</span><span class="n">localhost:8080</span><span class="sr">/factstore/</span><span class="n">facts</span>
+</pre></div>
+
+
+<p>On success this will return a 201 (Created) and the URI of the newly created fact in the location header of the response. To retrieve a fact you can GET it from the returned URI.</p>
+<h2 id="rest-api-documentation">REST API Documentation</h2>
+<p>To get the latest documentation you should start your copy of an Apache Stanbol launcher that includes the FactStore and navigate your browser to http://localhost:8080/factstore. There you will find more information and the documentation of the FactStore's REST API.</p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2010 The Apache Software Foundation, Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+ <br />
+ Apache, Stanbol and the Apache feather and Stanbol logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>