You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by ij...@apache.org on 2011/10/20 01:18:14 UTC
svn commit: r1186560 - in /incubator/jena/site/trunk:
content/jena/documentation/io/ templates/
Author: ijd
Date: Wed Oct 19 23:18:13 2011
New Revision: 1186560
URL: http://svn.apache.org/viewvc?rev=1186560&view=rev
Log:
Migrated old ARP documentation to new site structure.
Added:
incubator/jena/site/trunk/content/jena/documentation/io/
incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java (with props)
incubator/jena/site/trunk/content/jena/documentation/io/features.mdtext
incubator/jena/site/trunk/content/jena/documentation/io/index.mdtext
incubator/jena/site/trunk/content/jena/documentation/io/iohowto.mdtext
incubator/jena/site/trunk/content/jena/documentation/io/sax.mdtext
incubator/jena/site/trunk/content/jena/documentation/io/standalone.mdtext
Modified:
incubator/jena/site/trunk/templates/sidenav.mdtext
Added: incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java Wed Oct 19 23:18:13 2011
@@ -0,0 +1,51 @@
+
+import javax.xml.transform.*;
+import javax.xml.transform.dom.*;
+import javax.xml.transform.sax.*;
+import org.xml.sax.*;
+import org.w3c.dom.*;
+import javax.xml.parsers.*;
+import java.io.*;
+import com.hp.hpl.jena.rdf.arp.*;
+import com.hp.hpl.jena.rdf.model.*;
+
+/**
+ * @author Jeremy J. Carroll
+ *
+ */
+public class DOM2Jena {
+
+ public static void main(String args[]) throws Exception {
+
+ // Create DOM:
+
+ DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
+ // DOM must have namespace information inside it!
+ factory.setNamespaceAware(true);
+ DocumentBuilder domParser = factory.newDocumentBuilder();
+ Document document = domParser
+ .parse(new File("testing/wg/Manifest.rdf"));
+ // Make DOM into transformer input
+ Source input = new DOMSource(document);
+
+ // Make SAX2Model SAX event handler
+ Model m = ModelFactory.createDefaultModel();
+ SAX2Model handler = SAX2Model.create(
+ "http://www.w3.org/2000/10/rdf-tests/rdfcore/Manifest.rdf", m);
+
+
+ // Make a SAXResult object using this handler
+ SAXResult output = new SAXResult(handler);
+ output.setLexicalHandler(handler);
+
+ // Run transform
+ TransformerFactory xformFactory = TransformerFactory.newInstance();
+ Transformer idTransform = xformFactory.newTransformer();
+ idTransform.transform(input, output);
+
+ // Use Model
+ m.write(System.out, "N-TRIPLE");
+ }
+
+}
+
Propchange: incubator/jena/site/trunk/content/jena/documentation/io/DOM2Jena.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: incubator/jena/site/trunk/content/jena/documentation/io/features.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/features.mdtext?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/features.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/features.mdtext Wed Oct 19 23:18:13 2011
@@ -0,0 +1,51 @@
+Title: ARP Features
+
+- Java based RDF parser.
+- Compliant with
+ [RDF Syntax](http://www.w3.org/TR/rdf-syntax-grammar) and
+ [RDF Test Cases](http://www.w3.org/TR/rdf-testcases)
+ Recommendations.
+- Compliant with following standards and recommendations:
+ - **daml:collection**<br />
+ [rdf:parseType='daml:collection'](http://www.daml.org/2001/03/reference.html#collection)
+ is supported.
+ - **xml:lang**<br />
+ [xml:lang](http://www.w3.org/TR/REC-xml#sec-lang-tag) is fully
+ supported, both in RDF/XML and any document embedding RDF/XML.
+ Moreover, the language tags are checked against
+ [RFC1766](http://www.isi.edu/in-notes/rfc1766.txt),
+ [RFC3066](http://www.isi.edu/in-notes/rfc3066.txt), ISO639-1,
+ [ISO3166](http://www.din.de/gremien/nas/nabd/iso3166ma/codlstp1/db_en.html).
+ - **xml:base**<br />
+ [xml:base](http://www.w3.org/TR/xmlbase/) is fully supported,
+ both in RDF/XML and any document embedding RDF/XML.
+ - **URI**<br />
+ All URI references are checked against
+ [RFC2396](http://www.isi.edu/in-notes/rfc2396.txt). The treatment
+ of international URIs implements the concept of
+ [RDF URI Reference](http://www.w3.org/TR/rdf-concepts/#dfn-URI-reference).
+ - **XML Names**<br />
+ All rdf:ID's are checked against the
+ [XML Names](http://www.w3.org/TR/REC-xml#dt-name) specification.
+ - **Unicode Normal Form C**<br />
+ String literals are checked for conformance with an early
+ uniform normalization processing model.
+ - **XML Literals**<br />
+ `rdf:parseType='Literal'` is processed respecting namespaces,
+ processing instructions and XML comments. This follows the XML
+ exclusive canonicalizations recommendation with comments.
+ - **Relative Namespace URI references**<br />
+ Namespace URI references are checked in light of the
+ [W3C XML Plenary decision](http://www.w3.org/2000/09/xppa).
+- Command-line RDF/XML error checking.
+- Can be used independently of Jena, with customizable
+ `StatementHandler`.
+- Highly configurable error processing.
+- Xerces based XML parsing.
+- Processes both standalone and embedded RDF/XML.
+- Streaming parser, suitable for large files.
+- Supports SAX and DOM, for integration with non-file XML
+ sources.
+
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/io/index.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/index.mdtext?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/index.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/index.mdtext Wed Oct 19 23:18:13 2011
@@ -0,0 +1,11 @@
+Title: RDF input and output handling in Jena
+
+This section details how Jena parses and generates the various syntaxes used
+to encode RDF, including RDF/XML, Turtle and N-triples.
+ARP is the parsing subsystem in Jena for handling the RDF/XML syntax. Other parsers
+are documented in the RIOT subsystem [TODO link]
+
+- [Jena RDF I/O how-to](iohowto.html#input)
+- [ARP Features](features.html)
+- [Using ARP without Jena](standalone.html)
+- [Using other SAX and DOM XML sources](sax.html)
Added: incubator/jena/site/trunk/content/jena/documentation/io/iohowto.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/iohowto.mdtext?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/iohowto.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/iohowto.mdtext Wed Oct 19 23:18:13 2011
@@ -0,0 +1,738 @@
+Title: Jena RDF I/O How-To
+
+This is a guide to the I/O subsystem of Jena. All Jena users need
+to know to use InputStreams and OutputStreams rather than Readers
+and Writers. 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 I/O subsystem.
+
+Note that a new IO subsystem for Jena, named RIOT, is currently in development.
+Further details on RIOT can be found here: [TODO]
+
+## Contents
+
+- [Quick Introduction](#quick_introduction)
+ - [RDF/XML, RDF/XML-ABBREV](#rdfxml_rdfxml-abbrev)
+ - [TURTLE](#turtle)
+ - [N-TRIPLE](#n_triple)
+ - [N3](#n3)
+- [Character Encoding Issues](#character_encoding_issues)
+ - [Encodings Supported in Jena 2.2 and later](#encodings_supported_in_jena_22_and_later)
+- [When to Use Reader and Writer?](#when_to_use_reader_and_writer)
+- [Introduction to Advanced Jena I/O](#introduction_to_advanced_jena_io)
+- [Advanced RDF/XML Input](#advanced_rdfxml_input)
+ - [ARP properties](#arp_properties)
+ - [Interrupting ARP](#interrupting_arp)
+- [Advanced RDF/XML Output](#advanced_rdfxml_output)
+- [Advanced Turtle/N3 Output](#advanced_turtlen3_output)
+- [Conformance](#conformance)
+- [Faster RDF/XML I/O](#faster_rdfxml_io)
+
+## Quick Introduction
+
+The main I/O methods in Jena use `InputStream`s and `OutputStream`s.
+These methods are found on the
+[`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) interface.
+These are:
+
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream, java.lang.String))`(java.io.InputStream in, java.lang.String base)`
+ <br />Add statements from an RDF/XML serialization
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream, java.lang.String, java.lang.String))`(java.io.InputStream in, java.lang.String base, java.lang.String lang)`
+ <br /> Add RDF statements represented in language `lang` to the model.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.lang.String))`(java.lang.String url)`
+ <br />Add the RDF statements from an XML document.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream))`(java.io.OutputStream out)`
+ <br /> Write the model as an XML document.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream, java.lang.String))`(java.io.OutputStream out, java.lang.String lang)`
+ <br />Write a serialized representation of a model in a specified language.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream, java.lang.String, java.lang.String))`(java.io.OutputStream out, java.lang.String lang, java.lang.String base)`
+ <br />Write a serialized representation of a model in a specified language.
+
+The built-in languages are `"RDF/XML"`, `"RDF/XML-ABBREV"`,
+`"N-TRIPLE"`, `"N3"` and `"TURTLE"`. In addition, for Turtle output
+the language can be specified as: `"N3-PP"`, `"N3-PLAIN"` or
+`"N3-TRIPLE"`, which controls the style of N3 produced.
+
+There are also methods which use `Reader`s and `Writer`s. Do not use
+them, unless you are sure it is correct to. In advanced
+applications, they are useful, see [below](#reader-writer); and
+there is every intention to continue to support them. The RDF/XML
+parser now checks to see if the `Model.read(Reader â¦)` calls
+are being abused, and issues
+[`ERR_ENCODING_MISMATCH`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#ERR_ENCODING_MISMATCH)
+and
+[`WARN_ENCODING_MISMATCH`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#WARN_ENCODING_MISMATCH)
+errors. Most incorrect usage of `Reader`s for RDF/XML input will
+result in such errors. Most incorrect usage of `Writer`s for RDF/XML
+output will produce correct XML by using an appropriate XML
+declaration giving the encoding - e.g.
+
+ <?xml version='1.0' encoding='ISO-8859-15'?>
+
+However, such XML is less portable than XML in UTF-8. Using the
+`Model.write(OutputStream â¦)` methods allows the Jena system
+code to choose UTF-8 encoding, which is the best choice.
+
+### RDF/XML, RDF/XML-ABBREV
+
+For input, both of these are the same, and fully implement the
+[RDF Syntax Recommendation](http://www.w3.org/TR/rdf-syntax-grammar/),
+see [conformance](#conformance).
+
+For output, `"RDF/XML"`, produces regular output reasonably
+efficiently, but it is not readable. In contrast,
+`"RDF/XML-ABBREV"`, produces readable output without much regard to
+efficiency.
+
+All the readers and writers for RDF/XML are configurable, see
+below, [input](#input) and [output](#output).
+
+### TURTLE
+
+The N3 reader accepts any valid
+[Turtle](http://www.w3.org/TR/turtle/).
+Note that the N3 and Turtle writers produce internationalized
+qnames, with the character set from XML Namespaces (except for
+':'), not restricted to ASCII as is the definition of N3 and
+Turtle.
+
+The Turtle writer is the N3 writer [configured](#n3-output) with:
+usePropertySymbols=false, useTripleQuotedStrings=false,
+useDoubles=false.
+
+### N-TRIPLE
+
+The N-TRIPLE readers and writers implement
+[RDF Core's N-Triples](http://www.w3.org/TR/rdf-testcases/#ntriples)
+language. They are not configurable.
+
+### N3
+
+The N3 readers and writers implement
+[Tim Berners-Lee's N3](http://www.w3.org/2000/10/swap/Primer.html)
+language.
+
+There are actually 4 writers:
+
+- N3: The standard writer that choose one of the other 3.
+- N3-PP: The full N3 pretty writer
+- N3-PLAIN: An N3 writer that does not nest bNode strutures but
+ does write record-like groups of all properties for a subject
+- N3-TRIPLE: Writer one statement per line, like N-TRIPLES, but
+ also does qname conversion of URIrefs.
+
+The standard Jena writer `"N3"` chooses which writer to use based on
+the system property `com.hp.hpl.jena.n3.N3JenaWriter.writer`.
+
+If none of these produce N3 to your liking, it is possible to
+further [customize](#n3-output) the output.
+
+## Character Encoding Issues
+
+The easiest way to not read or understand this section is always to
+use `InputStream`s and `OutputStream`s with Jena, and to never use
+`Reader`s and `Writer`s. If you do this, Jena will do the right thing,
+for the vast majority of users. If you have legacy code that uses
+`Reader`s and `Writer`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.
+
+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.
+
+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.
+
+The XML approach is designed for the Web which uses multiple
+encodings, and some of them requiring thousands of characters.
+
+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
+[IANA](http://www.iana.org/assignments/character-sets), but other
+systems have no obligations to support any of these, other than
+UTF-8 and UTF-16.
+
+Within Java, encodings appear primarily with the `InputStreamReader`
+and `OutputStreamWriter` classes, which convert between bytes and
+characters using a named encoding, and with their subclasses,
+`FileReader` and `FileWriter`, 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 `Reader` or `Writer`
+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.
+
+### Encodings Supported in Jena 2.2 and later
+
+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.
+
+On RDF/XML output any encoding supported by Java can be used, by
+constructing an `OutputStreamWriter` 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.
+
+Java can be configured either with or without a jar of extra
+encodings on the classpath. This jar is `charsets.jar` and sits in
+the `lib` directory of the Java Runtime. If this jar is not on your
+classpath then the range of encodings supported is fairly small.
+
+The encodings supported by Java are listed by Sun, for
+[1.4.2](http://java.sun.com/j2se/1.4.2/docs/guide/intl/encoding.doc.html),
+and
+[1.5.0](http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html).
+For an encoding that is not in these lists it is possible to write
+your own transcoder as documented in the `java.nio.charset` package
+documentation.
+
+Earlier versions of Jena supported fewer encodings.
+
+## When to Use Reader and Writer?
+
+Infrequently.
+
+Despite the character encoding issues, it is still sometimes
+appropriate to use `Reader`s and `Writer`s with Jena I/O. A good
+example is using `Reader`s and `Writer`s into `StringBuffer`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.
+
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.Reader, java.lang.String))`(java.io.Reader reader, java.lang.String base)`
+<br />Using this method is often a mistake.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.Reader, java.lang.String, java.lang.String))`(java.io.Reader reader, java.lang.String base, java.lang.String lang)`
+<br />Using this method is often a mistake.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer))`(java.io.Writer writer)`
+<br />Caution! Write the model as an XML document.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer, java.lang.String))`(java.io.Writer writer, java.lang.String lang)`
+<br /> Caution! Write a serialized representation of a model in a specified language.
+- [`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.Writer, java.lang.String, java.lang.String))`(java.io.Writer writer, java.lang.String lang, java.lang.String base)`
+<br /> Caution! Write a serialized representation of a model in a specified language.
+
+Incorrect use of these `read(Reader, â¦)` 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 `write(Writer, â¦)` methods
+results in peculiar XML declarations such as
+`<?xml version="1.0" encoding="WINDOWS-1252"?>`. 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
+[notes](http://nagoya.apache.org/bugzilla/show_bug.cgi?id=4456):
+
+> 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.
+
+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.
+
+## Introduction to Advanced Jena I/O
+
+The RDF/XML input and output is configurable.
+However, to configure it, it is necessary to access an `RDFReader` or
+`RDFWriter` object that remains hidden in the simpler interface
+above.
+
+The four vital calls in the `Model` interface are:
+
+- [`RDFReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader())`()`
+<br />Return an RDFReader instance for the default serialization language.
+- [`RDFReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader(java.lang.String))`(java.lang.String lang)`
+<br />Return an RDFReader instance for the specified serialization language.
+- [`RDFReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getWriter`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter())`()`
+<br />Return an RDFWriter instance for the default serialization language.
+- [`RDFReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getWriter`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String))`(java.lang.String lang)`
+<br />An RDFWriter instance for the specified serialization language.
+
+Each of these calls returns an `RDFReader` or `RDFWriter` that can be
+used to read or write any `Model` (not just the one which created
+it). As well as the necessary
+[`read`](/jena/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))
+and
+[`write`](/jena/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))
+methods, these interfaces provide:
+
+- [`RDFErrorHandler`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html)
+[`setErrorHandler`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler))`(` [RDFErrorHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html) `errHandler )`
+<br />Set an error handler for the reader
+- `java.lang.Object`
+[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setProperty(java.lang.String, java.lang.Object))`(java.lang.String propName, java.lang.Object propValue)`
+<br />Set the value of a reader property.
+
+Setting properties, or the error handler, on an `RDFReader` or an
+`RDFWriter` allows the programmer to access non-default behaviour.
+Moreover, since the `RDFReader` and `RDFWriter` is not bound to a
+specific `Model`, a typical idiom is to create the `RDFReader` or
+`RDFWriter` 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.
+
+ Model m = Modelfactory.createDefaultModel();
+ RDFWriter writer = m.getRDFWriter();
+ m = null; // m is no longer needed.
+ writer.setErrorHandler(myErrorHandler);
+ writer.setProperty("showXmlDeclaration","true");
+ writer.setProperty("tab","8");
+ writer.setProperty("relativeURIs","same-document,relative");
+ â¦
+ Model marray[];
+ â¦
+ for (int i=0; i<marray.length; i++) {
+ â¦
+ OutputStream out = new FileOutputStream("foo" + i + ".rdf");
+ writer.write(marray[i],
+ out,
+ "http://example.org/");
+ out.close();
+ }
+
+Note that all of the current implementations are synchronized, so
+that a specific `RDFReader` cannot be reading two different documents
+at the same time. In a multi-threaded application this may suggest a
+need for a pool of `RDFReader`s and/or `RDFWriter`s, or alternatively
+to create, initialize, use and discard them as needed.
+
+For N-TRIPLE there are currently no properties supported for
+either the `RDFReader` or the `RDFWriter`. Hence this idiom above is
+not very helpful, and just using the `Model.write()` methods may
+prove easier.
+
+For RDF/XML and RDF/XML-ABBREV, there are many options in both the
+`RDFReader` and the `RDFWriter`. N3 has options on the `RDFWriter`. These
+options are detailed below. For RDF/XML they are also found in the
+JavaDoc for
+`JenaReader.`[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`
+and
+`RDFXMLWriterI.`[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/xmloutput/RDFXMLWriterI.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`.
+
+## Advanced RDF/XML Input
+
+For access to these advanced features, first get an `RDFReader`
+object that is an instance of an ARP parser, by using the
+[`getReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader())`()`
+method on any `Model`. It is then configured using the
+[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`
+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
+[RDF grammar](http://www.w3.org/TR/rdf-syntax-grammar/#section-Infoset-Grammar)
+over a [Xerces2-J](http://xml.apache.org/xerces2-j/index.html) XML
+parser). However, changing the features and properties of the XML
+parser is not likely to be useful, but was easy to implement.
+
+[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`
+can be used to set and get:
+
+- ARP properties
+ <br /> These allow fine grain control over the extensive error
+ reporting capabilities of ARP. And are detailed directly below.
+- SAX2 features
+ <br />See
+ [Xerces features](http://xml.apache.org/xerces2-j/features.html).
+ Value should be given as a String `"true"` or `"false"` or a `Boolean`.
+- SAX2 properties
+ <br /> See [Xerces properties](http://xml.apache.org/xerces2-j/properties.html).
+- Xerces features
+ <br /> See [Xerces features](http://xml.apache.org/xerces2-j/features.html).
+ Value should be given as a String `"true"` or `"false"` or a `Boolean`.
+- Xerces properties
+ <br /> See [Xerces properties](http://xml.apache.org/xerces2-j/properties.html).
+
+### ARP properties
+
+An ARP property is referred to either by its property name, (see
+below) or by an absolute URL of the form
+`http://jena.hpl.hp.com/arp/properties/<PropertyName>`. The value
+should be a String, an Integer or a Boolean depending on the
+property.
+
+ARP property names and string values are case insensitive.
+
+Property Name | Description | Value class | Legal Values
+------------- | ----------- | ----------- | ------------
+`iri-rules` | Set the engine for checking and resolving. `"strict"` sets the IRI engine with rules for valid IRIs, XLink and RDF; it does not permit spaces in IRIs. `"iri"`sets the IRI engine to IRI ([RFC 3986](http://www.ietf.org/rfc/rfc3986.txt), [RFC 3987](http://www.ietf.org/rfc/rfc3987.txt)) `.` The default is `"lax"`(for backwards compatibility)`,` the rules for RDF URI references only, which does permit spaces although the use of spaces is not good practice. | String | `lax`<br />`strict`<br />`iri`
+`error-mode`| [`ARPOptions.setDefaultErrorMode()`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setDefaultErrorMode()) <br />[`ARPOptions.setLaxErrorMode()`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setLaxErrorMode())<br />[`ARPOptions.setStrictErrorMode()`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setStrictErrorMode())<br />[`ARPOptions.setStrictErrorMode(int)`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setStrictErrorMode(int))<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. | `String` | `default`<br />`lax`<br />`strict`<br />`strict-ignore`<br />`strict-warning`<br />`strict-error`<br />`strict-fatal`
+`embedding` | [`ARPOptions.setEmbedding(boolean)`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setEmbedding(boolean)) <br />This sets ARP to look for RDF embedded within an enclosing XML document. | `String` or `Boolean` | `true`<br />`false`
+`ERR_<XXX>` <br />`WARN_<XXX>`<br />`IGN_<XXX>` | See [`ARPErrorNumbers`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html) for a complete list of the error conditions detected. Setting one of these properties is equivalent to the method [`ARPOptions.setErrorMode(int, int)`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setErrorMode(int,%20int)). Thus fine-grained control over the behaviour in response to specific error conditions is possible.| `String` or `Integer` | [`EM_IGNORE`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_IGNORE)<br />[`EM_WARNING`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_WARNING)<br />[`EM_ERROR`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_ERROR)<br />[`EM_FATAL`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_FATAL)
+
+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:
+
+ Model m = Modelfactory.createDefaultModel();
+ RDFReader arp = m.getReader();
+ m = null; // m is no longer needed.
+ // initialize arp
+ // Do not warn on use of unqualified RDF attributes.
+ arp.setProperty("WARN_UNQUALIFIED_RDF_ATTRIBUTE","EM_IGNORE");
+
+ â¦
+
+ InputStream in = new FileInputStream(fname);
+ arp.read(m,in,url);
+ in.close();
+
+As a second example, suppose you wish to work in strict mode, but
+allow `"daml:collection"`, the following works:
+
+ â¦
+ arp.setProperty("error-mode", "strict" );
+ arp.setProperty("IGN_DAML_COLLECTION","EM_IGNORE");
+ â¦
+
+The other way round does not work.
+
+ â¦
+ arp.setProperty("IGN_DAML_COLLECTION","EM_IGNORE");
+ arp.setProperty("error-mode", "strict" );
+ â¦
+
+This is because in strict mode
+[`IGN_DAML_COLLECTION`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#IGN_DAML_COLLECTION)
+is treated as an error, and so the second call to `setProperty`
+overwrites the effect of the first.
+
+The IRI rules and resolver can be set on a per-reader basis:
+
+ InputStream in = ... ;
+ String baseURI = ... ;
+ Model model = Modelfactory.createDefaultModel();
+ RDFReader r = model.getReader("RDF/XML");
+ r.setProperty("iri-rules", "strict") ;
+ r.setProperty("error-mode", "strict") ; // Warning will be errors.
+
+ // Alternative to the above "error-mode": set specific warning to be an error.
+ //r.setProperty( "WARN_MALFORMED_URI", ARPErrorNumbers.EM_ERROR) ;
+ r.read(model, in, baseURI) ;
+ in.close();
+
+The global default IRI engine can be set with:
+
+ ARPOptions.setIRIFactoryGlobal(IRIFactory.iriImplementation()) ;
+
+or other IRI rule engine from `IRIFactory`.
+
+### Interrupting ARP
+
+ARP can be interrupted using the `Thread.interrupt()` method. This
+causes an
+[`ERR_INTERRUPTED`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#ERR_INTERRUPTED)
+error during the parse, which is usually treated as a fatal error.
+
+Here is an illustrative code sample:
+
+ ARP a = new ARP();
+ final Thread arpt = Thread.currentThread();
+ Thread killt = new Thread(new Runnable() {
+ public void run() {
+ try {
+ Thread.sleep(tim);
+ } catch (InterruptedException e) {
+ }
+ arpt.interrupt();
+ }
+ });
+ killt.start();
+ try {
+ in = new FileInputStream(fileName);
+ a.load(in);
+ in.close();
+ fail("Thread was not interrupted.");
+ } catch (SAXParseException e) {
+ }
+
+## Advanced RDF/XML Output
+
+The first RDF/XML output question is whether to use the `"RDF/XML"`
+or `RDF/XML-ABBREV` writer. While some of the code is shared, these
+two writers are really very different, resulting in different but
+equivalent output. `RDF/XML-ABBREV` is slower, but should produce
+more readable XML.
+
+For access to advanced features, first get an RDFWriter object, of
+the appropriate language, by using
+[`getWriter`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String))`("RDF/XML")`
+or
+[`getWriter`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String))`("RDF/XML-ABBREV")`
+on any `Model`. It is then configured using the
+[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`
+method. This changes the properties for writing RDF/XML.
+
+### Properties to Control RDF/XML Output
+<table>
+<tr><th>Property Name</th><th>Description</th><th>Value class</th><th>Legal Values</th></tr>
+<tr>
+<td>`xmlbase`</td>
+<td>The value to be included for an xml:base attribute on the root element in the file.</td>
+<td>`String`</td>
+<td>A URI string, or null (default)</td>
+</tr>
+<tr>
+<td>`longId`</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>`String` or `Boolean`</td>
+<td>`"true"`, `"false"` (default)</td>
+</tr>
+<tr>
+<td>`allowBadURIs`</td>
+<td>URIs in the graph are, by default, checked prior to serialization.</td>
+<td>`String` or `Boolean`</td>
+<td>`"true"`, `"false"` (default)</td>
+</tr>
+<tr>
+<td>`relativeURIs`</td>
+<td>What sort of relative URIs should be used. A comma separated list of options:
+
+- *same-document*<br />
+ same-document references (e.g. "" or "\#foo")
+- *network*<br />
+ network paths e.g. `"//example.org/foo"` omitting the URI scheme
+- *absolute*<br />
+ absolute paths e.g. `"/foo"` omitting the scheme and authority
+- *relative*<br />
+ relative path not beginning in `"../"`
+- *parent*<br />
+ relative path beginning in `"../"`
+- *grandparent*<br />
+ relative path begining in `"../../"`
+
+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>`showXmlDeclaration`</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 `OutputStreamWriter`
+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:
+
+- Set this option to true and use the
+ `write(Model,Writer,String)` variant with an appropriate `OutputStreamWriter`.
+- Or set this option to false, and write the declaration to an `OutputStream` before calling
+ `write(Model,OutputStream,String)`.
+</td>
+<td>`true`, `"true"`, `false`, `"false"` or `"default"`</td>
+<td>can be true, false or "default" (null)</td>
+</tr>
+<tr>
+<td>`showDoctypeDeclaration`</td>
+<td>
+If true, an XML Doctype declaration is included in the output. This
+declaration includes a `!ENTITY` 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>`String` or `Boolean`</td>
+<td>`true`, `false`, `"true"`, `"false"`</td>
+</tr>
+<tr>
+<td>`tab`</td>
+<td>The number of spaces with which to indent XML child elements.</td>
+<td>`String` or `Integer`</td>
+<td>positive integer "2" is the default</td>
+</tr>
+<tr>
+<td>`attributeQuoteChar`</td>
+<td>How to write XML attributes.</td>
+<td>`String`</td>
+<td>`"\""` or `"'"`</td>
+</tr>
+<tr>
+<td>`blockRules`</td>
+<td>A list of `Resource` or a `String` being a comma separated list of
+fragment IDs from
+[http://www.w3.org/TR/rdf-syntax-grammar](http://www.w3.org/TR/rdf-syntax-grammar)
+indicating grammar rules that will not be used. Rules that can be
+avoided are:
+
+- [section-Reification](http://www.w3.org/TR/rdf-syntax-grammar#section-Reification)
+ ([`RDFSyntax.sectionReification`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#sectionReification))
+- [section-List-Expand](http://www.w3.org/TR/rdf-syntax-grammar#section-List-Expand)
+ ([`RDFSyntax.sectionListExpand`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#sectionListExpand))
+- [parseTypeLiteralPropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeLiteralPropertyElt)
+ ([`RDFSyntax.parseTypeLiteralPropertyElt`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt))
+- [parseTypeResourcePropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeResourcePropertyElt)
+ ([`RDFSyntax.parseTypeLiteralPropertyElt`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt))
+- [parseTypeCollectionPropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeCollectionPropertyElt)
+ ([`RDFSyntax.parseTypeCollectionPropertyElt`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeCollectionPropertyElt))
+- [idAttr](http://www.w3.org/TR/rdf-syntax-grammar#idAttr)
+ ([`RDFSyntax.idAttr`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#idAttr))
+- [propertyAttr](http://www.w3.org/TR/rdf-syntax-grammar#propertyAttr)
+ ([`RDFSyntax.propertyAttr`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#propertyAttr))
+
+In addition "daml:collection"
+([`DAML_OIL.collection`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/DAML_OIL.html#collection))
+can be blocked. Blocking
+[idAttr](http://www.w3.org/TR/rdf-syntax-grammar#idAttr) also
+blocks
+[section-Reification](http://www.w3.org/TR/rdf-syntax-grammar#section-Reification).
+By default, rule
+[propertyAttr](http://www.w3.org/TR/rdf-syntax-grammar#propertyAttr)
+is blocked. For the basic writer (RDF/XML) only
+[parseTypeLiteralPropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeLiteralPropertyElt)
+has any affect, since none of the other rules are implemented by
+that writer.
+</td>
+<td>Resource[] or String</td>
+</tr>
+<tr>Â
+<td>`prettyTypes`</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.
+
+Example usage showing the a value suitable for DAML+OIL output:
+
+ w.setProperty("prettyTypes",
+ new Resource[]{
+ DAML_OIL.Ontology,
+ DAML_OIL.Class,
+ DAML_OIL.Datatype,
+ DAML_OIL.Property,
+ DAML_OIL.ObjectProperty,
+ DAML_OIL.DatatypeProperty,
+ DAML_OIL.TransitiveProperty,
+ DAML_OIL.UnambigousProperty,
+ DAML_OIL.UniqueProperty,
+ });
+</td>
+<td>
+`Resource[]`
+</td>
+</tr>
+</table>
+Â
+As an example,
+
+ RDFWriter w = m.getWriter("RDF/XML-ABBREV");
+ w.setProperty("attribtueQuoteChar","'");
+ w.setProperty("showXMLDeclaration","true");
+ w.setProperty("tab","1");
+ w.setProperty("blockRules",
+ "daml:collection,parseTypeLiteralPropertyElt,"
+ +"parseTypeResourcePropertyElt,parseTypeCollectionPropertyElt");
+
+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 `"'"`.
+
+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.
+
+## Advanced N3 Output
+
+The N3 pretty printer (which is used by default)Â and the N3 plain
+writer provide a number of properties to control their output. The
+properties all start: `http://jena.hpl.hp.com/n3/properties/`. 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.
+
+### Properties to Control N3 Output
+
+Property Name | Description | Default | Legal Values of String
+------------- | ----------- | ------- | ----------------------
+`minGap` | Minimum gap between items on a line | 1 | positive integer
+`objectLists` | Print object lists as comma separated lists | `true` | boolean `"true"` or `"false"`
+`subjectColumn` | If the subject is shorter than this value, the first property may go on the same line. | `indentProperty` | positive integer
+`propertyColumn` | Width of the property column | 8 | positive integer
+`indentProperty` | Width to indent properties | 6 | positive integer
+`widePropertyLen` | Width of the property column | 20 | integer, greater than `propertyColumn`
+`abbrevBaseURI` | Control whether to use abbreviations `<>` or `<#>` | true | boolean `"true"` or `"false"`
+`usePropertySymbols` | Control whether to use `"a"`, `"="` and `"=\>"` in output | true | boolean `"true"` or `"false"`
+`useTripleQuotedStrings` | Allow the use of `"""` to delimit long strings | true | boolean `"true"` or `"false"`
+`useDoubles` | Allow the use doubles as 123.456 | true | boolean `"true"` or `"false"`
+
+Notes:
+
+1. Only the N3 pretty printer print object lists as comma-separated lists.
+
+## Conformance
+
+The RDF/XML I/O endeavours to conform with the
+[RDF Syntax Recommendation](http://www.w3.org/TR/rdf-syntax-grammar/).
+
+The parser must be set to strict mode. (Note that, the conformant
+behaviour for `rdf:parseType="daml:collection"` is to silently turn
+`"daml:collection"` into `"Literal"`).
+
+The RDF/XML writer is conformant, but does not exercise much of the
+grammar.
+
+The RDF/XML-ABBREV writer exercises all of the grammar and is
+conformant except that it uses the `daml:collection` construct for
+DAML ontologies. This non-conformant behaviour can be switched off
+using the `blockRules` property.
+
+
+## Faster RDF/XML I/O
+
+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:
+
+ Model m;
+ â¦
+ â¦
+ RDFWriter fasterWriter = m.getWriter("RDF/XML");
+ fasterWriter.setProperty("allowBadURIs","true");
+ fasterWriter.setProperty("relativeURIs","");
+ fasterWriter.setProperty("tab","0");
+
+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.
+
+ Model m;
+ â¦
+ â¦
+ RDFReader bigFileReader = m.getReader("RDF/XML");
+ bigFileReader.setProperty("WARN_REDEFINITION_OF_ID","EM_IGNORE");
+ â¦
+
+
+
Added: incubator/jena/site/trunk/content/jena/documentation/io/sax.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/sax.mdtext?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/sax.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/sax.mdtext Wed Oct 19 23:18:13 2011
@@ -0,0 +1,199 @@
+Title: SAX Input into Jena and ARP
+
+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.
+
+## Contents
+
+- [Overview](#overview)
+- [Sample Code](#sample_code)
+- [Initializing SAX event source](#initializing_sax_event_source)
+- [Error Handler](#error_handler)
+- [Options](#options)
+- [XML Lang and Namespaces](#xml_lang_and_namespaces)
+- [Using your own statement handler](#using_your_own_statement_handler)
+- [Using a DOM as input](#using_a_dom_as_input)
+
+## 1. Overview
+
+To read an arbitrary SAX source as triples to be added into a Jena
+model, it is not possible to use a
+`Model.`[`read`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html#read(java.io.InputStream,%20java.lang.String))()
+operation. Instead, you construct a SAX event handler of class
+[`SAX2Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html),
+using the
+[`create`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html#create(java.lang.String,%20com.hp.hpl.jena.rdf.model.Model))
+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
+[`SAX2Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html)
+handler.
+
+## Sample Code
+
+This code uses the Xerces parser as a SAX event stream, and adds
+the triple to a
+[`Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) using
+default options.
+
+ // Use your own SAX source.
+ XMLReader saxParser = new SAXParser();
+
+ // set up SAX input
+ InputStream in = new FileInputStream("kb.rdf");
+ InputSource ins = new InputSource(in);
+ ins.setSystemId(base);
+
+ Model m = ModelFactory.createDefaultModel();
+ String base = "http://example.org/";
+
+ // create handler, linked to Model
+ SAX2Model handler = SAX2Model.create(base, m);
+
+ // install handler on SAX event stream
+ SAX2RDF.installHandlers(saxParser, handler);
+
+ try {
+ try {
+ saxParser.parse(ins);
+ } finally {
+ // MUST ensure handler is closed.
+ handler.close();
+ }
+ } catch (SAXParseException e) {
+ // Fatal parsing errors end here,
+ // but they will already have been reported.
+ }
+
+## Initializing SAX event source
+
+If your SAX event source is a subclass of `XMLReader`, then the
+[installHandlers](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#installHandlers(org.xml.sax.XMLReader,%20com.hp.hpl.jena.rdf.arp.XMLHandler))
+static method can be used as shown in the sample. Otherwise, you
+have to do it yourself. The
+[`installHandlers`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#installHandlers(org.xml.sax.XMLReader,%20com.hp.hpl.jena.rdf.arp.XMLHandler))
+code is like this:
+
+ static public void installHandlers(XMLReader rdr, XMLHandler sax2rdf)
+ throws SAXException
+ {
+ rdr.setEntityResolver(sax2rdf);
+ rdr.setDTDHandler(sax2rdf);
+ rdr.setContentHandler(sax2rdf);
+ rdr.setErrorHandler(sax2rdf);
+ rdr.setFeature("http://xml.org/sax/features/namespaces", true);
+ rdr.setFeature(
+ "http://xml.org/sax/features/namespace-prefixes",
+ true);
+ rdr.setProperty(
+ "http://xml.org/sax/properties/lexical-handler",
+ sax2rdf);
+ }
+
+For some other SAX source, the exact code will differ, but the
+required operations are as above.
+
+## Error Handler
+
+The [SAX2Model](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html)
+handler supports the
+[setErrorHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler))
+method, from the Jena
+[RDFReader](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+interface. This is used in the same way as that method to control
+error reporting.
+
+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.
+
+## Options
+
+The [`SAX2Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html)
+handler supports the
+[`setProperty`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setProperty(java.lang.String,%20java.lang.Object))
+method, from the Jena
+[`RDFReader`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+interface. This is used in nearly the same way to have fine grain
+control over ARPs behaviour, particularly over error reporting, see
+the [I/O howto](iohowto.html#arp_properties). Setting SAX or
+Xerces properties cannot be done using this method.
+
+## XML Lang and Namespaces
+
+If you are only treating some document subset as RDF/XML then it is
+necessary to ensure that ARP knows the correct value for `xml:lang`
+and desirable that it knows the correct mappings of namespace
+prefixes.
+
+There is a second version of the
+[`create`](/jena/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))
+method, which allows specification of the `xml:lang` value from the
+outer context. If this is inappropriate it is possible, but hard
+work, to synthesis an appropriate SAX event.
+
+For the namespaces prefixes, it is possible to call the
+[`startPrefixMapping`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#startPrefixMapping(java.lang.String,%20java.lang.String))
+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.
+
+## Using your own triple handler
+
+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
+[SAX2RDF](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html). The
+[create](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#create(java.lang.String))
+method on this class does not provide any means of specifying what
+to do with the triples. Instead, the class implements the
+[ARPConfig](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html)
+interface, which permits the setting of handlers and parser
+options, as described in the documentation for using
+[ARP without Jena](standalone.html).
+
+Thus you need to:
+
+1. Create a SAX2RDF using
+ [SAX2RDF.create()](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#create(java.lang.String))
+2. Attach your StatementHandler and SAXErrorHandler and optionally
+ your NamespaceHandler and ExtendedHandler to the SAX2RDF instance.
+3. Install the SAX2RDF instance as the SAX handler on your SAX
+ source.
+4. Follow the remainder of the code sample above.
+
+## Using a DOM as Input
+
+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.
+
+### Using a DOM as Input to Jena
+
+The [`DOM2Model`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html)
+subclass of SAX2Model, allows the parsing of a DOM using ARP. The
+procedure to follow is:
+
+- Construct a `DOM2Model`, using a factory method such as
+ [`createD2M`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html#createD2M(java.lang.String,%20com.hp.hpl.jena.rdf.model.Model)),
+ 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).
+- Set any properties, error handlers etc. on the `DOM2Model`
+ object.
+- The DOM is parsed simply by calling the
+ [`load(Node)`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/DOM2Model.html#load(org.w3c.dom.Node))
+ method.
+
+### Using a DOM as Input to ARP
+
+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.
Added: incubator/jena/site/trunk/content/jena/documentation/io/standalone.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/content/jena/documentation/io/standalone.mdtext?rev=1186560&view=auto
==============================================================================
--- incubator/jena/site/trunk/content/jena/documentation/io/standalone.mdtext (added)
+++ incubator/jena/site/trunk/content/jena/documentation/io/standalone.mdtext Wed Oct 19 23:18:13 2011
@@ -0,0 +1,191 @@
+Title: Using ARP Without Jena
+
+ARP can be used both as a Jena subsystem, or as a standalone
+RDF/XML parser. This document gives a quick guide to using ARP
+standalone.
+
+## Contents
+
+- [Overview](#overview)
+- [Sample Code](#sample)
+- [ARP Event Handling](#handlers)
+- [Configuring ARP](#config)
+- [Interrupting ARP](#interrupt)
+- [Using Other SAX Sources](#sax2rdf)
+- [Memory usage](#memory)
+
+## Overview
+
+To load an RDF file:
+
+1. Create an
+ [ARP](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARP.html#ARP()) instance.
+2. Set parse options, particularly error detection control, using
+ [getOptions](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions())
+ or
+ [setOptionsWith](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setOptionsWith(com.hp.hpl.jena.rdf.arp.ARPOptions)).
+3. Set its handlers, by calling the
+ [getHandlers](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getHandlers())
+ or
+ [setHandlersWith](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setHandlersWith(com.hp.hpl.jena.rdf.arp.ARPHandlers))
+ methods, and then.
+ - Setting the
+ [statement handler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setStatementHandler(com.hp.hpl.jena.rdf.arp.StatementHandler)).
+ - Optionally setting the other handlers.
+4. Call a
+ [load](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARP.html#load(java.io.InputStream,%20java.lang.String))
+ method
+
+Xerces is used for parsing the XML. The SAXEvents generated by
+Xerces are then analysed as RDF by ARP. It is possible to use a
+different source of SAX events.
+
+Errors may occur in either the XML or the RDF part.
+
+## Sample Code
+
+ ARP arp = new ARP();
+
+ // initialisation - uses ARPConfig interface only.
+ arp.getOptions().setLaxErrorMode();
+
+ arp.getHandlers().setErrorHandler(new ErrorHandler(){
+ public void fatalError(SAXParseException e){
+ // TODO code
+ }
+ public void error(SAXParseException e){
+ // TODO code
+ }
+ public void warning(SAXParseException e){
+ // TODO code
+ }
+ });
+ arp.getHandlers().setStatementHandler(new StatementHandler(){
+ public void statement(AResource a, AResource b, ALiteral l){
+ // TODO code
+ }
+ public void statement(AResource a, AResource b, AResource l){
+ // TODO code
+ }
+ });
+
+ // parsing.
+
+ try {
+ // Loading fixed input ...
+ arp.load(new StringReader(
+ "<rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'>\n"
+ +"<rdf:Description><rdf:value rdf:parseType='Literal'>"
+ +"<b>hello</b></rdf:value>\n"
+ +"</rdf:Description></rdf:RDF>"
+ ));
+
+ }
+ catch (IOException ioe){
+ // something unexpected went wrong
+ }
+ catch (SAXParseException s){
+ // This error will have been reported
+ }
+ catch (SAXException ss) {
+ // This error will not have been reported.
+ }
+
+## ARP Event Handling
+
+ARP reports events concerning:
+
+- Triples found in the input.
+- Errors in the input.
+- Namespace declarations.
+- Scope of blank nodes.
+
+User code is needed to respond to any of these events of interest.
+This is written by implementing any of the relevant interfaces:
+[StatementHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/StatementHandler.html),
+org.xml.sax.ErrorHandler,
+[NamespaceHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/NamespaceHandler.html),
+and
+[ExtendedHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html).
+
+An individual handler is set by calling the
+[getHandlers](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getHandlers())
+method on the ARP instance. This returns an encapsulation of all
+the handlers being used. A specific handler is set by calling the
+appropriate set...Handler method on that object, e.g.
+[setStatementHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setStatementHandler(com.hp.hpl.jena.rdf.arp.StatementHandler)).
+
+All the handlers can be copied from one ARP instance to another by
+using the
+[setHandlersWith](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#setHandlersWith(com.hp.hpl.jena.rdf.arp.ARPHandlers))
+method:
+
+ ARP from, to;
+ // initialize from and to
+ // ...
+
+ to.setHandlersWith(from.getHandlers());
+
+The error handler reports both XML and RDF errors, the former
+detected by Xerces. See
+[ARPHandlers.setErrorHandler](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPHandlers.html#setErrorHandler(org.xml.sax.ErrorHandler))
+for details of how to distinguish between them.
+
+## Configuring ARP
+
+ARP can be configured to treat most error conditions as warnings or
+to be ignored, and to treat some non-error conditions as warnings
+or errors.
+
+In addition, the behaviour in response to input that does not have
+an `<rdf:RDF>` root element is configurable: either to treat the
+whole file as RDF anyway, or to scan the file looking for embedded
+`<rdf:RDF>` elements.
+
+As with the handlers, there is an options object that encapsulates
+these settings. It can be accessed using
+[`getOptions`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions()),
+and then individual settings can be made using the methods in
+[`ARPOptions`](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html).
+
+It is also possible to copy all the option settings from one ARP
+instance to another:
+
+ ARP from, to;
+ // initialize from and to ...
+
+ to.setOptionsWith(from.getOptions());
+
+The [I/O how-to](iohowto.html#arp_properties) gives some more
+detail about the options settings, although it assumes the use of
+the Jena `RDFReader` interface.
+
+## Interrupting ARP
+
+It is possible to interrupt an ARP thread. See the
+[I/O how-to](iohowto.html#interrupting_arp) for details.
+
+## Using Other SAX Sources
+
+It is possible to use ARP with other SAX input sources, e.g. from a
+non-Xerces parser, or from an in-memory XML source, such as a DOM
+tree.
+
+Instead of an ARP instance, you create an instance of
+[SAX2RDF](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html) using
+the [newInstance](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html#newInstance(java.lang.String))
+method. This can be configured just like an ARP instance, following
+the initialization section of the [sample code](#sample).
+
+This is used like a SAX2Model instance as
+[described elsewhere](sax.html).
+
+## Memory usage
+
+For very large files, ARP does not use any additional memory except
+when either the
+[ExtendedHandler.discardNodesWithNodeID](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html#discardNodesWithNodeID())
+returns false or when the
+[AResource.setUserData](/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/AResource.html#setUserData(java.lang.Object))
+method has been used. In these cases ARP needs to remember the
+`rdf:nodeID` usage through the file life time.
Modified: incubator/jena/site/trunk/templates/sidenav.mdtext
URL: http://svn.apache.org/viewvc/incubator/jena/site/trunk/templates/sidenav.mdtext?rev=1186560&r1=1186559&r2=1186560&view=diff
==============================================================================
--- incubator/jena/site/trunk/templates/sidenav.mdtext (original)
+++ incubator/jena/site/trunk/templates/sidenav.mdtext Wed Oct 19 23:18:13 2011
@@ -49,6 +49,8 @@
- [Assembler](/jena/documentation/assembler/index.html)
- [Assembler how-to](/jena/documentation/assembler/assembler-howto.html)
- [Inside assemblers](/jena/documentation/assembler/inside-assemblers.html)
+ - [I/O](/jena/documentation/io/index.html)
+ - [I/O how-to](/jena/documentation/io/iohowto.html)
- [Notes](/jena/documentation/notes/index.html)
- [Concurrency how-to](/jena/documentation/notes/concurrency-howto.html)
- [Event handler how-to](/jena/documentation/notes/event-handler-howto.html)