jena-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r844519 [2/6] - in /websites/staging/jena/trunk/content: ./ about_jena/ documentation/ documentation/assembler/ documentation/inference/ documentation/io/ documentation/javadoc/ documentation/larq/ documentation/notes/ documentation/ontolog...
Date Tue, 01 Jan 2013 15:28:12 GMT
Added: websites/staging/jena/trunk/content/documentation/io/arp_howto.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/arp_howto.html (added)
+++ websites/staging/jena/trunk/content/documentation/io/arp_howto.html Tue Jan  1 15:28:10 2013
@@ -0,0 +1,809 @@
+<!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 - Jena RDF/XML How-To</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></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">Jena RDF/XML How-To</h1>
+    <p>This is a guide to the RDF/XML I/O subsystem of Jena, ARP.
+The first section gives a quick introduction to the
+I/O subsystem. The other sections are aimed at users wishing to use
+advanced features within the RDF/XML I/O subsystem.</p>
+<h2 id="contents">Contents</h2>
+<ul>
+<li><a href="#quick-introduction">Quick Introduction</a></li>
+<li><a href="#rdfxml-rdfxml-abbrev">RDF/XML, RDF/XML-ABBREV</a></li>
+<li><a href="#character-encoding-issues">Character Encoding Issues</a><ul>
+<li><a href="#encodings-supported-in-jena-22-and-later">Encodings Supported in Jena 2.2 and later</a></li>
+</ul>
+</li>
+<li><a href="#when-to-use-reader-and-writer">When to Use Reader and Writer?</a></li>
+<li><a href="#introduction-to-advanced-jena-io">Introduction to Advanced Jena I/O</a></li>
+<li><a href="#advanced-rdfxml-input">Advanced RDF/XML Input</a><ul>
+<li><a href="#arp-properties">ARP properties</a></li>
+<li><a href="#interrupting-arp">Interrupting ARP</a></li>
+</ul>
+</li>
+<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>
+</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.
+This is import to correctly handle character sets.</p>
+<p>These methods are found on the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> interface.
+These are:</p>
+<ul>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream, java.lang.String)"><code>read</code></a><code>(java.io.InputStream in, java.lang.String base)</code>
+  <br />Add statements from an RDF/XML serialization</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream, java.lang.String, java.lang.String)"><code>read</code></a><code>(java.io.InputStream in, java.lang.String base, java.lang.String lang)</code>
+  <br /> Add RDF statements represented in language <code>lang</code> to the model.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.lang.String)"><code>read</code></a><code>(java.lang.String url)</code>
+  <br />Add the RDF statements from an XML document.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream)"><code>write</code></a><code>(java.io.OutputStream out)</code>
+  <br /> Write the model as an XML document.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream, java.lang.String)"><code>write</code></a><code>(java.io.OutputStream out, java.lang.String lang)</code>
+  <br />Write a serialized representation of a model in a specified language.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream, java.lang.String, java.lang.String)"><code>write</code></a><code>(java.io.OutputStream out, java.lang.String lang, java.lang.String base)</code>
+  <br />Write a serialized representation of a model in a specified language.</li>
+</ul>
+<p>The built-in languages are <code>"RDF/XML"</code>, <code>"RDF/XML-ABBREV"</code> as well as 
+<code>"N-TRIPLE"</code>, and <code>"TURTLE"</code>.</p>
+<p>There are also methods which use <code>Reader</code>s and <code>Writer</code>s. Do not use
+them, unless you are sure it is correct to. In advanced
+applications, they are useful, see <a href="#reader-writer">below</a>; and
+there is every intention to continue to support them. The RDF/XML
+parser now checks to see if the <code>Model.read(Reader …)</code> calls
+are being abused, and issues
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#ERR_ENCODING_MISMATCH"><code>ERR_ENCODING_MISMATCH</code></a>
+and
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#WARN_ENCODING_MISMATCH"><code>WARN_ENCODING_MISMATCH</code></a>
+errors. Most incorrect usage of <code>Reader</code>s for RDF/XML input will
+result in such errors. Most incorrect usage of <code>Writer</code>s for RDF/XML
+output will produce correct XML by using an appropriate XML
+declaration giving the encoding - e.g.</p>
+<div class="codehilite"><pre><span class="sr">&lt;?xml version=&#39;1.0&#39; encoding=&#39;ISO-8859-15&#39;?&gt;</span>
+</pre></div>
+
+
+<p>However, such XML is less portable than XML in UTF-8. Using the
+<code>Model.write(OutputStream …)</code> methods allows the Jena system
+code to choose UTF-8 encoding, which is the best choice.</p>
+<h2 id="rdfxml-rdfxml-abbrev">RDF/XML, RDF/XML-ABBREV</h2>
+<p>For input, both of these are the same, and fully implement the
+<a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF Syntax Recommendation</a>,
+see <a href="#conformance">conformance</a>.</p>
+<p>For output, <code>"RDF/XML"</code>, produces regular output reasonably
+efficiently, but it is not readable. In contrast,
+<code>"RDF/XML-ABBREV"</code>, produces readable output without much regard to
+efficiency.</p>
+<p>All the readers and writers for RDF/XML are configurable, see
+below, <a href="#input">input</a> and <a href="#output">output</a>.</p>
+<h2 id="character-encoding-issues">Character Encoding Issues</h2>
+<p>The easiest way to not read or understand this section is always to
+use <code>InputStream</code>s and <code>OutputStream</code>s with Jena, and to never use
+<code>Reader</code>s and <code>Writer</code>s. If you do this, Jena will do the right thing,
+for the vast majority of users. If you have legacy code that uses
+<code>Reader</code>s and <code>Writer</code>s, or you have special needs with respect to
+encodings, then this section may be helpful. The last part of this
+section summarizes the character encodings supported by Jena.</p>
+<p>Character encoding is the way that characters are mapped to bytes,
+shorts or ints. There are many different character encodings.
+Within Jena, character encodings are important in their
+relationship to Web content, particularly RDF/XML files, which
+cannot be understood without knowing the character encoding, and in
+relationship to Java, which provides support for many character
+encodings.</p>
+<p>The Java approach to encodings is designed for ease of use on a
+single machine, which uses a single encoding; often being a
+one-byte encoding, e.g. for European languages which do not need
+thousands of different characters.</p>
+<p>The XML approach is designed for the Web which uses multiple
+encodings, and some of them requiring thousands of characters.</p>
+<p>On the Web, XML files, including RDF/XML files, are by default
+encoded in "UTF-8" (Unicode). This is always a good choice for
+creating content, and is the one used by Jena by default. Other
+encodings can be used, but may be less interoperable. Other
+encodings should be named using the canonical name registered at
+<a href="http://www.iana.org/assignments/character-sets">IANA</a>, but other
+systems have no obligations to support any of these, other than
+UTF-8 and UTF-16.</p>
+<p>Within Java, encodings appear primarily with the <code>InputStreamReader</code>
+and <code>OutputStreamWriter</code> classes, which convert between bytes and
+characters using a named encoding, and with their subclasses,
+<code>FileReader</code> and <code>FileWriter</code>, which convert between bytes in the file
+and characters using the default encoding of the platform. It is
+not possible to change the encoding used by a <code>Reader</code> or <code>Writer</code>
+while it is being used. The default encoding of the platform
+depends on a large range of factors. This default encoding may be
+useful for communicating with other programs on the same platform.
+Sometimes the default encoding is not registered at IANA, and so
+Jena application developers should not use the default encoding for
+Web content, but use UTF-8.</p>
+<h3 id="encodings-supported-in-jena-22-and-later">Encodings Supported in Jena 2.2 and later</h3>
+<p>On RDF/XML input any encoding supported by Java can be used. If
+this is not a canonical name registered at IANA a warning message
+is produced. Some encodings have better support in Java 1.5 than
+Java 1.4; for such encodings a warning message is produced on Java
+1.4, suggesting upgrading.</p>
+<p>On RDF/XML output any encoding supported by Java can be used, by
+constructing an <code>OutputStreamWriter</code> using that encoding, and using
+that for output. If the encoding is not registered at IANA then a
+warning message is produced. Some encodings have better support in
+Java 1.5 than Java 1.4; for such encodings a warning message is
+produced on Java 1.4, suggesting upgrading.</p>
+<p>Java can be configured either with or without a jar of extra
+encodings on the classpath. This jar is <code>charsets.jar</code> and sits in
+the <code>lib</code> directory of the Java Runtime. If this jar is not on your
+classpath then the range of encodings supported is fairly small.</p>
+<p>The encodings supported by Java are listed by Sun, for
+<a href="http://docs.oracle.com/javase/1.4.2/docs/guide/intl/encoding.doc.html">1.4.2</a>,
+and
+<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/intl/encoding.doc.html">1.5.0</a>.
+For an encoding that is not in these lists it is possible to write
+your own transcoder as documented in the <code>java.nio.charset</code> package
+documentation.</p>
+<p>Earlier versions of Jena supported fewer encodings.</p>
+<h2 id="when-to-use-reader-and-writer">When to Use Reader and Writer?</h2>
+<p>Infrequently.</p>
+<p>Despite the character encoding issues, it is still sometimes
+appropriate to use <code>Reader</code>s and <code>Writer</code>s with Jena I/O. A good
+example is using <code>Reader</code>s and <code>Writer</code>s into <code>StringBuffer</code>s in memory.
+These do not need to be encoded and decoded so a character encoding
+does not need to be specified. Other examples are when an advanced
+user explicitly wishes to correctly control the encoding.</p>
+<ul>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.Reader, java.lang.String)"><code>read</code></a><code>(java.io.Reader reader, java.lang.String base)</code>
+<br />Using this method is often a mistake.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.Reader, java.lang.String, java.lang.String)"><code>read</code></a><code>(java.io.Reader reader, java.lang.String base, java.lang.String lang)</code>
+<br />Using this method is often a mistake.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer)"><code>write</code></a><code>(java.io.Writer writer)</code>
+<br />Caution! Write the model as an XML document.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer, java.lang.String)"><code>write</code></a><code>(java.io.Writer writer, java.lang.String lang)</code>
+<br /> Caution! Write a serialized representation of a model in a specified language.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer, java.lang.String, java.lang.String)"><code>write</code></a><code>(java.io.Writer writer, java.lang.String lang, java.lang.String base)</code>
+<br /> Caution! Write a serialized representation of a model in a specified language.</li>
+</ul>
+<p>Incorrect use of these <code>read(Reader, …)</code> methods results in
+warnings and errors with RDF/XML and RDF/XML-ABBREV (except in a
+few cases where the incorrect use cannot be automatically
+detected). Incorrect use of the <code>write(Writer, …)</code> methods
+results in peculiar XML declarations such as
+<code>&lt;?xml version="1.0" encoding="WINDOWS-1252"?&gt;</code>. This would reflect
+that the character encoding you used (probably without realizing)
+in your Writer is registered with IANA under the name
+"WINDOWS-1252". The resulting XML is of reduced portability as a
+result. Glenn Marcy
+<a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=4456">notes</a>:</p>
+<blockquote>
+<p>since UTF-8 and UTF-16 are the only encodings REQUIRED to be
+understood by all conformant XML processors, even ISO-8859-1 would
+technically be on shaky ground if not for the fact that it is in
+such widespread use that every reasonable XML processor supports
+it.With N-TRIPLE incorrect use is usually benign, since N-TRIPLE is
+ascii based.</p>
+</blockquote>
+<p>Character encoding issues of N3 are not well-defined; hence use of
+these methods may require changes in the future. Use of the
+InputStream and OutputStream methods will allow your code to work
+with future versions of Jena which do the right thing - whatever
+that is. Currently the OutputStream methods use UTF-8 encoding.</p>
+<h2 id="introduction-to-advanced-jena-io">Introduction to Advanced Jena I/O</h2>
+<p>The RDF/XML input and output is configurable.
+However, to configure it, it is necessary to access an <code>RDFReader</code> or
+<code>RDFWriter</code> object that remains hidden in the simpler interface
+above.</p>
+<p>The four vital calls in the <code>Model</code> interface are:</p>
+<ul>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html"><code>RDFReader</code></a>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader()"><code>getReader</code></a><code>()</code>
+<br />Return an RDFReader instance for the default serialization language.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html"><code>RDFReader</code></a>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader(java.lang.String)"><code>getReader</code></a><code>(java.lang.String lang)</code>
+<br />Return an RDFReader instance for the specified serialization language.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html"><code>RDFReader</code></a>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter()"><code>getWriter</code></a><code>()</code>
+<br />Return an RDFWriter instance for the default serialization language.</li>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html"><code>RDFReader</code></a>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String)"><code>getWriter</code></a><code>(java.lang.String lang)</code>
+<br />An RDFWriter instance for the specified serialization language.</li>
+</ul>
+<p>Each of these calls returns an <code>RDFReader</code> or <code>RDFWriter</code> that can be
+used to read or write any <code>Model</code> (not just the one which created
+it). As well as the necessary
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#read(com.hp.hpl.jena.rdf.model.Model, java.io.InputStream, java.lang.String)"><code>read</code></a>
+and
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriter.html#write(com.hp.hpl.jena.rdf.model.Model, java.io.OutputStream, java.lang.String)"><code>write</code></a>
+methods, these interfaces provide:</p>
+<ul>
+<li><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html"><code>RDFErrorHandler</code></a>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler)"><code>setErrorHandler</code></a><code>(</code> <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html">RDFErrorHandler</a> <code>errHandler )</code>
+<br />Set an error handler for the reader</li>
+<li><code>java.lang.Object</code>
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(java.lang.String propName, java.lang.Object propValue)</code>
+<br />Set the value of a reader property.</li>
+</ul>
+<p>Setting properties, or the error handler, on an <code>RDFReader</code> or an
+<code>RDFWriter</code> allows the programmer to access non-default behaviour.
+Moreover, since the <code>RDFReader</code> and <code>RDFWriter</code> is not bound to a
+specific <code>Model</code>, a typical idiom is to create the <code>RDFReader</code> or
+<code>RDFWriter</code> on system initialization, to set the appropriate
+properties so that it behaves exactly as required in your application,
+and then to do all subsequent I/O through it.</p>
+<div class="codehilite"><pre><span class="n">Model</span> <span class="n">m</span> <span class="o">=</span> <span class="n">Modelfactory</span><span class="o">.</span><span class="n">createDefaultModel</span><span class="p">();</span>
+<span class="n">RDFWriter</span> <span class="n">writer</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getRDFWriter</span><span class="p">();</span>
+<span class="n">m</span> <span class="o">=</span> <span class="n">null</span><span class="p">;</span> <span class="sr">//</span> <span class="n">m</span> <span class="n">is</span> <span class="nb">no</span> <span class="n">longer</span> <span class="n">needed</span><span class="o">.</span>
+<span class="n">writer</span><span class="o">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">myErrorHandler</span><span class="p">);</span>
+<span class="n">writer</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;showXmlDeclaration&quot;</span><span class="p">,</span><span class="s">&quot;true&quot;</span><span class="p">);</span>
+<span class="n">writer</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;tab&quot;</span><span class="p">,</span><span class="s">&quot;8&quot;</span><span class="p">);</span>
+<span class="n">writer</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;relativeURIs&quot;</span><span class="p">,</span><span class="s">&quot;same-document,relative&quot;</span><span class="p">);</span>
+<span class="err">…</span>
+<span class="n">Model</span> <span class="n">marray</span><span class="o">[]</span><span class="p">;</span>
+<span class="err">…</span>
+<span class="k">for</span> <span class="p">(</span><span class="nb">int</span> <span class="n">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="n">i</span><span class="o">&lt;</span><span class="n">marray</span><span class="o">.</span><span class="nb">length</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+<span class="err">…</span>
+    <span class="n">OutputStream</span> <span class="n">out</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FileOutputStream</span><span class="p">(</span><span class="s">&quot;foo&quot;</span> <span class="o">+</span> <span class="n">i</span> <span class="o">+</span> <span class="s">&quot;.rdf&quot;</span><span class="p">);</span>
+    <span class="n">writer</span><span class="o">.</span><span class="nb">write</span><span class="p">(</span><span class="n">marray</span><span class="p">[</span><span class="n">i</span><span class="p">],</span>
+                       <span class="n">out</span><span class="p">,</span>
+      <span class="s">&quot;http://example.org/&quot;</span><span class="p">);</span>
+    <span class="n">out</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Note that all of the current implementations are synchronized, so
+that a specific <code>RDFReader</code> cannot be reading two different documents
+at the same time. In a multi-threaded application this may suggest a
+need for a pool of <code>RDFReader</code>s and/or <code>RDFWriter</code>s, or alternatively
+to create, initialize, use and discard them as needed.</p>
+<p>For N-TRIPLE there are currently no properties supported for
+either the <code>RDFReader</code> or the <code>RDFWriter</code>. Hence this idiom above is
+not very helpful, and just using the <code>Model.write()</code> methods may
+prove easier.</p>
+<p>For RDF/XML and RDF/XML-ABBREV, there are many options in both the
+<code>RDFReader</code> and the <code>RDFWriter</code>. N3 has options on the <code>RDFWriter</code>. These
+options are detailed below. For RDF/XML they are also found in the
+JavaDoc for
+<code>JenaReader.</code><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(String, Object)</code>
+and
+<code>RDFXMLWriterI.</code><a href="/documentation/javadoc/jena/com/hp/hpl/jena/xmloutput/RDFXMLWriterI.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(String, Object)</code>.</p>
+<h2 id="advanced-rdfxml-input">Advanced RDF/XML Input</h2>
+<p>For access to these advanced features, first get an <code>RDFReader</code>
+object that is an instance of an ARP parser, by using the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader()"><code>getReader</code></a><code>()</code>
+method on any <code>Model</code>. It is then configured using the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(String, Object)</code>
+method. This changes the properties for parsing RDF/XML. Many of
+the properties change the RDF parser, some change the XML parser.
+(The Jena RDF/XML parser, ARP, implements the
+<a href="http://www.w3.org/TR/rdf-syntax-grammar/#section-Infoset-Grammar">RDF grammar</a>
+over a <a href="http://xml.apache.org/xerces2-j/index.html">Xerces2-J</a> XML
+parser). However, changing the features and properties of the XML
+parser is not likely to be useful, but was easy to implement.</p>
+<p><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(String, Object)</code>
+can be used to set and get:</p>
+<ul>
+<li>ARP properties
+   <br /> These allow fine grain control over the extensive error
+   reporting capabilities of ARP. And are detailed directly below.</li>
+<li>SAX2 features
+  <br />See
+  <a href="http://xml.apache.org/xerces2-j/features.html">Xerces features</a>.
+  Value should be given as a String <code>"true"</code> or <code>"false"</code> or a <code>Boolean</code>.</li>
+<li>SAX2 properties
+  <br /> See <a href="http://xml.apache.org/xerces2-j/properties.html">Xerces properties</a>.</li>
+<li>Xerces features
+  <br /> See <a href="http://xml.apache.org/xerces2-j/features.html">Xerces features</a>.
+    Value should be given as a String <code>"true"</code> or <code>"false"</code> or a <code>Boolean</code>.</li>
+<li>Xerces properties
+  <br /> See <a href="http://xml.apache.org/xerces2-j/properties.html">Xerces properties</a>.</li>
+</ul>
+<h3 id="arp-properties">ARP properties</h3>
+<p>An ARP property is referred to either by its property name, (see
+below) or by an absolute URL of the form
+<code>http://jena.hpl.hp.com/arp/properties/&lt;PropertyName&gt;</code>. The value
+should be a String, an Integer or a Boolean depending on the
+property.</p>
+<p>ARP property names and string values are case insensitive.</p>
+<table>
+<thead>
+<tr>
+<th>Property Name</th>
+<th>Description</th>
+<th>Value class</th>
+<th>Legal Values</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>iri-rules</code></td>
+<td>Set the engine for checking and resolving. <code>"strict"</code> sets the IRI engine with rules for valid IRIs, XLink and RDF; it does not permit spaces in IRIs. <code>"iri"</code>sets the IRI engine to IRI (<a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>) <code>.</code> The default is <code>"lax"</code>(for backwards compatibility)<code>,</code> the rules for RDF URI references only, which does permit spaces although the use of spaces is not good practice.</td>
+<td>String</td>
+<td><code>lax</code><br /><code>strict</code><br /><code>iri</code></td>
+</tr>
+<tr>
+<td><code>error-mode</code></td>
+<td><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setDefaultErrorMode()"><code>ARPOptions.setDefaultErrorMode()</code></a> <br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setLaxErrorMode()"><code>ARPOptions.setLaxErrorMode()</code></a><br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setStrictErrorMode()"><code>ARPOptions.setStrictErrorMode()</code></a><br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setStrictErrorMode(int)"><code>ARPOptions.setStrictErrorMode(int)</code></a><br />  This allows a coarse-grained approach to control of error handling. Setting this property is equivalent to setting many of the fine-grained error handling properties.</td>
+<td><code>String</code></td>
+<td><code>default</code><br /><code>lax</code><br /><code>strict</code><br /><code>strict-ignore</code><br /><code>strict-warning</code><br /><code>strict-error</code><br /><code>strict-fatal</code></td>
+</tr>
+<tr>
+<td><code>embedding</code></td>
+<td><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setEmbedding(boolean)"><code>ARPOptions.setEmbedding(boolean)</code></a> <br />This sets ARP to look for RDF embedded within an enclosing XML document.</td>
+<td><code>String</code> or <code>Boolean</code></td>
+<td><code>true</code><br /><code>false</code></td>
+</tr>
+<tr>
+<td><code>ERR_&lt;XXX&gt;</code> <br /><code>WARN_&lt;XXX&gt;</code><br /><code>IGN_&lt;XXX&gt;</code></td>
+<td>See <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html"><code>ARPErrorNumbers</code></a> for a complete list of the error conditions detected. Setting one of these properties is equivalent to the method <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setErrorMode(int,%20int)"><code>ARPOptions.setErrorMode(int, int)</code></a>. Thus fine-grained control over the behaviour in response to specific error conditions is possible.</td>
+<td><code>String</code> or <code>Integer</code></td>
+<td><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_IGNORE"><code>EM_IGNORE</code></a><br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_WARNING"><code>EM_WARNING</code></a><br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_ERROR"><code>EM_ERROR</code></a><br /><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_FATAL"><code>EM_FATAL</code></a></td>
+</tr>
+</tbody>
+</table>
+<p>As an example, if you are working in an environment with legacy RDF
+data that uses unqualified RDF attributes such as "about" instead
+of "rdf:about", then the following code is appropriate:</p>
+<div class="codehilite"><pre><span class="n">Model</span> <span class="n">m</span> <span class="o">=</span> <span class="n">Modelfactory</span><span class="o">.</span><span class="n">createDefaultModel</span><span class="p">();</span>
+<span class="n">RDFReader</span> <span class="n">arp</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getReader</span><span class="p">();</span>
+<span class="n">m</span> <span class="o">=</span> <span class="n">null</span><span class="p">;</span> <span class="sr">//</span> <span class="n">m</span> <span class="n">is</span> <span class="nb">no</span> <span class="n">longer</span> <span class="n">needed</span><span class="o">.</span>
+<span class="sr">//</span> <span class="n">initialize</span> <span class="n">arp</span>
+<span class="sr">//</span> <span class="n">Do</span> <span class="ow">not</span> <span class="nb">warn</span> <span class="n">on</span> <span class="k">use</span> <span class="n">of</span> <span class="n">unqualified</span> <span class="n">RDF</span> <span class="n">attributes</span><span class="o">.</span>
+<span class="n">arp</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;WARN_UNQUALIFIED_RDF_ATTRIBUTE&quot;</span><span class="p">,</span><span class="s">&quot;EM_IGNORE&quot;</span><span class="p">);</span>
+
+<span class="err">…</span>
+
+<span class="n">InputStream</span> <span class="n">in</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="n">fname</span><span class="p">);</span>
+<span class="n">arp</span><span class="o">.</span><span class="nb">read</span><span class="p">(</span><span class="n">m</span><span class="p">,</span><span class="n">in</span><span class="p">,</span><span class="n">url</span><span class="p">);</span>
+<span class="n">in</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+</pre></div>
+
+
+<p>As a second example, suppose you wish to work in strict mode, but
+allow <code>"daml:collection"</code>, the following works:</p>
+<div class="codehilite"><pre> <span class="err">…</span>
+ <span class="n">arp</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;error-mode&quot;</span><span class="p">,</span> <span class="s">&quot;strict&quot;</span> <span class="p">);</span>
+ <span class="n">arp</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;IGN_DAML_COLLECTION&quot;</span><span class="p">,</span><span class="s">&quot;EM_IGNORE&quot;</span><span class="p">);</span>
+ <span class="err">…</span>
+</pre></div>
+
+
+<p>The other way round does not work.</p>
+<div class="codehilite"><pre> <span class="err">…</span>
+ <span class="n">arp</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;IGN_DAML_COLLECTION&quot;</span><span class="p">,</span><span class="s">&quot;EM_IGNORE&quot;</span><span class="p">);</span>
+ <span class="n">arp</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;error-mode&quot;</span><span class="p">,</span> <span class="s">&quot;strict&quot;</span> <span class="p">);</span>
+ <span class="err">…</span>
+</pre></div>
+
+
+<p>This is because in strict mode
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#IGN_DAML_COLLECTION"><code>IGN_DAML_COLLECTION</code></a>
+is treated as an error, and so the second call to <code>setProperty</code>
+overwrites the effect of the first.</p>
+<p>The IRI rules and resolver can be set on a per-reader basis:</p>
+<div class="codehilite"><pre><span class="n">InputStream</span> <span class="n">in</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
+<span class="n">String</span> <span class="n">baseURI</span> <span class="o">=</span> <span class="o">...</span> <span class="p">;</span>
+<span class="n">Model</span> <span class="n">model</span> <span class="o">=</span> <span class="n">Modelfactory</span><span class="o">.</span><span class="n">createDefaultModel</span><span class="p">();</span>
+<span class="n">RDFReader</span> <span class="n">r</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">getReader</span><span class="p">(</span><span class="s">&quot;RDF/XML&quot;</span><span class="p">);</span>
+<span class="n">r</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;iri-rules&quot;</span><span class="p">,</span> <span class="s">&quot;strict&quot;</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">r</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;error-mode&quot;</span><span class="p">,</span> <span class="s">&quot;strict&quot;</span><span class="p">)</span> <span class="p">;</span> <span class="sr">//</span> <span class="n">Warning</span> <span class="n">will</span> <span class="n">be</span> <span class="n">errors</span><span class="o">.</span>
+
+<span class="sr">//</span> <span class="n">Alternative</span> <span class="n">to</span> <span class="n">the</span> <span class="n">above</span> <span class="s">&quot;error-mode&quot;</span><span class="p">:</span> <span class="n">set</span> <span class="n">specific</span> <span class="n">warning</span> <span class="n">to</span> <span class="n">be</span> <span class="n">an</span> <span class="n">error</span><span class="o">.</span>
+<span class="sr">//</span><span class="n">r</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span> <span class="s">&quot;WARN_MALFORMED_URI&quot;</span><span class="p">,</span> <span class="n">ARPErrorNumbers</span><span class="o">.</span><span class="n">EM_ERROR</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">r</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="n">in</span><span class="p">,</span> <span class="n">baseURI</span><span class="p">)</span> <span class="p">;</span>
+<span class="n">in</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+</pre></div>
+
+
+<p>The global default IRI engine can be set with:</p>
+<div class="codehilite"><pre><span class="n">ARPOptions</span><span class="o">.</span><span class="n">setIRIFactoryGlobal</span><span class="p">(</span><span class="n">IRIFactory</span><span class="o">.</span><span class="n">iriImplementation</span><span class="p">())</span> <span class="p">;</span>
+</pre></div>
+
+
+<p>or other IRI rule engine from <code>IRIFactory</code>.</p>
+<h3 id="interrupting-arp">Interrupting ARP</h3>
+<p>ARP can be interrupted using the <code>Thread.interrupt()</code> method. This
+causes an
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#ERR_INTERRUPTED"><code>ERR_INTERRUPTED</code></a>
+error during the parse, which is usually treated as a fatal error.</p>
+<p>Here is an illustrative code sample:</p>
+<div class="codehilite"><pre><span class="n">ARP</span> <span class="n">a</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ARP</span><span class="p">();</span>
+<span class="n">final</span> <span class="n">Thread</span> <span class="n">arpt</span> <span class="o">=</span> <span class="n">Thread</span><span class="o">.</span><span class="n">currentThread</span><span class="p">();</span>
+<span class="n">Thread</span> <span class="n">killt</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Thread</span><span class="p">(</span><span class="k">new</span> <span class="n">Runnable</span><span class="p">()</span> <span class="p">{</span>
+     <span class="n">public</span> <span class="n">void</span> <span class="n">run</span><span class="p">()</span> <span class="p">{</span>
+       <span class="n">try</span> <span class="p">{</span>
+          <span class="n">Thread</span><span class="o">.</span><span class="nb">sleep</span><span class="p">(</span><span class="n">tim</span><span class="p">);</span>
+       <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">InterruptedException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+       <span class="p">}</span>
+       <span class="n">arpt</span><span class="o">.</span><span class="n">interrupt</span><span class="p">();</span>
+     <span class="p">}</span>
+  <span class="p">});</span>
+<span class="n">killt</span><span class="o">.</span><span class="n">start</span><span class="p">();</span>
+<span class="n">try</span> <span class="p">{</span>
+  <span class="n">in</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="n">fileName</span><span class="p">);</span>
+  <span class="n">a</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">in</span><span class="p">);</span>
+  <span class="n">in</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+  <span class="n">fail</span><span class="p">(</span><span class="s">&quot;Thread was not interrupted.&quot;</span><span class="p">);</span>
+<span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">SAXParseException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="advanced-rdfxml-output">Advanced RDF/XML Output</h2>
+<p>The first RDF/XML output question is whether to use the <code>"RDF/XML"</code>
+or <code>RDF/XML-ABBREV</code> writer. While some of the code is shared, these
+two writers are really very different, resulting in different but
+equivalent output. <code>RDF/XML-ABBREV</code> is slower, but should produce
+more readable XML.</p>
+<p>For access to advanced features, first get an RDFWriter object, of
+the appropriate language, by using
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String)"><code>getWriter</code></a><code>("RDF/XML")</code>
+or
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String)"><code>getWriter</code></a><code>("RDF/XML-ABBREV")</code>
+on any <code>Model</code>. It is then configured using the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object)"><code>setProperty</code></a><code>(String, Object)</code>
+method. This changes the properties for writing RDF/XML.</p>
+<h3 id="properties-to-control-rdfxml-output">Properties to Control RDF/XML Output</h3>
+<p><table>
+<tr><th>Property Name</th><th>Description</th><th>Value class</th><th>Legal Values</th></tr>
+<tr>
+<td><code>xmlbase</code></td>
+<td>The value to be included for an xml:base attribute on the root element in the file.</td>
+<td><code>String</code></td>
+<td>A URI string, or null (default)</td>
+</tr>
+<tr>
+<td><code>longId</code></td>
+<td>Whether to use long or short id's for anon resources. Short id's are easier to read and are the default, but can run out of memory on very large models.</td>
+<td><code>String</code> or <code>Boolean</code></td>
+<td><code>"true"</code>, <code>"false"</code> (default)</td>
+</tr>
+<tr>
+<td><code>allowBadURIs</code></td>
+<td>URIs in the graph are, by default, checked prior to serialization.</td>
+<td><code>String</code> or <code>Boolean</code></td>
+<td><code>"true"</code>, <code>"false"</code> (default)</td>
+</tr>
+<tr>
+<td><code>relativeURIs</code></td>
+<td>What sort of relative URIs should be used. A comma separated list of options:</p>
+<ul>
+<li><em>same-document</em><br />
+ same-document references (e.g. "" or "#foo")</li>
+<li><em>network</em><br />
+  network paths e.g. <code>"//example.org/foo"</code> omitting the URI scheme</li>
+<li><em>absolute</em><br />
+  absolute paths e.g. <code>"/foo"</code> omitting the scheme and authority</li>
+<li><em>relative</em><br />
+  relative path not beginning in <code>"../"</code></li>
+<li><em>parent</em><br />
+  relative path beginning in <code>"../"</code></li>
+<li><em>grandparent</em><br />
+  relative path begining in <code>"../../"</code></li>
+</ul>
+<p>The default value is "same-document, absolute, relative, parent".
+To switch off relative URIs use the value "". Relative URIs of any
+of these types are output where possible if and only if the option
+has been specified.</td>
+<td>String</td>
+</tr>
+<tr>
+<td><code>showXmlDeclaration</code></td>
+<td>
+If true, an XML Declaration is included in the output, if false no XML declaration is included.
+The default behaviour only gives an XML Declaration when asked to write to an <code>OutputStreamWriter</code>
+that uses some encoding other than UTF-8 or UTF-16. In this case the encoding is shown in the
+XML declaration. To ensure that the encoding attribute is shown in the XML declaration either:</p>
+<ul>
+<li>Set this option to true and use the
+    <code>write(Model,Writer,String)</code> variant with an appropriate <code>OutputStreamWriter</code>.</li>
+<li>
+<p>Or set this option to false, and write the declaration to an <code>OutputStream</code> before calling
+    <code>write(Model,OutputStream,String)</code>.
+</td>
+<td><code>true</code>, <code>"true"</code>, <code>false</code>, <code>"false"</code> or <code>"default"</code></td>
+<td>can be true, false or "default" (null)</td>
+</tr>
+<tr>
+<td><code>showDoctypeDeclaration</code></td>
+<td>
+If true, an XML Doctype declaration is included in the output. This
+declaration includes a <code>!ENTITY</code> declaration for each prefix mapping
+in the model, and any attribute value that starts with the URI of
+that mapping is written as starting with the corresponding entity
+invocation.
+</td>
+<td><code>String</code> or <code>Boolean</code></td>
+<td><code>true</code>, <code>false</code>, <code>"true"</code>, <code>"false"</code></td>
+</tr>
+<tr>
+<td><code>tab</code></td>
+<td>The number of spaces with which to indent XML child elements.</td>
+<td><code>String</code> or <code>Integer</code></td>
+<td>positive integer "2" is the default</td>
+</tr>
+<tr>
+<td><code>attributeQuoteChar</code></td>
+<td>How to write XML attributes.</td>
+<td><code>String</code></td>
+<td><code>"\""</code> or <code>"'"</code></td>
+</tr>
+<tr>
+<td><code>blockRules</code></td>
+<td>
+A list of <code>Resource</code> or a <code>String</code> being a comma separated list of
+fragment IDs from <a href="http://www.w3.org/TR/rdf-syntax-grammar">http://www.w3.org/TR/rdf-syntax-grammar</a>
+indicating grammar rules that will not be used. Rules that can be blocked are:</p>
+</li>
+<li>
+<p><a href="http://www.w3.org/TR/rdf-syntax-grammar#section-Reification">section-Reification</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#sectionReification"><code>RDFSyntax.sectionReification</code></a>)</p>
+</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#section-List-Expand">section-List-Expand</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#sectionListExpand"><code>RDFSyntax.sectionListExpand</code></a>)</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#parseTypeLiteralPropertyElt">parseTypeLiteralPropertyElt</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt"><code>RDFSyntax.parseTypeLiteralPropertyElt</code></a>)</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#parseTypeResourcePropertyElt">parseTypeResourcePropertyElt</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt"><code>RDFSyntax.parseTypeLiteralPropertyElt</code></a>)</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#parseTypeCollectionPropertyElt">parseTypeCollectionPropertyElt</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeCollectionPropertyElt"><code>RDFSyntax.parseTypeCollectionPropertyElt</code></a>)</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#idAttr">idAttr</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#idAttr"><code>RDFSyntax.idAttr</code></a>)</li>
+<li><a href="http://www.w3.org/TR/rdf-syntax-grammar#propertyAttr">propertyAttr</a>
+ (<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#propertyAttr"><code>RDFSyntax.propertyAttr</code></a>)</li>
+</ul>
+<p>In addition <code>"daml:collection"</code>
+(<a href="/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/DAML_OIL.html#collection"><code>DAML_OIL.collection</code></a>)
+can be blocked. Blocking
+<a href="http://www.w3.org/TR/rdf-syntax-grammar#idAttr">idAttr</a> also
+blocks
+<a href="http://www.w3.org/TR/rdf-syntax-grammar#section-Reification">section-Reification</a>.
+By default, rule
+<a href="http://www.w3.org/TR/rdf-syntax-grammar#propertyAttr">propertyAttr</a>
+is blocked. For the basic writer (RDF/XML) only
+<a href="http://www.w3.org/TR/rdf-syntax-grammar#parseTypeLiteralPropertyElt">parseTypeLiteralPropertyElt</a>
+has any effect, since none of the other rules are implemented by
+that writer.
+</td>
+<td><code>Resource[]</code> or <code>String</code></td>
+<td></td>
+</tr>
+<tr> 
+<td><code>prettyTypes</code></td>
+<td>
+Only for the RDF/XML-ABBREV writer. This is a list of the types of
+the principal objects in the model. The writer will tend to create
+RDF/XML with resources of these types at the top level.
+</td>
+<td>
+<code>Resource[]</code>
+</td>
+<td></td>
+</tr>
+</table>
+ 
+As an example,</p>
+<div class="codehilite"><pre><span class="n">RDFWriter</span> <span class="n">w</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getWriter</span><span class="p">(</span><span class="s">&quot;RDF/XML-ABBREV&quot;</span><span class="p">);</span>
+<span class="n">w</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;attribtueQuoteChar&quot;</span><span class="p">,</span><span class="s">&quot;&#39;&quot;</span><span class="p">);</span>
+<span class="n">w</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;showXMLDeclaration&quot;</span><span class="p">,</span><span class="s">&quot;true&quot;</span><span class="p">);</span>
+<span class="n">w</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;tab&quot;</span><span class="p">,</span><span class="s">&quot;1&quot;</span><span class="p">);</span>
+<span class="n">w</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;blockRules&quot;</span><span class="p">,</span>
+  <span class="s">&quot;daml:collection,parseTypeLiteralPropertyElt,&quot;</span>
+  <span class="o">+</span><span class="s">&quot;parseTypeResourcePropertyElt,parseTypeCollectionPropertyElt&quot;</span><span class="p">);</span>
+</pre></div>
+
+
+<p>creates a writer that does not use rdf:parseType (preferring
+rdf:datatype for rdf:XMLLiteral), indents only a little, and
+produces the XMLDeclaration. Attributes are used, and are quoted
+with <code>"'"</code>.</p>
+<p>Note that property attributes are not used at all, by default.
+However, the RDF/XML-ABBREV writer includes a rule to produce
+property attributes when the value does not contain any spaces.
+This rule is normally switched off. This rule can be turned on
+selectively by using the blockRules property as detailed above.</p>
+<h2 id="conformance">Conformance</h2>
+<p>The RDF/XML I/O endeavours to conform with the
+<a href="http://www.w3.org/TR/rdf-syntax-grammar/">RDF Syntax Recommendation</a>.</p>
+<p>The parser must be set to strict mode. (Note that, the conformant
+behaviour for <code>rdf:parseType="daml:collection"</code> is to silently turn
+<code>"daml:collection"</code> into <code>"Literal"</code>).</p>
+<p>The RDF/XML writer is conformant, but does not exercise much of the
+grammar.</p>
+<p>The RDF/XML-ABBREV writer exercises all of the grammar and is
+conformant except that it uses the <code>daml:collection</code> construct for
+DAML ontologies. This non-conformant behaviour can be switched off
+using the <code>blockRules</code> property.</p>
+<h2 id="faster-rdfxml-io">Faster RDF/XML I/O</h2>
+<p>To optimise the speed of writing RDF/XML it is suggested that all
+URI processing is turned off. Also do not use RDF/XML-ABBREV. It is
+unclear whether the longId attribute is faster or slower; the short
+IDs have to be generated on the fly and a table maintained during
+writing. The longer IDs are long, and hence take longer to write.
+The following creates a faster writer:</p>
+<div class="codehilite"><pre><span class="n">Model</span> <span class="n">m</span><span class="p">;</span>
+<span class="err">…</span>
+<span class="err">…</span>
+<span class="n">RDFWriter</span> <span class="n">fasterWriter</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getWriter</span><span class="p">(</span><span class="s">&quot;RDF/XML&quot;</span><span class="p">);</span>
+<span class="n">fasterWriter</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;allowBadURIs&quot;</span><span class="p">,</span><span class="s">&quot;true&quot;</span><span class="p">);</span>
+<span class="n">fasterWriter</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;relativeURIs&quot;</span><span class="p">,</span><span class="s">&quot;&quot;</span><span class="p">);</span>
+<span class="n">fasterWriter</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;tab&quot;</span><span class="p">,</span><span class="s">&quot;0&quot;</span><span class="p">);</span>
+</pre></div>
+
+
+<p>When reading RDF/XML the check for reuse of rdf:ID has a memory
+overhead, which can be significant for very large files. In this
+case, this check can be suppressed by telling ARP to ignore this
+error.</p>
+<div class="codehilite"><pre><span class="n">Model</span> <span class="n">m</span><span class="p">;</span>
+<span class="err">…</span>
+<span class="err">…</span>
+<span class="n">RDFReader</span> <span class="n">bigFileReader</span> <span class="o">=</span> <span class="n">m</span><span class="o">.</span><span class="n">getReader</span><span class="p">(</span><span class="s">&quot;RDF/XML&quot;</span><span class="p">);</span>
+<span class="n">bigFileReader</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span><span class="s">&quot;WARN_REDEFINITION_OF_ID&quot;</span><span class="p">,</span><span class="s">&quot;EM_IGNORE&quot;</span><span class="p">);</span>
+<span class="err">…</span>
+</pre></div>
+  </div>
+
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2011&ndash;12 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>

