You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2013/03/28 18:17:24 UTC
svn commit: r856347 - in /websites/staging/jena/trunk/content: ./
documentation/io/
Author: buildbot
Date: Thu Mar 28 17:17:24 2013
New Revision: 856347
Log:
Staging update by buildbot for jena
Added:
websites/staging/jena/trunk/content/documentation/io/rdf-input.html
Removed:
websites/staging/jena/trunk/content/documentation/io/arp_features.html
websites/staging/jena/trunk/content/documentation/io/output.html
Modified:
websites/staging/jena/trunk/content/ (props changed)
websites/staging/jena/trunk/content/documentation/io/arp.html
websites/staging/jena/trunk/content/documentation/io/index.html
websites/staging/jena/trunk/content/documentation/io/rdf-output.html
websites/staging/jena/trunk/content/documentation/io/rdfxml_howto.html
Propchange: websites/staging/jena/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Mar 28 17:17:24 2013
@@ -1 +1 @@
-1462003
+1462217
Modified: websites/staging/jena/trunk/content/documentation/io/arp.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/arp.html (original)
+++ websites/staging/jena/trunk/content/documentation/io/arp.html Thu Mar 28 17:17:24 2013
@@ -159,11 +159,58 @@
<p>This section details the Jena RDF/XML parser.
ARP is the parsing subsystem in Jena for handling the RDF/XML syntax.</p>
<ul>
-<li><a href="rdfxml_howto.html">Using ARP</a></li>
-<li><a href="arp_features.html">ARP Features</a></li>
+<li><a href="#arp-features">ARP Features</a></li>
<li><a href="arp_standalone.html">Using ARP without Jena</a></li>
<li><a href="arp_sax.html">Using other SAX and DOM XML sources</a></li>
</ul>
+<h2 id="arp-features">ARP Features</h2>
+<ul>
+<li>Java based RDF parser.</li>
+<li>Compliant with
+ <a href="http://www.w3.org/TR/rdf-syntax-grammar">RDF Syntax</a> and
+ <a href="http://www.w3.org/TR/rdf-testcases">RDF Test Cases</a>
+ Recommendations.</li>
+<li>Compliant with following standards and recommendations:<ul>
+<li><strong>xml:lang</strong><br />
+ <a href="http://www.w3.org/TR/REC-xml#sec-lang-tag">xml:lang</a> is fully
+ supported, both in RDF/XML and any document embedding RDF/XML.
+ Moreover, the language tags are checked against
+ <a href="http://www.isi.edu/in-notes/rfc1766.txt">RFC1766</a>,
+ <a href="http://www.isi.edu/in-notes/rfc3066.txt">RFC3066</a>, ISO639-1,
+ <a href="http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/db_en.html">ISO3166</a>.</li>
+<li><strong>xml:base</strong><br />
+ <a href="http://www.w3.org/TR/xmlbase/">xml:base</a> is fully supported,
+ both in RDF/XML and any document embedding RDF/XML.</li>
+<li><strong>URI</strong><br />
+ All URI references are checked against
+ <a href="http://www.isi.edu/in-notes/rfc2396.txt">RFC2396</a>. The treatment
+ of international URIs implements the concept of
+ <a href="http://www.w3.org/TR/rdf-concepts/#dfn-URI-reference">RDF URI Reference</a>.</li>
+<li><strong>XML Names</strong><br />
+ All rdf:ID's are checked against the
+ <a href="http://www.w3.org/TR/REC-xml#dt-name">XML Names</a> specification.</li>
+<li><strong>Unicode Normal Form C</strong><br />
+ String literals are checked for conformance with an early
+ uniform normalization processing model.</li>
+<li><strong>XML Literals</strong><br />
+ <code>rdf:parseType='Literal'</code> is processed respecting namespaces,
+ processing instructions and XML comments. This follows the XML
+ exclusive canonicalizations recommendation with comments.</li>
+<li><strong>Relative Namespace URI references</strong><br />
+ Namespace URI references are checked in light of the
+ <a href="http://www.w3.org/2000/09/xppa">W3C XML Plenary decision</a>.</li>
+</ul>
+</li>
+<li>Command-line RDF/XML error checking.</li>
+<li>Can be used independently of Jena, with customizable
+ <code>StatementHandler</code>.</li>
+<li>Highly configurable error processing.</li>
+<li>Xerces based XML parsing.</li>
+<li>Processes both standalone and embedded RDF/XML.</li>
+<li>Streaming parser, suitable for large files.</li>
+<li>Supports SAX and DOM, for integration with non-file XML
+ sources.</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/jena/trunk/content/documentation/io/index.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/index.html (original)
+++ websites/staging/jena/trunk/content/documentation/io/index.html Thu Mar 28 17:17:24 2013
@@ -156,35 +156,17 @@
<div id="content">
<h1 class="title">Reading and Writing RDF in Jena</h1>
- <p>This page details the setup of RDF I/O technology (RIOT) introduced in Jena 2.10.</p>
-<p>The output capabilities are described <a href="rdf-output.html">elsewhere</a>.</p>
+ <p>This page details the setup of RDF I/O technology (RIOT).</p>
<ul>
<li><a href="#formats">Formats</a></li>
<li><a href="#command-line-tools">Commands</a></li>
-<li><a href="#inference">Inference</a></li>
-<li><a href="#api">API</a><ul>
-<li><a href="#determining-the-rdf-syntax">Determining the RDF syntax</a></li>
-<li><a href="#example-1-common-usage">Example 1 : Common usage</a></li>
-<li><a href="#example-2-using-the-rdfdatamgr">Example 2 : Using the RDFDataMgr</a></li>
+<li><a href="rdf-input.html">Reading RDF in Jena</a></li>
+<li><a href="rdf-output.html">Writing RDf in Jena</a></li>
+<li><a href="rdfxml_howto.html">Working with RDF/XML parser</a></li>
</ul>
-</li>
-<li><a href="#logging">Logging</a></li>
-<li><a href="#streammanager-and-locationmapper">The StreamManager and LocationMapper</a><ul>
-<li><a href="#configuring-a-streammanager">Configuring a <code>StreamManager</code></a></li>
-<li><a href="#configuring-a-locationmapper">Configuring a <code>LocationMapper</code></a></li>
-</ul>
-</li>
-<li><a href="#advanced-examples">Advanced examples</a><ul>
-<li><a href="#iterating-over-parser-output">Iterating over parser output</a></li>
-<li><a href="#filter-the-output-of-parsing">Filtering the output of parsing</a></li>
-<li><a href="#add-a-new-language">Add a new language</a></li>
-</ul>
-</li>
-</ul>
-<p>Full details of operations are given in the javadoc.</p>
<h2 id="formats">Formats</h2>
<p>The following RDF formats are supported by Jena. In addition, other syntaxes
-can be integrated into the parser framework.</p>
+can be integrated into both the parser and writer registries.</p>
<ul>
<li>Turtle</li>
<li>RDF/XML</li>
@@ -195,8 +177,6 @@ can be integrated into the parser framew
</ul>
<p>RDF/JSON is not JSON-LD - it is a direct encoding of RDF triples in JSON.
See the <a href="rdf-json.html">description of RDF/JSON</a>.</p>
-<p>See also the <a href="arp.html">RDF/XML specific documentation</a> for configuration
-of the RDF/XML parser.</p>
<h2 id="command-line-tools">Command line tools</h2>
<p>There are scripts in Jena download to run these commands.</p>
<ul>
@@ -271,194 +251,6 @@ process:</p>
<p>Output will contain the base data and triples inferred based on
RDF subclass, subproperty, domain and range declarations.</p>
-<h2 id="api">API</h2>
-<p>Much of the functionality is accessed via the Jena Model API; direct
-calling of the RIOT subsystem isn't needed. A resource name
-with no URI scheme is assumed to be a local file name.</p>
-<p>Applications typically use at most <code>RDFDataMgr</code> to read RDF datasets.</p>
-<p>The major classes in the RIOT API are:</p>
-<table>
-<thead>
-<tr>
-<th>Class</th>
-<th>Comment</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td>RDFDataMgr</td>
-<td>Main set of functions to read and load models and datasets</td>
-</tr>
-<tr>
-<td>StreamManager</td>
-<td>Handles the opening of typed input streams</td>
-</tr>
-<tr>
-<td>StreamRDF</td>
-<td>Interface for the output of all parsers</td>
-</tr>
-<tr>
-<td>RDFLanguages</td>
-<td>Registered languages</td>
-</tr>
-<tr>
-<td>RDFParserRegistry</td>
-<td>Registered parser factories</td>
-</tr>
-</tbody>
-</table>
-<h3 id="determining-the-rdf-syntax">Determining the RDF syntax</h3>
-<p>The syntax of the RDF file is determined by the content type (if an HTTP
-request), then the file extension if there is no content type (or it's
-<code>text/plain</code>), which is assumed to be type returned for an unconfigured
-http server. The application can also pass in a declared language hint.</p>
-<p>The following is a suggested Apache httpd .htaccess file:</p>
-<div class="codehilite"><pre><span class="n">AddType</span> <span class="n">text</span><span class="o">/</span><span class="n">turtle</span> <span class="o">.</span><span class="n">ttl</span>
-<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">rdf</span><span class="o">+</span><span class="n">xml</span> <span class="o">.</span><span class="n">rdf</span>
-<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">n</span><span class="o">-</span><span class="n">triples</span> <span class="o">.</span><span class="n">nt</span>
-
-<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">ld</span><span class="o">+</span><span class="n">json</span> <span class="o">.</span><span class="n">jsonld</span>
-<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">owl</span><span class="o">+</span><span class="n">xml</span> <span class="o">.</span><span class="n">owl</span>
-
-<span class="n">AddType</span> <span class="n">text</span><span class="o">/</span><span class="n">trig</span> <span class="o">.</span><span class="n">trig</span>
-<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">n</span><span class="o">-</span><span class="n">quads</span> <span class="o">.</span><span class="n">nq</span>
-</pre></div>
-
-
-<h3 id="example-1-common-usage">Example 1 : Common usage</h3>
-<p>In this example, a file in the current directory is read as Turtle.</p>
-<p>Model model = ModelFactory.createDefaultModel() ;
- model.read("data.ttl") ;</p>
-<p>If the syntax is not as the file extension, a language can be declared:</p>
-<div class="codehilite"><pre><span class="n">model</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span><span class="s">"data.foo"</span><span class="p">,</span> <span class="s">"TURTLE"</span><span class="p">)</span> <span class="p">;</span>
-</pre></div>
-
-
-<h3 id="example-2-using-the-rdfdatamgr">Example 2 : Using the RDFDataMgr</h3>
-<p>In versions of Jena priot to 2.10.0, the <code>FileManager</code> provided some of
-this functionality. It was more basic, and not properly web enabled. The
-<code>RDFDataMgr</code> superceeds the <code>FileManager</code>. "load*" operations create an
-in-memory container (model, or dataset as appropriate); "read" operations
-add data into an existing model or dataset.</p>
-<div class="codehilite"><pre><span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="n">model</span> <span class="ow">and</span> <span class="nb">read</span> <span class="n">into</span> <span class="n">it</span> <span class="n">from</span> <span class="n">file</span>
-<span class="sr">//</span> <span class="s">"data.ttl"</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">Turtle</span><span class="o">.</span>
-<span class="n">Model</span> <span class="n">model</span> <span class="o">=</span> <span class="n">RDFDataMgr</span><span class="o">.</span><span class="n">loadModel</span><span class="p">(</span><span class="s">"data.ttl"</span><span class="p">)</span> <span class="p">;</span>
-
-<span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="n">dataset</span> <span class="ow">and</span> <span class="nb">read</span> <span class="n">into</span> <span class="n">it</span> <span class="n">from</span> <span class="n">file</span>
-<span class="sr">//</span> <span class="s">"data.trig"</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">TriG</span><span class="o">.</span>
-<span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="n">RDFDataMgr</span><span class="o">.</span><span class="n">loadDataset</span><span class="p">(</span><span class="s">"data.trig"</span><span class="p">)</span> <span class="p">;</span>
-
-<span class="sr">//</span> <span class="n">Read</span> <span class="n">into</span> <span class="n">an</span> <span class="n">existing</span> <span class="n">Model</span>
-<span class="n">RDFDataMgr</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="s">"data2.ttl"</span><span class="p">)</span> <span class="p">;</span>
-</pre></div>
-
-
-<h2 id="logging">Logging</h2>
-<p>The parsers log to a logger called <code>org.aapche.jena.riot</code>. To avoid <code>WARN</code>
-messages, set this in log4j.properties to <code>ERROR</code>.</p>
-<h2 id="streammanager-and-locationmapper">StreamManager and LocationMapper</h2>
-<p>By default, the <code>RDFDataMgr</code> uses the global <code>StreamManager</code> to open typed
-InputStreams. This is available to applications via <code>RDFDataMgr.open</code> as well as directly
-using a <code>StreamManager</code>.</p>
-<p>The <code>StreamManager</code> is choosen based on the <code>Context</code> object for the
-oepration, but normally this defaults to the global <code>Context</code> availbale vai
-<code>Context.get()</code>. The constant <code>RDFDataMgr.streamManagerSymbol</code>, which is
-<code>http://jena.apache.org/riot/streamManager</code> is used.</p>
-<p>Specialized StreamManagers can be configured with specific locators for
-data:</p>
-<ul>
-<li>File locator (with own current directory)</li>
-<li>URL locator</li>
-<li>Class loader locator</li>
-<li>Zip file locator</li>
-</ul>
-<h3 id="configuring-a-streammanager">Configuring a <code>StreamManager</code></h3>
-<p>The <code>StreamManager</code> can be reconfigured with different places to look for
-files. The default configuration used for the global <code>StreamManager</code> is
-a file access class, wihere the current directory is that of the java
-process, a URL accessor for reading from the web, and a
-class laoder-based accessor. Different setups can be built and used
-either as the global set up, </p>
-<p>There is also a <code>LocationMapper</code> for rewiting file names and URLs before
-use to allow placing known names in different places (e.g. having local
-copies of import http resources).</p>
-<h3 id="configuring-a-locationmapper">Configuring a <code>LocationMapper</code></h3>
-<p>Location mapping files are RDF, usually written in Turtle although
-an RDF syntax can be used.</p>
-<div class="codehilite"><pre><span class="nv">@prefix</span> <span class="n">lm:</span> <span class="sr"><http://jena.hpl.hp.com/2004/08/location-mapping#></span>
-
-<span class="o">[]</span> <span class="n">lm:mapping</span>
- <span class="p">[</span> <span class="n">lm:name</span> <span class="s">"file:foo.n3"</span> <span class="p">;</span> <span class="n">lm:altName</span> <span class="s">"file:etc/foo.n3"</span> <span class="p">]</span> <span class="p">,</span>
- <span class="p">[</span> <span class="n">lm:prefix</span> <span class="s">"file:etc/"</span> <span class="p">;</span> <span class="n">lm:altPrefix</span> <span class="s">"file:ETC/"</span> <span class="p">]</span> <span class="p">,</span>
- <span class="p">[</span> <span class="n">lm:name</span> <span class="s">"file:etc/foo.n3"</span> <span class="p">;</span> <span class="n">lm:altName</span> <span class="s">"file:DIR/foo.n3"</span> <span class="p">]</span>
- <span class="o">.</span>
-</pre></div>
-
-
-<p>There are two types of location mapping: exact match renaming and
-prefix renaming. When trying to find an alternative location, a
-<code>LocationMapper</code> first tries for an exact match; if none is found,
-the LocationMapper will search for the longest matching prefix. If
-two are the same length, there is no guarantee on order tried;
-there is no implied order in a location mapper configuration file
-(it sets up two hash tables).</p>
-<p>In the example above, <code>file:etc/foo.n3</code> becomes <code>file:DIR/foo.n3</code>
-because that is an exact match. The prefix match of file:/etc/ is
-ignored.</p>
-<p>All string tests are done case sensitively because the primary use
-is for URLs.</p>
-<p>Notes:</p>
-<ul>
-<li>Property values are not URIs, but strings. This is a system
- feature, not an RDF feature. Prefix mapping is name rewriting;
- alternate names are not treated as equivalent resources in the rest
- of Jena. While application writers are encouraged to use URIs to
- identify files, this is not always possible.</li>
-<li>There is no check to see if the alternative system resource is
- equivalent to the original.</li>
-</ul>
-<p>A LocationMapper finds its configuration file by looking for the
-following files, in order:</p>
-<ul>
-<li><code>file:location-mapping.rdf</code></li>
-<li><code>file:location-mapping.ttl</code></li>
-<li><code>file:etc/location-mapping.rdf</code></li>
-<li><code>file:etc/location-mapping.ttl</code></li>
-</ul>
-<p>This is a specified as a path - note the path separator is always
-the character ';' regardless of operating system because URLs
-contain ':'.</p>
-<p>Applications can also set mappings programmatically. No
-configuration file is necessary.</p>
-<p>The base URI for reading models will be the original URI, not the alternative location.</p>
-<h3 id="debugging">Debugging</h3>
-<p>Using log4j, set the logging level of the classes:</p>
-<ul>
-<li>org.apache.jena.riot.stream.StreamManager</li>
-<li>org.apache.jena.riot.stream.LocationMapper</li>
-</ul>
-<h2 id="advanced-examples">Advanced examples</h2>
-<h3 id="iterating-over-parser-output">Iterating over parser output</h3>
-<p>One of the capabilities of the RIOT API is the ability to treat parser output as an iterator,
-this is useful when you don't want to go to the trouble of writing a full sink implementation and can easily express your
-logic in normal iterator style.</p>
-<p>To do this you use one of the subclasses of
-<a href="http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/lang/PipedRDFIterator.java?view=markup">PipedRDFIterator</a>
-in conjunction with a <a href="http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/lang/PipedRDFStream.java?view=markup">PipedRDFStream</a>.</p>
-<p>This <code>PipedRDFStream</code> provides an implementation of <code>StreamRDF</code> which allows it to consume parser output and this is consumed by
-the <code>PipedRDFIterator</code> implementation. This has some advantages over a direct <code>StreamRDF</code> implementation since it allows the parser
-production of data to run ahead of your consumption of data which may result in better overall throughput.</p>
-<p>The only complication is that you need to ensure that the thread feeding the <code>PipedRDFStream</code> and the consumer of the iterator are on different threads
-as otherwise you can run into a deadlock situation where one is waiting on data from the other which is never started.</p>
-<p>See <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_6.java">RIOT example 6</a>
-which shows an example usage including a simple way to push the parser onto a different thread to avoid the possible deadlock.</p>
-<h3 id="filter-the-output-of-parsing">Filter the output of parsing</h3>
-<p>When working with very large files, it can be useful to process the stream of triples or quads produced
-by the parser so as to work in a streaming fashion.</p>
-<p>See <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_4.java">RIOT example 4</a></p>
-<h3 id="add-a-new-language">Add a new language</h3>
-<p>The set of languages is not fixed. A new languages, together with a parser, can be added to RIOT as shown in
-<a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_5.java">RIOT example 5</a></p>
</div>
<div id="footer">
Added: websites/staging/jena/trunk/content/documentation/io/rdf-input.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/rdf-input.html (added)
+++ websites/staging/jena/trunk/content/documentation/io/rdf-input.html Thu Mar 28 17:17:24 2013
@@ -0,0 +1,386 @@
+<!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="/css/jena.css" rel="stylesheet" type="text/css">
+
+ <title>Apache Jena - Reading RDF in Jena</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js" type="text/javascript"></script>
+ <script src="/js/jena-navigation.js" type="text/javascript"></script>
+</head>
+
+<body>
+ <div id="header">
+ <div id="logoblock">
+ <img alt="Apache Jena" src="/images/jena-logo/jena-logo-small.png"/>
+ </div>
+
+ <div id="titleblock">
+ <h1 class="title">Apache Jena</h1>
+ <div id="topmenu" class="tabbar round-10">
+ <ul>
+ <li class="round-top-8"><a class="round-top-8" href="/index.html" id="home_menu">Home</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/help_and_support/index.html">Support</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/getting_started/index.html">Getting started</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/tutorials/index.html">Tutorials</a></li>
+ <li class="round-top-8"><a class="round-top-8" href="/documentation/index.html">Documentation</a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+
+ <div id="navigation" class="clear">
+ <h1 id="quick-links">Quick links</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/download/index.html">Downloads</a></li>
+<li><a href="/help_and_support/index.html">Help and support</a></li>
+<li><a href="/help_and_support/bugs_and_suggestions.html">Report a bug</a></li>
+<li><a href="/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/getting_involved/index.html">Getting involved</a></li>
+<li><a href="/documentation/">Documentation</a></li>
+</ul>
+<h1 id="about-jena">About Jena</h1>
+<ul>
+<li><a href="/index.html">Home</a></li>
+<li><a href="/about_jena/about.html">About Jena</a></li>
+<li><a href="/about_jena/architecture.html">Architecture</a></li>
+<li><a href="/about_jena/roadmap.html">Roadmap</a></li>
+<li><a href="/about_jena/team.html">Project team</a></li>
+<li><a href="/about_jena/contributions.html">Related projects</a></li>
+</ul>
+<h1 id="download">Download</h1>
+<ul>
+<li><a href="/download/index.html">Downloading Jena</a></li>
+<li><a href="/download/maven.html">Using Maven</a></li>
+<li><a href="/download/osgi.html">Using OSGi</a></li>
+</ul>
+<h1 id="help-and-support">Help and support</h1>
+<ul>
+<li><a href="/help_and_support/index.html">Getting help</a></li>
+<li><a href="/help_and_support/bugs_and_suggestions.html">Bugs and suggestions</a></li>
+</ul>
+<h1 id="getting-started">Getting Started</h1>
+<ul>
+<li><a href="/getting_started/index.html">A first Jena project</a></li>
+<li><a href="/getting_started/rdf_api.html">RDF API overview</a></li>
+<li><a href="/getting_started/sparql.html">Querying RDF with SPARQL</a></li>
+<li><a href="/getting_started/fuseki.html">Serving RDF over HTTP</a></li>
+<li><a href="/getting_started/tell_me_how.html">Tell me how to ...</a></li>
+</ul>
+<h1 id="tutorials">Tutorials</h1>
+<ul>
+<li><a href="/tutorials/index.html">Tutorials index</a></li>
+<li><a href="/tutorials/rdf_api.html">RDF tutorial</a></li>
+<li><a href="/tutorials/sparql.html">SPARQL queries</a></li>
+<li><a href="/tutorials/using_jena_with_eclipse.html">Using Jena with Eclipse</a></li>
+</ul>
+<h1 id="documentation">Documentation</h1>
+<ul>
+<li><a href="/documentation/index.html">Overview</a></li>
+<li><a href="/documentation/javadoc/">Javadoc</a></li>
+<li><a href="/documentation/rdf/index.html">RDF</a></li>
+<li><a href="/documentation/io/index.html">I/O</a></li>
+<li><a href="/documentation/query/index.html">SPARQL (ARQ)</a><ul>
+<li><a href="/documentation/query/app_api.html">Application API</a></li>
+<li><a href="/documentation/query/cmds.html">Command line utilities</a></li>
+</ul>
+</li>
+<li><a href="/documentation/tdb/index.html">TDB</a><ul>
+<li><a href="/documentation/tdb/tdb_transactions.html">API for Transactions</a></li>
+<li><a href="/documentation/tdb/assembler.html">Dataset Assembler</a></li>
+</ul>
+</li>
+<li><a href="/documentation/serving_data/index.html">Fuseki: Serving Data</a></li>
+<li><a href="/documentation/ontology/index.html">Ontology</a></li>
+<li><a href="/documentation/inference/index.html">Inference</a></li>
+<li><a href="/documentation/assembler/index.html">Assembler</a><ul>
+<li><a href="/documentation/assembler/assembler-howto.html">Assembler how-to</a></li>
+<li><a href="/documentation/assembler/inside-assemblers.html">Inside assemblers</a></li>
+</ul>
+</li>
+<li><a href="/documentation/sdb/index.html">SDB</a></li>
+<li><a href="/documentation/larq/index.html">LARQ: Free Text Search</a></li>
+<li><a href="/documentation/notes/index.html">Notes</a><ul>
+<li><a href="/documentation/notes/concurrency-howto.html">Concurrency how-to</a></li>
+<li><a href="/documentation/notes/event-handler-howto.html">Event handler how-to</a></li>
+<li><a href="/documentation/notes/file-manager.html">File manager how-to</a></li>
+<li><a href="/documentation/notes/model-factory.html">Model factory how-to</a></li>
+<li><a href="/documentation/notes/rdf-frames.html">RDF frames</a></li>
+<li><a href="/documentation/notes/reification.html">Reification how-to</a></li>
+<li><a href="/documentation/notes/typed-literals.html">Typed literals how-to</a></li>
+<li><a href="/documentation/notes/iri.html">Support for IRI's</a></li>
+<li><a href="/documentation/notes/sse.html">SSE</a></li>
+</ul>
+</li>
+<li><a href="/documentation/tools/index.html">Tools</a><ul>
+<li><a href="/documentation/tools/schemagen.html">schemagen</a></li>
+<li><a href="/documentation/tools/eyeball-getting-started.html">eyeball</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="getting-involved">Getting Involved</h1>
+<ul>
+<li><a href="/getting_involved/index.html">Contributing to Jena</a><ul>
+<li><a href="/getting_involved/reviewing_contributions.html">Reviewing Contributions</a></li>
+</ul>
+</li>
+</ul>
+<h1 id="asf-links">ASF links</h1>
+<ul>
+<li><a href="http://www.apache.org">Apache Software Foundation</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0">License</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">
+ <h1 class="title">Reading RDF in Jena</h1>
+ <p>This page details the setup of RDF I/O technology (RIOT) for input
+introduced in Jena 2.10.</p>
+<p>The output capabilities are described <a href="rdf-output.html">elsewhere</a>.</p>
+<ul>
+<li><a href="#api">API</a><ul>
+<li><a href="#determining-the-rdf-syntax">Determining the RDF syntax</a></li>
+<li><a href="#example-1-common-usage">Example 1 : Common usage</a></li>
+<li><a href="#example-2-using-the-rdfdatamgr">Example 2 : Using the RDFDataMgr</a></li>
+</ul>
+</li>
+<li><a href="#logging">Logging</a></li>
+<li><a href="#streammanager-and-locationmapper">The StreamManager and LocationMapper</a><ul>
+<li><a href="#configuring-a-streammanager">Configuring a <code>StreamManager</code></a></li>
+<li><a href="#configuring-a-locationmapper">Configuring a <code>LocationMapper</code></a></li>
+</ul>
+</li>
+<li><a href="#advanced-examples">Advanced examples</a><ul>
+<li><a href="#iterating-over-parser-output">Iterating over parser output</a></li>
+<li><a href="#filter-the-output-of-parsing">Filtering the output of parsing</a></li>
+<li><a href="#add-a-new-language">Add a new language</a></li>
+</ul>
+</li>
+</ul>
+<p>Full details of operations are given in the javadoc.</p>
+<h2 id="api">API</h2>
+<p>Much of the functionality is accessed via the Jena Model API; direct
+calling of the RIOT subsystem isn't needed. A resource name
+with no URI scheme is assumed to be a local file name.</p>
+<p>Applications typically use at most <code>RDFDataMgr</code> to read RDF datasets.</p>
+<p>The major classes in the RIOT API are:</p>
+<table>
+<thead>
+<tr>
+<th>Class</th>
+<th>Comment</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>RDFDataMgr</td>
+<td>Main set of functions to read and load models and datasets</td>
+</tr>
+<tr>
+<td>StreamManager</td>
+<td>Handles the opening of typed input streams</td>
+</tr>
+<tr>
+<td>StreamRDF</td>
+<td>Interface for the output of all parsers</td>
+</tr>
+<tr>
+<td>RDFLanguages</td>
+<td>Registered languages</td>
+</tr>
+<tr>
+<td>RDFParserRegistry</td>
+<td>Registered parser factories</td>
+</tr>
+</tbody>
+</table>
+<h3 id="determining-the-rdf-syntax">Determining the RDF syntax</h3>
+<p>The syntax of the RDF file is determined by the content type (if an HTTP
+request), then the file extension if there is no content type (or it's
+<code>text/plain</code>), which is assumed to be type returned for an unconfigured
+http server. The application can also pass in a declared language hint.</p>
+<p>The following is a suggested Apache httpd .htaccess file:</p>
+<div class="codehilite"><pre><span class="n">AddType</span> <span class="n">text</span><span class="o">/</span><span class="n">turtle</span> <span class="o">.</span><span class="n">ttl</span>
+<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">rdf</span><span class="o">+</span><span class="n">xml</span> <span class="o">.</span><span class="n">rdf</span>
+<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">n</span><span class="o">-</span><span class="n">triples</span> <span class="o">.</span><span class="n">nt</span>
+
+<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">ld</span><span class="o">+</span><span class="n">json</span> <span class="o">.</span><span class="n">jsonld</span>
+<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">owl</span><span class="o">+</span><span class="n">xml</span> <span class="o">.</span><span class="n">owl</span>
+
+<span class="n">AddType</span> <span class="n">text</span><span class="o">/</span><span class="n">trig</span> <span class="o">.</span><span class="n">trig</span>
+<span class="n">AddType</span> <span class="n">application</span><span class="o">/</span><span class="n">n</span><span class="o">-</span><span class="n">quads</span> <span class="o">.</span><span class="n">nq</span>
+</pre></div>
+
+
+<h3 id="example-1-common-usage">Example 1 : Common usage</h3>
+<p>In this example, a file in the current directory is read as Turtle.</p>
+<p>Model model = ModelFactory.createDefaultModel() ;
+ model.read("data.ttl") ;</p>
+<p>If the syntax is not as the file extension, a language can be declared:</p>
+<div class="codehilite"><pre><span class="n">model</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span><span class="s">"data.foo"</span><span class="p">,</span> <span class="s">"TURTLE"</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<h3 id="example-2-using-the-rdfdatamgr">Example 2 : Using the RDFDataMgr</h3>
+<p>In versions of Jena priot to 2.10.0, the <code>FileManager</code> provided some of
+this functionality. It was more basic, and not properly web enabled. The
+<code>RDFDataMgr</code> superceeds the <code>FileManager</code>. "load*" operations create an
+in-memory container (model, or dataset as appropriate); "read" operations
+add data into an existing model or dataset.</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="n">model</span> <span class="ow">and</span> <span class="nb">read</span> <span class="n">into</span> <span class="n">it</span> <span class="n">from</span> <span class="n">file</span>
+<span class="sr">//</span> <span class="s">"data.ttl"</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">Turtle</span><span class="o">.</span>
+<span class="n">Model</span> <span class="n">model</span> <span class="o">=</span> <span class="n">RDFDataMgr</span><span class="o">.</span><span class="n">loadModel</span><span class="p">(</span><span class="s">"data.ttl"</span><span class="p">)</span> <span class="p">;</span>
+
+<span class="sr">//</span> <span class="n">Create</span> <span class="n">a</span> <span class="n">dataset</span> <span class="ow">and</span> <span class="nb">read</span> <span class="n">into</span> <span class="n">it</span> <span class="n">from</span> <span class="n">file</span>
+<span class="sr">//</span> <span class="s">"data.trig"</span> <span class="n">assumed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">TriG</span><span class="o">.</span>
+<span class="n">Dataset</span> <span class="n">dataset</span> <span class="o">=</span> <span class="n">RDFDataMgr</span><span class="o">.</span><span class="n">loadDataset</span><span class="p">(</span><span class="s">"data.trig"</span><span class="p">)</span> <span class="p">;</span>
+
+<span class="sr">//</span> <span class="n">Read</span> <span class="n">into</span> <span class="n">an</span> <span class="n">existing</span> <span class="n">Model</span>
+<span class="n">RDFDataMgr</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="s">"data2.ttl"</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<h2 id="logging">Logging</h2>
+<p>The parsers log to a logger called <code>org.aapche.jena.riot</code>. To avoid <code>WARN</code>
+messages, set this in log4j.properties to <code>ERROR</code>.</p>
+<h2 id="streammanager-and-locationmapper">StreamManager and LocationMapper</h2>
+<p>By default, the <code>RDFDataMgr</code> uses the global <code>StreamManager</code> to open typed
+InputStreams. This is available to applications via <code>RDFDataMgr.open</code> as well as directly
+using a <code>StreamManager</code>.</p>
+<p>The <code>StreamManager</code> is choosen based on the <code>Context</code> object for the
+oepration, but normally this defaults to the global <code>Context</code> availbale vai
+<code>Context.get()</code>. The constant <code>RDFDataMgr.streamManagerSymbol</code>, which is
+<code>http://jena.apache.org/riot/streamManager</code> is used.</p>
+<p>Specialized StreamManagers can be configured with specific locators for
+data:</p>
+<ul>
+<li>File locator (with own current directory)</li>
+<li>URL locator</li>
+<li>Class loader locator</li>
+<li>Zip file locator</li>
+</ul>
+<h3 id="configuring-a-streammanager">Configuring a <code>StreamManager</code></h3>
+<p>The <code>StreamManager</code> can be reconfigured with different places to look for
+files. The default configuration used for the global <code>StreamManager</code> is
+a file access class, wihere the current directory is that of the java
+process, a URL accessor for reading from the web, and a
+class laoder-based accessor. Different setups can be built and used
+either as the global set up, </p>
+<p>There is also a <code>LocationMapper</code> for rewiting file names and URLs before
+use to allow placing known names in different places (e.g. having local
+copies of import http resources).</p>
+<h3 id="configuring-a-locationmapper">Configuring a <code>LocationMapper</code></h3>
+<p>Location mapping files are RDF, usually written in Turtle although
+an RDF syntax can be used.</p>
+<div class="codehilite"><pre><span class="nv">@prefix</span> <span class="n">lm:</span> <span class="sr"><http://jena.hpl.hp.com/2004/08/location-mapping#></span>
+
+<span class="o">[]</span> <span class="n">lm:mapping</span>
+ <span class="p">[</span> <span class="n">lm:name</span> <span class="s">"file:foo.n3"</span> <span class="p">;</span> <span class="n">lm:altName</span> <span class="s">"file:etc/foo.n3"</span> <span class="p">]</span> <span class="p">,</span>
+ <span class="p">[</span> <span class="n">lm:prefix</span> <span class="s">"file:etc/"</span> <span class="p">;</span> <span class="n">lm:altPrefix</span> <span class="s">"file:ETC/"</span> <span class="p">]</span> <span class="p">,</span>
+ <span class="p">[</span> <span class="n">lm:name</span> <span class="s">"file:etc/foo.n3"</span> <span class="p">;</span> <span class="n">lm:altName</span> <span class="s">"file:DIR/foo.n3"</span> <span class="p">]</span>
+ <span class="o">.</span>
+</pre></div>
+
+
+<p>There are two types of location mapping: exact match renaming and
+prefix renaming. When trying to find an alternative location, a
+<code>LocationMapper</code> first tries for an exact match; if none is found,
+the LocationMapper will search for the longest matching prefix. If
+two are the same length, there is no guarantee on order tried;
+there is no implied order in a location mapper configuration file
+(it sets up two hash tables).</p>
+<p>In the example above, <code>file:etc/foo.n3</code> becomes <code>file:DIR/foo.n3</code>
+because that is an exact match. The prefix match of file:/etc/ is
+ignored.</p>
+<p>All string tests are done case sensitively because the primary use
+is for URLs.</p>
+<p>Notes:</p>
+<ul>
+<li>Property values are not URIs, but strings. This is a system
+ feature, not an RDF feature. Prefix mapping is name rewriting;
+ alternate names are not treated as equivalent resources in the rest
+ of Jena. While application writers are encouraged to use URIs to
+ identify files, this is not always possible.</li>
+<li>There is no check to see if the alternative system resource is
+ equivalent to the original.</li>
+</ul>
+<p>A LocationMapper finds its configuration file by looking for the
+following files, in order:</p>
+<ul>
+<li><code>file:location-mapping.rdf</code></li>
+<li><code>file:location-mapping.ttl</code></li>
+<li><code>file:etc/location-mapping.rdf</code></li>
+<li><code>file:etc/location-mapping.ttl</code></li>
+</ul>
+<p>This is a specified as a path - note the path separator is always
+the character ';' regardless of operating system because URLs
+contain ':'.</p>
+<p>Applications can also set mappings programmatically. No
+configuration file is necessary.</p>
+<p>The base URI for reading models will be the original URI, not the alternative location.</p>
+<h3 id="debugging">Debugging</h3>
+<p>Using log4j, set the logging level of the classes:</p>
+<ul>
+<li>org.apache.jena.riot.stream.StreamManager</li>
+<li>org.apache.jena.riot.stream.LocationMapper</li>
+</ul>
+<h2 id="advanced-examples">Advanced examples</h2>
+<h3 id="iterating-over-parser-output">Iterating over parser output</h3>
+<p>One of the capabilities of the RIOT API is the ability to treat parser output as an iterator,
+this is useful when you don't want to go to the trouble of writing a full sink implementation and can easily express your
+logic in normal iterator style.</p>
+<p>To do this you use one of the subclasses of
+<a href="http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/lang/PipedRDFIterator.java?view=markup">PipedRDFIterator</a>
+in conjunction with a <a href="http://svn.apache.org/viewvc/jena/trunk/jena-arq/src/main/java/org/apache/jena/riot/lang/PipedRDFStream.java?view=markup">PipedRDFStream</a>.</p>
+<p>This <code>PipedRDFStream</code> provides an implementation of <code>StreamRDF</code> which allows it to consume parser output and this is consumed by
+the <code>PipedRDFIterator</code> implementation. This has some advantages over a direct <code>StreamRDF</code> implementation since it allows the parser
+production of data to run ahead of your consumption of data which may result in better overall throughput.</p>
+<p>The only complication is that you need to ensure that the thread feeding the <code>PipedRDFStream</code> and the consumer of the iterator are on different threads
+as otherwise you can run into a deadlock situation where one is waiting on data from the other which is never started.</p>
+<p>See <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_6.java">RIOT example 6</a>
+which shows an example usage including a simple way to push the parser onto a different thread to avoid the possible deadlock.</p>
+<h3 id="filter-the-output-of-parsing">Filter the output of parsing</h3>
+<p>When working with very large files, it can be useful to process the stream of triples or quads produced
+by the parser so as to work in a streaming fashion.</p>
+<p>See <a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_4.java">RIOT example 4</a></p>
+<h3 id="add-a-new-language">Add a new language</h3>
+<p>The set of languages is not fixed. A new languages, together with a parser, can be added to RIOT as shown in
+<a href="https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_5.java">RIOT example 5</a></p>
+ </div>
+
+ <div id="footer">
+ <div class="copyright">
+ <p>
+ Copyright © 2011–2013 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 Jena, Jena, the Apache Jena project logo,
+ Apache and the Apache feather logos are trademarks of The Apache Software Foundation.
+ </p>
+ </div>
+ </div>
+
+</body>
+</html>
Modified: websites/staging/jena/trunk/content/documentation/io/rdf-output.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/rdf-output.html (original)
+++ websites/staging/jena/trunk/content/documentation/io/rdf-output.html Thu Mar 28 17:17:24 2013
@@ -21,7 +21,7 @@
<link href="/css/jena.css" rel="stylesheet" type="text/css">
- <title>Apache Jena - RDF Output</title>
+ <title>Apache Jena - Writing RDF in Apache Jena</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js" type="text/javascript"></script>
<script src="/js/jena-navigation.js" type="text/javascript"></script>
@@ -155,93 +155,383 @@
</div>
<div id="content">
- <h1 class="title">RDF Output</h1>
- <p>See the <a href="rdfxml_howto.html#advanced-rdfxml-output">Jena RDF/XML How-To</a> for details of RDF/XML and
-RDF/XML-ABBREV configuration.</p>
-<h2 id="advanced-turtle-output">Advanced Turtle Output</h2>
-<p>The Turtle pretty printer (which is used by default)Â and the Turtle plain
-writer provide a number of properties to control their output. The
-properties all start: <code>http://jena.hpl.hp.com/n3/properties/</code>. The
-name used can be the full name, starting with this string, or the
-short form of just the name below. All values are strings; they
-may be interpreted as integer, boolean or string as defined below.</p>
-<h3 id="properties-to-control-turtle-output">Properties to Control Turtle Output</h3>
+ <h1 class="title">Writing RDF in Apache Jena</h1>
+ <p>This page describes the RIOT (RDF I/O technology) output capabilities.</p>
+<p>See <a href="index.html">Reading RDF</a> for details of the RIOT Reader system.</p>
+<p>See <a href="rdfxml_howto.html#advanced-rdfxml-output">Advanced RDF/XML Output</a>
+for details of the Jena RDF/XML writer.</p>
+<ul>
+<li><a href="#API">API</a></li>
+<li><a href="#rdfformat">RDFFormat</a></li>
+<li><a href="#rdfformats-and-jena-syntax-names"><code>RDFFormat</code>s and Jena syntax names</a></li>
+<li><a href="#formats">Formats</a></li>
+<li><a href="#normal-printing">Normal Printing</a></li>
+<li><a href="#pretty-printed-formats">Pretty Printed Languages</a></li>
+<li><a href="#streamed-block-formats">Streamed Block Formats</a></li>
+<li><a href="#line-printed-formats">Line printed formats</a></li>
+<li><a href="#n-triples-and-n-quads">N-triples and N-Quads</a></li>
+<li><a href="#rdfxml">RDF/XML</a></li>
+<li><a href="#examples">Examples</a></li>
+<li><a href="#Notes">Notes</a></li>
+</ul>
+<h2 id="api">API</h2>
+<p>There are two ways to write RDF data using Apache Jena RIOT,
+either via the <code>RDFDataMgr</code> </p>
+<div class="codehilite"><pre><span class="n">RDFDataMgr</span><span class="o">.</span><span class="nb">write</span><span class="p">(</span><span class="n">OutputStream</span><span class="p">,</span> <span class="n">Model</span><span class="p">,</span> <span class="n">RDFFormat</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">RDFDataMgr</span><span class="o">.</span><span class="nb">write</span><span class="p">(</span><span class="n">OutputStream</span><span class="p">,</span> <span class="n">Dataset</span><span class="p">,</span> <span class="n">RDFFormat</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>or using the <code>model</code> API:</p>
+<div class="codehilite"><pre><span class="n">model</span><span class="o">.</span><span class="nb">write</span><span class="p">(</span><span class="n">output</span><span class="p">,</span> <span class="s">"format"</span><span class="p">)</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>The <em><code>format</code></em> names are described below; they are a superset of the
+names Jena has supported before RIOT.</p>
+<p>Many variations of these methods exist. See the full javadoc for details.</p>
+<h2 id="rdfformat"><code>RDFFormat</code></h2>
+<p>Output using RIOT depends on the format, which involves both the language (syntax)
+being written and the variant of that syntax. </p>
+<p>The RIOT writer architecture is extensible. The following languages
+are available as part of the standard setup.</p>
+<ul>
+<li>Turtle</li>
+<li>N-Triples</li>
+<li>RDF/XML</li>
+<li>RDF/JSON</li>
+<li>TriG</li>
+<li>NQuads</li>
+</ul>
+<p>In addition, there are variants of Trutle, TriG for pretty printing,
+streamed output and flat output. RDF/XML has variants for pretty printing
+and plain output. Jena RIOT uses <code>org.apache.jena.riot.RDFFormat</code> as a way
+to identfy the language and variant to be written. The class contains constants
+for the standard supported formats.</p>
+<p>Note:</p>
+<ul>
+<li>RDF/JSON is not JSON-LD. See the <a href="rdf-json.html">description of RDF/JSON</a>.</li>
+<li>N3 is treated as Turtle for output.</li>
+</ul>
+<h2 id="rdfformats-and-jena-syntax-names"><code>RDFFormat</code>s and Jena syntax names</h2>
+<p>The string name traditionally used in <code>model.write</code> is mapped to RIOT <code>RDFFormat</code>
+as follows:</p>
<table>
<thead>
<tr>
-<th>Property Name</th>
-<th>Description</th>
-<th>Default</th>
-<th>Legal Values of String</th>
+<th>Jena writer name</th>
+<th>RIOT RDFFormat</th>
</tr>
</thead>
<tbody>
<tr>
-<td><code>minGap</code></td>
-<td>Minimum gap between items on a line</td>
-<td>1</td>
-<td>positive integer</td>
+<td><code>"TURTLE"</code></td>
+<td><code>TURTLE</code></td>
+</tr>
+<tr>
+<td><code>"TTL"</code></td>
+<td><code>TURTLE</code></td>
+</tr>
+<tr>
+<td><code>"Turtle"</code></td>
+<td><code>TURTLE</code></td>
+</tr>
+<tr>
+<td><code>"N-TRIPLES"</code></td>
+<td><code>NTRIPLES</code></td>
</tr>
<tr>
-<td><code>objectLists</code></td>
-<td>Print object lists as comma separated lists</td>
-<td><code>true</code></td>
-<td>boolean <code>"true"</code> or <code>"false"</code></td>
+<td><code>"N-TRIPLE"</code></td>
+<td><code>NTRIPLES</code></td>
</tr>
<tr>
-<td><code>subjectColumn</code></td>
-<td>If the subject is shorter than this value, the first property may go on the same line.</td>
-<td><code>indentProperty</code></td>
-<td>positive integer</td>
+<td><code>"NT"</code></td>
+<td><code>NTRIPLES</code></td>
</tr>
<tr>
-<td><code>propertyColumn</code></td>
-<td>Width of the property column</td>
-<td>8</td>
-<td>positive integer</td>
+<td><code>"RDF/XML-ABBREV"</code></td>
+<td><code>RDFXML</code></td>
</tr>
<tr>
-<td><code>indentProperty</code></td>
-<td>Width to indent properties</td>
-<td>6</td>
-<td>positive integer</td>
+<td><code>"RDF/XML"</code></td>
+<td><code>RDFXML_PLAIN</code></td>
+</tr>
+<tr>
+<td><code>"N3"</code></td>
+<td><code>N3</code></td>
+</tr>
+<tr>
+<td><code>"RDF/JSON"</code></td>
+<td><code>RDFJSON</code></td>
+</tr>
+</tbody>
+</table>
+<h2 id="formats">Formats</h2>
+<h3 id="normal-printing">Normal Printing</h3>
+<p>A <code>Lang</code> can be used for the writer format, in which case it is mapped to
+an <code>RDFFormat</code> internally. The normal writers are:</p>
+<table>
+<thead>
+<tr>
+<th>RDFFormat or Lang</th>
+<th></th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>TURTLE</td>
+<td>Turtle, pretty printed</td>
</tr>
<tr>
-<td><code>widePropertyLen</code></td>
-<td>Width of the property column</td>
-<td>20</td>
-<td>integer, greater than <code>propertyColumn</code></td>
+<td>TTL</td>
+<td>Same</td>
</tr>
<tr>
-<td><code>abbrevBaseURI</code></td>
-<td>Control whether to use abbreviations <code><></code> or <code><#></code></td>
-<td>true</td>
-<td>boolean <code>"true"</code> or <code>"false"</code></td>
+<td>NTRIPLES</td>
+<td>N-triples</td>
</tr>
<tr>
-<td><code>usePropertySymbols</code></td>
-<td>Control whether to use <code>"a"</code>, <code>"="</code> and <code>"=\>"</code> in output</td>
-<td>true</td>
-<td>boolean <code>"true"</code> or <code>"false"</code></td>
+<td>TRIG</td>
+<td>TriG, pretty printed</td>
</tr>
<tr>
-<td><code>useTripleQuotedStrings</code></td>
-<td>Allow the use of <code>"""</code> to delimit long strings</td>
-<td>true</td>
-<td>boolean <code>"true"</code> or <code>"false"</code></td>
+<td>NQUADS</td>
+<td></td>
+</tr>
+<tr>
+<td>RDFXML</td>
+<td>RDF/XML, pretty printed</td>
+</tr>
+</tbody>
+</table>
+<p>Pretty printed RDF/XML is also known as RDF/XML-ABBREV</p>
+<h3 id="pretty-printed-languages">Pretty Printed Languages</h3>
+<p>All Turtle and TriG formats use
+prefix names, and short forms for literals.</p>
+<p>The pretty printed versions of Turtle and TriG prints
+data with the same subject in the same graph together.
+All the properties for a given subject are sorted
+into a predefined order. RDF lists are printed as
+<code>(...)</code> and <code>[...]</code> is used for blank nodes where possible.<br />
+</p>
+<p>The analysis for determing what can be pretty printed requires
+temporary datastructures and also a scan of the whole graph before
+writing begins. Therefore, pretty printed formats are not suitable
+for writing persistent graphs and datasets.</p>
+<p>When writing at scale use either a "blocked" version of Turtle or TriG,
+or write N-triples/N-Quads.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nv">@prefix</span> <span class="p">:</span> <span class="sr"><http://example/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">dc:</span> <span class="sr"><http://purl.org/dc/elements/1.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">rdf:</span> <span class="sr"><http://www.w3.org/1999/02/22-rdf-syntax-ns#></span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">book</span> <span class="n">dc:author</span> <span class="p">(</span> <span class="p">:</span><span class="n">a</span> <span class="p">:</span><span class="n">b</span> <span class="p">)</span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">a</span> <span class="n">a</span> <span class="n">foaf:Person</span> <span class="p">;</span>
+ <span class="n">foaf:knows</span> <span class="p">[</span> <span class="n">foaf:name</span> <span class="s">"Bob"</span> <span class="p">]</span> <span class="p">;</span>
+ <span class="n">foaf:name</span> <span class="s">"Alice"</span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">b</span> <span class="n">foaf:knows</span> <span class="p">:</span><span class="n">a</span> <span class="o">.</span>
+</pre></div>
+
+
+<p>Pretty printed formats:</p>
+<table>
+<thead>
+<tr>
+<th>RDFFormat</th>
+<th>Same as</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>TURTLE_PRETTY</td>
+<td>TURTLE, TTL</td>
+</tr>
+<tr>
+<td>TRIG_PRETTY</td>
+<td>TRIG</td>
+</tr>
+<tr>
+<td>RDFXML_PRETTY</td>
+<td>RDFXML_ABBREV, RDFXML</td>
+</tr>
+</tbody>
+</table>
+<h3 id="streamed-block-formats">Streamed Block Formats</h3>
+<p>The streamed formats write triples or quads as given.<br />
+They group together data by adjacent subject or graph/subject
+in the output stream.</p>
+<p>The written data is like the pretty printed forms but without
+RDF lists being written in the '(...)' form, and it does not
+use the blank node form <code>[...]</code>.</p>
+<p>This gives some degree of readability while not requiring
+excessive temporary datastructure. Data larger than the size of RAM
+can be written but blank node labels need to be tracked in order
+to use the short label form.</p>
+<p>Example:</p>
+<div class="codehilite"><pre><span class="nv">@prefix</span> <span class="p">:</span> <span class="sr"><http://example/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">dc:</span> <span class="sr"><http://purl.org/dc/elements/1.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">rdf:</span> <span class="sr"><http://www.w3.org/1999/02/22-rdf-syntax-ns#></span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">book</span> <span class="n">dc:author</span> <span class="n">_:b0</span> <span class="o">.</span>
+
+<span class="n">_:b0</span> <span class="n">rdf:rest</span> <span class="n">_:b1</span> <span class="p">;</span>
+ <span class="n">rdf:first</span> <span class="p">:</span><span class="n">a</span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">a</span> <span class="n">foaf:knows</span> <span class="n">_:b2</span> <span class="p">;</span>
+ <span class="n">foaf:name</span> <span class="s">"Alice"</span> <span class="p">;</span>
+ <span class="n">rdf:type</span> <span class="n">foaf:Person</span> <span class="o">.</span>
+
+<span class="n">_:b2</span> <span class="n">foaf:name</span> <span class="s">"Bob"</span> <span class="o">.</span>
+
+<span class="p">:</span><span class="n">b</span> <span class="n">foaf:knows</span> <span class="p">:</span><span class="n">a</span> <span class="o">.</span>
+
+<span class="n">_:b1</span> <span class="n">rdf:rest</span> <span class="n">rdf:nil</span> <span class="p">;</span>
+ <span class="n">rdf:first</span> <span class="p">:</span><span class="n">b</span> <span class="o">.</span>
+</pre></div>
+
+
+<p>Formats:</p>
+<table>
+<thead>
+<tr>
+<th>RDFFormat</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>TURTLE_BLOCKS</td>
+</tr>
+<tr>
+<td>TRIG_BLOCKS</td>
+</tr>
+</tbody>
+</table>
+<h3 id="line-printed">Line printed</h3>
+<p>There are writers for Turtle and Trig that use the abbreviated formats for
+prefix names and short forms for literals. They write each triple or quad
+on a single line.</p>
+<p>The regularity of the output can be useful for test processing data.<br />
+These formats do not offer more scalabilty than the stream forms.</p>
+<p>Example:</p>
+<p>The FLAT writers abbreviates IRIs, literals and blank node labels
+but always writes one complete triple on one line (no use of <code>;</code>).</p>
+<div class="codehilite"><pre><span class="nv">@prefix</span> <span class="p">:</span> <span class="sr"><http://example/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">dc:</span> <span class="sr"><http://purl.org/dc/elements/1.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">foaf:</span> <span class="sr"><http://xmlns.com/foaf/0.1/></span> <span class="o">.</span>
+<span class="nv">@prefix</span> <span class="n">rdf:</span> <span class="sr"><http://www.w3.org/1999/02/22-rdf-syntax-ns#></span> <span class="o">.</span>
+<span class="n">_:b0</span> <span class="n">foaf:name</span> <span class="s">"Bob"</span> <span class="o">.</span>
+<span class="p">:</span><span class="n">book</span> <span class="n">dc:author</span> <span class="n">_:b1</span> <span class="o">.</span>
+<span class="n">_:b2</span> <span class="n">rdf:rest</span> <span class="n">rdf:nil</span> <span class="o">.</span>
+<span class="n">_:b2</span> <span class="n">rdf:first</span> <span class="p">:</span><span class="n">b</span> <span class="o">.</span>
+<span class="p">:</span><span class="n">a</span> <span class="n">foaf:knows</span> <span class="n">_:b0</span> <span class="o">.</span>
+<span class="p">:</span><span class="n">a</span> <span class="n">foaf:name</span> <span class="s">"Alice"</span> <span class="o">.</span>
+<span class="p">:</span><span class="n">a</span> <span class="n">rdf:type</span> <span class="n">foaf:Person</span> <span class="o">.</span>
+<span class="n">_:b1</span> <span class="n">rdf:rest</span> <span class="n">_:b2</span> <span class="o">.</span>
+<span class="n">_:b1</span> <span class="n">rdf:first</span> <span class="p">:</span><span class="n">a</span> <span class="o">.</span>
+<span class="p">:</span><span class="n">b</span> <span class="n">foaf:knows</span> <span class="p">:</span><span class="n">a</span> <span class="o">.</span>
+</pre></div>
+
+
+<p> </p>
+
+<table>
+<thead>
+<tr>
+<th>RDFFormat</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>TURTLE_FLAT</td>
+</tr>
+<tr>
+<td>TRIG_FLAT</td>
+</tr>
+</tbody>
+</table>
+<h3 id="n-triples-and-n-quads">N-triples and N-Quads</h3>
+<p>These provide the formats that are fastest to write,
+and data of any size can be output. They do not use any
+internal state. They maximise the
+interoperability with other systems and are useful
+for database dumps. They are not human readable,
+even at moderate scale.</p>
+<p>The files can be large but they compress well with gzip.
+Compression ratios of x8-x10 can often be obtained.</p>
+<p>Example:</p>
+<p>The N-Triples writer makes no attempt to make it's output readable.
+It uses internal blank nodes to ensure correct labeling without
+needing any writer state.</p>
+<div class="codehilite"><pre><span class="err">_:BX2Dc2b3371X3A13cf8faaf53X3AX2D7fff</span> <span class="err"><http:</span><span class="c1">//xmlns.com/foaf/0.1/name> "Bob" .</span>
+<span class="err"><http:</span><span class="c1">//example/book> <http://purl.org/dc/elements/1.1/author> _:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffe .</span>
+<span class="err">_:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffd</span> <span class="err"><http:</span><span class="c1">//www.w3.org/1999/02/22-rdf-syntax-ns#rest> <http://www.w3.org/1999/02/22-rdf-syntax-ns#nil> .</span>
+<span class="err">_:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffd</span> <span class="err"><http:</span><span class="c1">//www.w3.org/1999/02/22-rdf-syntax-ns#first> <http://example/b> .</span>
+<span class="err"><http:</span><span class="c1">//example/a> <http://xmlns.com/foaf/0.1/knows> _:BX2Dc2b3371X3A13cf8faaf53X3AX2D7fff .</span>
+<span class="err"><http:</span><span class="c1">//example/a> <http://xmlns.com/foaf/0.1/name> "Alice" .</span>
+<span class="err"><http:</span><span class="c1">//example/a> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .</span>
+<span class="err">_:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffe</span> <span class="err"><http:</span><span class="c1">//www.w3.org/1999/02/22-rdf-syntax-ns#rest> _:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffd .</span>
+<span class="err">_:BX2Dc2b3371X3A13cf8faaf53X3AX2D7ffe</span> <span class="err"><http:</span><span class="c1">//www.w3.org/1999/02/22-rdf-syntax-ns#first> <http://example/a> .</span>
+<span class="err"><http:</span><span class="c1">//example/b> <http://xmlns.com/foaf/0.1/knows> <http://example/a> .</span>
+</pre></div>
+
+
+<p> </p>
+
+<table>
+<thead>
+<tr>
+<th>RDFFormat</th>
+<th>Other names</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>NTRIPLE</td>
+<td>NTRIPLE, NT, NQ</td>
+</tr>
+<tr>
+<td>NQUADS</td>
+<td>NQUADS</td>
+</tr>
+</tbody>
+</table>
+<h3 id="rdfxml">RDF/XML</h3>
+<p>RIOT supports output in RDF/XML. RIOT RDFFormats defaults to pretty printed RDF/XML,
+while the jena writer writer name defaults to a streaming plain output.</p>
+<table>
+<thead>
+<tr>
+<th>RDFFormat</th>
+<th>Other names</th>
+<th>Jena writer name</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>RDFXML</td>
+<td>RDFXML_PRETTY, RDF_XML_ABBREV</td>
+<td>"RDF/XML-ABBREV"</td>
</tr>
<tr>
-<td><code>useDoubles</code></td>
-<td>Allow the use doubles as 123.456</td>
-<td>true</td>
-<td>boolean <code>"true"</code> or <code>"false"</code></td>
+<td>RDFXML_PLAIN</td>
+<td></td>
+<td>"RDF/XML"</td>
</tr>
</tbody>
</table>
-<p>Notes:</p>
-<ol>
-<li>Only the Turtle pretty printer print object lists as comma-separated lists.</li>
-</ol>
+<h2 id="examples">Examples</h2>
+<p>@@TODO</p>
+<h2 id="notes">Notes</h2>
+<p>Using <code>OutputStream</code>s is strongly encouraged. This allows the writers
+to manage the character encoding using UTF-8. Using <code>java.io.Writer</code>
+does not allow this; on platforms such as MS Windows, the default
+configuration of a <code>Writer</code> is not suitable for Turtle because
+the characte set is the platform default, and not UTF-8.
+The only use of wirters that is useful is using <code>java.io.StringWriter</code>.</p>
</div>
<div id="footer">
Modified: websites/staging/jena/trunk/content/documentation/io/rdfxml_howto.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/rdfxml_howto.html (original)
+++ websites/staging/jena/trunk/content/documentation/io/rdfxml_howto.html Thu Mar 28 17:17:24 2013
@@ -178,6 +178,7 @@ advanced features within the RDF/XML I/O
<li><a href="#advanced-rdfxml-output">Advanced RDF/XML Output</a></li>
<li><a href="#conformance">Conformance</a></li>
<li><a href="#faster-rdfxml-io">Faster RDF/XML I/O</a></li>
+<li><a href="arp.html">Details of ARP, the Jena RDF/XML parser</a></li>
</ul>
<h2 id="quick-introduction">Quick Introduction</h2>
<p>The main I/O methods in Jena use <code>InputStream</code>s and <code>OutputStream</code>s.