Added: websites/staging/jena/trunk/content/documentation/io/arp_sax.html
==============================================================================
--- websites/staging/jena/trunk/content/documentation/io/arp_sax.html (added)
+++ websites/staging/jena/trunk/content/documentation/io/arp_sax.html Tue Jan  1 15:28:10 2013
@@ -0,0 +1,349 @@
+<!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 - SAX Input into Jena and ARP</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></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">SAX Input into Jena and ARP</h1>
+    <p>Normally, both ARP and Jena are used to read files either from the
+local machine or from the Web. A different use case, addressed
+here, is when the XML source is available in-memory in some way. In
+these cases, ARP and Jena can be used as a SAX event handler,
+turning SAX events into triples, or a DOM tree can be parsed into a
+Jena Model.</p>
+<h2 id="contents">Contents</h2>
+<ul>
+<li><a href="#overview">Overview</a></li>
+<li><a href="#sample-code">Sample Code</a></li>
+<li><a href="#initializing-sax-event-source">Initializing SAX event source</a></li>
+<li><a href="#error-handler">Error Handler</a></li>
+<li><a href="#options">Options</a></li>
+<li><a href="#xml-lang-and-namespaces">XML Lang and Namespaces</a></li>
+<li><a href="#using-your-own-triple-handler">Using your own triple handler</a></li>
+<li><a href="#using-a-dom-as-input">Using a DOM as input</a></li>
+</ul>
+<h2 id="1-overview">1. Overview</h2>
+<p>To read an arbitrary SAX source as triples to be added into a Jena
+model, it is not possible to use a
+<code>Model.</code><a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream,%20java.lang.String)"><code>read</code></a>()
+operation. Instead, you construct a SAX event handler of class
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html"><code>SAX2Model</code></a>,
+using the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html#create(java.lang.String,%20com.hp.hpl.jena.rdf.model.Model)"><code>create</code></a>
+method, install these as the handler on your SAX event source, and
+then stream the SAX events. It is possible to have fine-grained
+control over the SAX events, for instance, by inserting or deleting
+events, before passing them to the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html"><code>SAX2Model</code></a>
+handler.</p>
+<h2 id="sample-code">Sample Code</h2>
+<p>This code uses the Xerces parser as a SAX event stream, and adds
+the triple to a
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a> using
+default options.</p>
+<div class="codehilite"><pre><span class="sr">//</span> <span class="n">Use</span> <span class="n">your</span> <span class="n">own</span> <span class="n">SAX</span> <span class="n">source</span><span class="o">.</span>
+<span class="n">XMLReader</span> <span class="n">saxParser</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SAXParser</span><span class="p">();</span>
+
+<span class="sr">//</span> <span class="n">set</span> <span class="n">up</span> <span class="n">SAX</span> <span class="n">input</span>
+<span class="n">InputStream</span> <span class="n">in</span> <span class="o">=</span> <span class="k">new</span> <span class="n">FileInputStream</span><span class="p">(</span><span class="s">&quot;kb.rdf&quot;</span><span class="p">);</span>
+<span class="n">InputSource</span> <span class="n">ins</span> <span class="o">=</span> <span class="k">new</span> <span class="n">InputSource</span><span class="p">(</span><span class="n">in</span><span class="p">);</span>
+<span class="n">ins</span><span class="o">.</span><span class="n">setSystemId</span><span class="p">(</span><span class="n">base</span><span class="p">);</span>
+
+<span class="n">Model</span> <span class="n">m</span> <span class="o">=</span> <span class="n">ModelFactory</span><span class="o">.</span><span class="n">createDefaultModel</span><span class="p">();</span>
+<span class="n">String</span> <span class="n">base</span> <span class="o">=</span> <span class="s">&quot;http://example.org/&quot;</span><span class="p">;</span>
+
+<span class="sr">//</span> <span class="n">create</span> <span class="n">handler</span><span class="p">,</span> <span class="n">linked</span> <span class="n">to</span> <span class="n">Model</span>
+<span class="n">SAX2Model</span> <span class="n">handler</span> <span class="o">=</span> <span class="n">SAX2Model</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">base</span><span class="p">,</span> <span class="n">m</span><span class="p">);</span>
+
+<span class="sr">//</span> <span class="n">install</span> <span class="n">handler</span> <span class="n">on</span> <span class="n">SAX</span> <span class="n">event</span> <span class="n">stream</span>
+<span class="n">SAX2RDF</span><span class="o">.</span><span class="n">installHandlers</span><span class="p">(</span><span class="n">saxParser</span><span class="p">,</span> <span class="n">handler</span><span class="p">);</span>
+
+<span class="n">try</span> <span class="p">{</span>
+    <span class="n">try</span> <span class="p">{</span>
+        <span class="n">saxParser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">ins</span><span class="p">);</span>
+    <span class="p">}</span> <span class="n">finally</span> <span class="p">{</span>
+        <span class="sr">//</span> <span class="n">MUST</span> <span class="n">ensure</span> <span class="n">handler</span> <span class="n">is</span> <span class="n">closed</span><span class="o">.</span>
+        <span class="n">handler</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+    <span class="p">}</span>
+<span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="n">SAXParseException</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+    <span class="sr">//</span> <span class="n">Fatal</span> <span class="n">parsing</span> <span class="n">errors</span> <span class="n">end</span> <span class="n">here</span><span class="p">,</span>
+    <span class="sr">//</span> <span class="n">but</span> <span class="n">they</span> <span class="n">will</span> <span class="n">already</span> <span class="n">have</span> <span class="n">been</span> <span class="n">reported</span><span class="o">.</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h2 id="initializing-sax-event-source">Initializing SAX event source</h2>
+<p>If your SAX event source is a subclass of <code>XMLReader</code>, then the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#installHandlers(org.xml.sax.XMLReader,%20com.hp.hpl.jena.rdf.arp.XMLHandler)">installHandlers</a>
+static method can be used as shown in the sample. Otherwise, you
+have to do it yourself. The
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#installHandlers(org.xml.sax.XMLReader,%20com.hp.hpl.jena.rdf.arp.XMLHandler)"><code>installHandlers</code></a>
+code is like this:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="n">public</span> <span class="n">void</span> <span class="n">installHandlers</span><span class="p">(</span><span class="n">XMLReader</span> <span class="n">rdr</span><span class="p">,</span> <span class="n">XMLHandler</span> <span class="n">sax2rdf</span><span class="p">)</span>
+<span class="n">throws</span> <span class="n">SAXException</span>
+<span class="p">{</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setEntityResolver</span><span class="p">(</span><span class="n">sax2rdf</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setDTDHandler</span><span class="p">(</span><span class="n">sax2rdf</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setContentHandler</span><span class="p">(</span><span class="n">sax2rdf</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setErrorHandler</span><span class="p">(</span><span class="n">sax2rdf</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setFeature</span><span class="p">(</span><span class="s">&quot;http://xml.org/sax/features/namespaces&quot;</span><span class="p">,</span> <span class="n">true</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setFeature</span><span class="p">(</span>
+            <span class="s">&quot;http://xml.org/sax/features/namespace-prefixes&quot;</span><span class="p">,</span>
+            <span class="n">true</span><span class="p">);</span>
+    <span class="n">rdr</span><span class="o">.</span><span class="n">setProperty</span><span class="p">(</span>
+            <span class="s">&quot;http://xml.org/sax/properties/lexical-handler&quot;</span><span class="p">,</span>
+            <span class="n">sax2rdf</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>For some other SAX source, the exact code will differ, but the
+required operations are as above.</p>
+<h2 id="error-handler">Error Handler</h2>
+<p>The <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html">SAX2Model</a>
+handler supports the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler)">setErrorHandler</a>
+method, from the Jena
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html">RDFReader</a>
+interface. This is used in the same way as that method to control
+error reporting.</p>
+<p>A specific fatal error, new in Jena 2.3, is ERR_INTERRUPTED, which
+indicates that the current Thread received an interrupt. This
+allows long jobs to be aborted on user request.</p>
+<h2 id="options">Options</h2>
+<p>The <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html"><code>SAX2Model</code></a>
+handler supports the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setProperty(java.lang.String,%20java.lang.Object)"><code>setProperty</code></a>
+method, from the Jena
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html"><code>RDFReader</code></a>
+interface. This is used in nearly the same way to have fine grain
+control over ARPs behaviour, particularly over error reporting, see
+the <a href="iohowto.html#arp_properties">I/O howto</a>. Setting SAX or
+Xerces properties cannot be done using this method.</p>
+<h2 id="xml-lang-and-namespaces">XML Lang and Namespaces</h2>
+<p>If you are only treating some document subset as RDF/XML then it is
+necessary to ensure that ARP knows the correct value for <code>xml:lang</code>
+and desirable that it knows the correct mappings of namespace
+prefixes.</p>
+<p>There is a second version of the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html#create(java.lang.String,%20com.hp.hpl.jena.rdf.model.Model,%20java.lang.String)"><code>create</code></a>
+method, which allows specification of the <code>xml:lang</code> value from the
+outer context. If this is inappropriate it is possible, but hard
+work, to synthesis an appropriate SAX event.</p>
+<p>For the namespaces prefixes, it is possible to call the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#startPrefixMapping(java.lang.String,%20java.lang.String)"><code>startPrefixMapping</code></a>
+SAX event, before passing the other SAX events, to declare each
+namespace, one by one. Failure to do this is permitted, but, for
+instance, a Jena Model will then not know the (advisory) namespace
+prefix bindings. These should be paired with endPrefixMapping
+events, but nothing untoward is likely if such code is omitted.</p>
+<h2 id="using-your-own-triple-handler">Using your own triple handler</h2>
+<p>As with ARP, it is possible to use this functionality, without
+using other Jena features, in particular, without using a Jena
+Model. Instead of using the class SAX2Model, you use its superclass
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html">SAX2RDF</a>. The
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#create(java.lang.String)">create</a>
+method on this class does not provide any means of specifying what
+to do with the triples. Instead, the class implements the
+<a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html">ARPConfig</a>
+interface, which permits the setting of handlers and parser
+options, as described in the documentation for using
+<a href="standalone.html">ARP without Jena</a>.</p>
+<p>Thus you need to:</p>
+<ol>
+<li>Create a SAX2RDF using
+    <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#create(java.lang.String)">SAX2RDF.create()</a></li>
+<li>Attach your StatementHandler and SAXErrorHandler and optionally
+    your NamespaceHandler and ExtendedHandler to the SAX2RDF instance.</li>
+<li>Install the SAX2RDF instance as the SAX handler on your SAX
+    source.</li>
+<li>Follow the remainder of the code sample above.</li>
+</ol>
+<h2 id="using-a-dom-as-input">Using a DOM as Input</h2>
+<p>None of the approaches listed here work with Java 1.4.1_04. We
+suggest using Java 1.4.2_04 or greater for this functionality.
+This issue has no impact on any other Jena functionality.</p>
+<h3 id="using-a-dom-as-input-to-jena">Using a DOM as Input to Jena</h3>
+<p>The <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html"><code>DOM2Model</code></a>
+subclass of SAX2Model, allows the parsing of a DOM using ARP. The
+procedure to follow is:</p>
+<ul>
+<li>Construct a <code>DOM2Model</code>, using a factory method such as
+    <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html#createD2M(java.lang.String,%20com.hp.hpl.jena.rdf.model.Model)"><code>createD2M</code></a>,
+    specifying the xml:base of the document to be loaded, the Model to
+    load into, optionally the xml:lang value (particularly useful if
+    using a DOM Node from within a Document).</li>
+<li>Set any properties, error handlers etc. on the <code>DOM2Model</code>
+    object.</li>
+<li>The DOM is parsed simply by calling the
+    <a href="/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html#load(org.w3c.dom.Node)"><code>load(Node)</code></a>
+    method.</li>
+</ul>
+<h3 id="using-a-dom-as-input-to-arp">Using a DOM as Input to ARP</h3>
+<p>DOM2Model is a subclass of SAX2RDF, and handlers etc. can be set on
+the DOM2Model as for SAX2RDF. Using a null model as the argument to
+the factory indicates this usage.</p>
+  </div>
+
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2011&ndash;12 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>



Mime
View raw message