You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by an...@apache.org on 2013/01/01 16:27:39 UTC
svn commit: r1427439 [1/2] - in /jena/site/trunk: content/
content/documentation/io/ content/documentation/notes/
content/documentation/rdf/ templates/
Author: andy
Date: Tue Jan 1 15:27:39 2013
New Revision: 1427439
URL: http://svn.apache.org/viewvc?rev=1427439&view=rev
Log:
Update documentation for Jena 2.10.0 (reficiation, RIOT)
Added:
jena/site/trunk/content/documentation/io/arp.mdtext
jena/site/trunk/content/documentation/io/arp_features.mdtext
jena/site/trunk/content/documentation/io/arp_howto.mdtext
jena/site/trunk/content/documentation/io/arp_sax.mdtext
jena/site/trunk/content/documentation/io/arp_standalone.mdtext
jena/site/trunk/content/documentation/io/rdf-json.html
jena/site/trunk/content/documentation/io/rdf-output.mdtext
Removed:
jena/site/trunk/content/documentation/io/features.mdtext
jena/site/trunk/content/documentation/io/iohowto.mdtext
jena/site/trunk/content/documentation/io/riot.mdtext
jena/site/trunk/content/documentation/io/sax.mdtext
jena/site/trunk/content/documentation/io/standalone.mdtext
Modified:
jena/site/trunk/content/documentation/io/index.mdtext
jena/site/trunk/content/documentation/notes/model-factory.mdtext
jena/site/trunk/content/documentation/rdf/index.mdtext
jena/site/trunk/content/ia.txt
jena/site/trunk/templates/sidenav.mdtext
Added: jena/site/trunk/content/documentation/io/arp.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/arp.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/arp.mdtext (added)
+++ jena/site/trunk/content/documentation/io/arp.mdtext Tue Jan 1 15:27:39 2013
@@ -0,0 +1,9 @@
+Title: RDF/XML Handling in Jena
+
+This section details the Jena RDF/XML parser.
+ARP is the parsing subsystem in Jena for handling the RDF/XML syntax.
+
+- [Using ARP](arp_howto.html)
+- [ARP Features](arp_features.html)
+- [Using ARP without Jena](arp_standalone.html)
+- [Using other SAX and DOM XML sources](arp_sax.html)
Added: jena/site/trunk/content/documentation/io/arp_features.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/arp_features.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/arp_features.mdtext (added)
+++ jena/site/trunk/content/documentation/io/arp_features.mdtext Tue Jan 1 15:27:39 2013
@@ -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: jena/site/trunk/content/documentation/io/arp_howto.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/arp_howto.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/arp_howto.mdtext (added)
+++ jena/site/trunk/content/documentation/io/arp_howto.mdtext Tue Jan 1 15:27:39 2013
@@ -0,0 +1,645 @@
+Title: Jena RDF/XML How-To
+
+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.
+
+
+## Contents
+
+- [Quick Introduction](#quick-introduction)
+- [RDF/XML, RDF/XML-ABBREV](#rdfxml-rdfxml-abbrev)
+- [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)
+- [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.
+This is import to correctly handle character sets.
+
+These methods are found on the
+[`Model`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) interface.
+These are:
+
+- [`Model`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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"` as well as
+`"N-TRIPLE"`, and `"TURTLE"`.
+
+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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#ERR_ENCODING_MISMATCH)
+and
+[`WARN_ENCODING_MISMATCH`](/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).
+
+## 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://docs.oracle.com/javase/1.4.2/docs/guide/intl/encoding.doc.html),
+and
+[1.5.0](http://docs.oracle.com/javase/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`read`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Model.html) [`write`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getReader`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader())`()`
+<br />Return an RDFReader instance for the default serialization language.
+- [`RDFReader`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getReader`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getWriter`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter())`()`
+<br />Return an RDFWriter instance for the default serialization language.
+- [`RDFReader`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html)
+[`getWriter`](/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`](/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`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html)
+[`setErrorHandler`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler))`(` [RDFErrorHandler](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFErrorHandler.html) `errHandler )`
+<br />Set an error handler for the reader
+- `java.lang.Object`
+[`setProperty`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/JenaReader.html#setProperty(java.lang.String, java.lang.Object))`(String, Object)`
+and
+`RDFXMLWriterI.`[`setProperty`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReaderF.html#getReader())`()`
+method on any `Model`. It is then configured using the
+[`setProperty`](/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`](/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()`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setDefaultErrorMode()) <br />[`ARPOptions.setLaxErrorMode()`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setLaxErrorMode())<br />[`ARPOptions.setStrictErrorMode()`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPOptions.html#setStrictErrorMode())<br />[`ARPOptions.setStrictErrorMode(int)`](/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)`](/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`](/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)`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_IGNORE)<br />[`EM_WARNING`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_WARNING)<br />[`EM_ERROR`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPErrorNumbers.html#EM_ERROR)<br />[`EM_FATAL`](/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`](/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`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFWriterF.html#getWriter(java.lang.String))`("RDF/XML")`
+or
+[`getWriter`](/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`](/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 blocked are:
+
+- [section-Reification](http://www.w3.org/TR/rdf-syntax-grammar#section-Reification)
+ ([`RDFSyntax.sectionReification`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#sectionListExpand))
+- [parseTypeLiteralPropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeLiteralPropertyElt)
+ ([`RDFSyntax.parseTypeLiteralPropertyElt`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt))
+- [parseTypeResourcePropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeResourcePropertyElt)
+ ([`RDFSyntax.parseTypeLiteralPropertyElt`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeLiteralPropertyElt))
+- [parseTypeCollectionPropertyElt](http://www.w3.org/TR/rdf-syntax-grammar#parseTypeCollectionPropertyElt)
+ ([`RDFSyntax.parseTypeCollectionPropertyElt`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#parseTypeCollectionPropertyElt))
+- [idAttr](http://www.w3.org/TR/rdf-syntax-grammar#idAttr)
+ ([`RDFSyntax.idAttr`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#idAttr))
+- [propertyAttr](http://www.w3.org/TR/rdf-syntax-grammar#propertyAttr)
+ ([`RDFSyntax.propertyAttr`](/documentation/javadoc/jena/com/hp/hpl/jena/vocabulary/RDFSyntax.html#propertyAttr))
+
+In addition `"daml:collection"`
+([`DAML_OIL.collection`](/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 effect, since none of the other rules are implemented by
+that writer.
+</td>
+<td>`Resource[]` or `String`</td>
+<td></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.
+</td>
+<td>
+`Resource[]`
+</td>
+<td></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.
+
+## 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: jena/site/trunk/content/documentation/io/arp_sax.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/arp_sax.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/arp_sax.mdtext (added)
+++ jena/site/trunk/content/documentation/io/arp_sax.mdtext Tue Jan 1 15:27:39 2013
@@ -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 triple handler](#using-your-own-triple-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`](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html),
+using the
+[`create`](/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`](/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`](/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](/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`](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html)
+handler supports the
+[setErrorHandler](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setErrorHandler(com.hp.hpl.jena.rdf.model.RDFErrorHandler))
+method, from the Jena
+[RDFReader](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2Model.html)
+handler supports the
+[`setProperty`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/RDFReader.html#setProperty(java.lang.String,%20java.lang.Object))
+method, from the Jena
+[`RDFReader`](/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`](/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`](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html). The
+[create](/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](/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()](/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`](/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`](/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)`](/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: jena/site/trunk/content/documentation/io/arp_standalone.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/arp_standalone.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/arp_standalone.mdtext (added)
+++ jena/site/trunk/content/documentation/io/arp_standalone.mdtext Tue Jan 1 15:27:39 2013
@@ -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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARP.html#ARP()) instance.
+2. Set parse options, particularly error detection control, using
+ [getOptions](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions())
+ or
+ [setOptionsWith](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getHandlers())
+ or
+ [setHandlersWith](/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](/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](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/StatementHandler.html),
+org.xml.sax.ErrorHandler,
+[NamespaceHandler](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/NamespaceHandler.html),
+and
+[ExtendedHandler](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html).
+
+An individual handler is set by calling the
+[getHandlers](/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](/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](/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](/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`](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ARPConfig.html#getOptions()),
+and then individual settings can be made using the methods in
+[`ARPOptions`](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/SAX2RDF.html) using
+the [newInstance](/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](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/arp/ExtendedHandler.html#discardNodesWithNodeID())
+returns false or when the
+[AResource.setUserData](/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: jena/site/trunk/content/documentation/io/index.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/index.mdtext?rev=1427439&r1=1427438&r2=1427439&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/io/index.mdtext (original)
+++ jena/site/trunk/content/documentation/io/index.mdtext Tue Jan 1 15:27:39 2013
@@ -1,12 +1,273 @@
-Title: RDF input and output handling in Jena
+Title: Reading RDF in Jena
+
+This page details the setup of RDF I/O technology (RIOT) introduced in Jena 2.10.
+
+The output capabilities are described [elsewhere](#rdf-output.html).
+
+- [Formats](#formats)
+- [Commands](#command_line_tools)
+- [Inference](#inference)
+- [API](#api)
+ - [Determining the RDF syntax](#determining_the_rdf_syntax)
+ - [Common usage](#example_1___common_usage)
+ - [Using the RDFDataMgr](##example_2___using_the_rdfdatamgr)
+- [Logging](#logging)
+- [The StreamManager and LocationMapper](#)
+ - [Configuring the `StreamManager`](#configuring_the_streammanager)
+ - [Configuring a `LocationMapper`](#configuring_a_locationmapper)
+- [Add a new language](#add_a_new_language)
+- [Advanced examples](#advanced_examples)
+
+Full details of operations are given in the javadoc.
+
+# Formats
+
+The following RDF formats are supported by Jena. In addition, other syntaxes
+can be integrated into the parser framework.
+
+- RDF/XML
+- Turtle
+- N-Triples
+- RDF/JSON
+- TriG
+- N-Quads
+
+RDF/JSON is not JSON-LD - it is a direct encoding of RDF triples in JSON.
+See the [description of RDF/JSON](rdf-json.html).
+
+See also the [RDF/XML specific documentation](arp.html) for configuration
+of the RDF/XML parser.
+
+# Command line tools
+
+There are scripts in Jena download to run these commands.
+
+- `riot` - parse, guessing the syntax from the file extension.
+ Assumed N-Quads/N-Triples from stdin.
+- `turtle`, `ntriples`, `nquads`, `trig`, `rdfxml` - parse a particular language
+
+These can be called directly as Java programs:
+
+The file extensions are:
+
+| Extension | Language |
+|===========|==========|
+| `.nt` | N-triples |
+| `.ttl` | Turtle |
+| `.nq` | N-Quads |
+| `.trig` | TriG |
+| `.rdf` | RDF/XML |
+| `.owl` | RDF/XML |
+
+In addition, if the extension is .gz the file is assumed to be gzip
+compressed. The file name is examined for an inner extension. For
+example, `.nt.gz` is gzip compressed N-Triples.
+
+These scripts call java programs in the `riotcmd` package. For example:
+
+ java -cp ... riotcmd.riot file.ttl
+
+The scripts all accept the same arguments (type "riot --help" to
+get command line reminders):
+
+- `--validate`: Checking mode: same as --strict --sink --check=true
+- `--check=true/false`: Run with checking of literals and IRIs either on or off.
+- `--sink`: No output of triples or quads.
+- `--time`: Output timing information.
+
+To aid in checking for errors in UTF8-encoded files, there is a
+utility which reads a file of bytes as UTF8 and checks the encoding.
+
+- `utf8` -- read bytes as UTF8
+
+# Inference
+
+RIOT support creation of inferred triples during the parsing
+process:
+
+ riotcmd.infer --rdfs VOCAB FILE FILE ...
+
+Output will contain the base data and triples inferred based on
+subclass, subproperty, domain and range.
+
+# API
+
+Much of the functionality is accessed via the Jena Model API; direct
+calling of the RIOT subsystem isn't needed. A resource name
+with no URI scheme is assumed to be a local file name.
+
+Applications typically use at most `RDFDataMgr` to read RDF datasets.
+
+The major classes in the RIOT API are:
+
+| Class | Comment |
+|-------|---------|
+| RDFDataMgr | Main set of functions to read and load models and datasets |
+| StreamManager | Handles the opening of types input streams |
+| StreamRDF | Interface for the output of all parsers |
+| RDFLanguages | Registered languages |
+| RDFParserRegistry | Registered parser factories |
+
+## Determining the RDF syntax
+
+The syntax of the RDF file is determined by the content type (if an HTTP
+request), then the file extension if there is no content type (or it's
+`text/plain`), which is assumed to be type returned for an unconfigured
+http server. The application can also pass in a declared language hint.
+
+The following is a suggested Apache httpd .htaccess file:
+
+ AddType text/turtle .ttl
+ AddType application/rdf+xml .rdf
+ AddType application/n-triples .nt
+
+ AddType application/ld+json .jsonld
+ AddType application/owl+xml .owl
+
+ AddType text/trig .trig
+ AddType application/n-quads .nq
+
+## Example 1 : Common usage
+
+In this example, a file in the current directory is read as Turtle.
+
+ Model model = ModelFactory.createDefaultModel() ;
+ model.read("data.ttl") ;
+
+If the syntax is not as the file extension, a language can be declared:
+
+ model.read("data.foo", "TURTLE") ;
+
+## Example 2 : Using the RDFDataMgr
+
+In versions of Jena priot to 2.10.0, the `FileManager` provided some of
+this functionality. It was more basic, and not properly web enabled. The
+`RDFDataMgr` superceeds the `FileManager`. "load*" operations create an
+in-memory container (model, or dataset as appropriate); "read" operations
+add data into an existing model or dataset.
+
+ // Create a model and read into it from file
+ // "data.ttl" assumed to be Turtle.
+ Model model = RDFDataMgr.loadModel("data.ttl") ;
+
+ // Create a dataset and read into it from file
+ // "data.trig" assumed to be TriG.
+ Dataset dataset = RDFDataMgr.loadDataset("data.trig") ;
+
+ // Read into an existing Model
+ RDFDataMgr.read(model, "data2.ttl") ;
+
+# Logging
+
+The parsers log to a logger called `org.aapche.jena.riot`. To avoid `WARN`
+messages, set this in log4j.properties to `ERROR`.
+
+# The StreamManager and LocationMapper
+
+By default, the `RDFDataMgr` uses the global `StreamManager` to open typed
+InputStreams. This is available to applications via `RDFDataMgr.open` as well as directly
+using a `StreamManager`.
+
+The `StreamManager` is choosen based on the `Context` object for the
+oepration, but normally this defaults to the global `Context` availbale vai
+`Context.get()`. The constant `RDFDataMgr.streamManagerSymbol`, which is
+`http://jena.apache.org/riot/streamManager` is used.
+
+Specialized StreamManagers can be configured with specific locators for
+data:
+
+- File locator (with own current directory)
+- URL locator
+- Class loader locator
+- Zip file locator
+
+## Configuring the `StreamManager`
+
+The `StreamManager` can be reconfigured with different places to look for
+files. The default configuration used for the global `StreamManager` is
+a file access class, wihere the current directory is that of the java
+process, a URL accessor for reading from the web, and a
+class laoder-based accessor. Different setups can be built and used
+either as the global set up,
+
+There is also a `LocationMapper` for rewiting file names and URLs before
+use to allow placing known names in different places (e.g. having local
+copies of import http resources).
+
+## Configuring a `LocationMapper`
+
+Location mapping files are RDF, usually written in Turtle although
+an RDF syntax can be used.
+
+ @prefix lm: <http://jena.hpl.hp.com/2004/08/location-mapping#>
+
+ [] lm:mapping
+ [ lm:name "file:foo.n3" ; lm:altName "file:etc/foo.n3" ] ,
+ [ lm:prefix "file:etc/" ; lm:altPrefix "file:ETC/" ] ,
+ [ lm:name "file:etc/foo.n3" ; lm:altName "file:DIR/foo.n3" ]
+ .
+
+There are two types of location mapping: exact match renaming and
+prefix renaming. When trying to find an alternative location, a
+`LocationMapper` first tries for an exact match; if none is found,
+the LocationMapper will search for the longest matching prefix. If
+two are the same length, there is no guarantee on order tried;
+there is no implied order in a location mapper configuration file
+(it sets up two hash tables).
+
+In the example above, `file:etc/foo.n3` becomes `file:DIR/foo.n3`
+because that is an exact match. The prefix match of file:/etc/ is
+ignored.
+
+All string tests are done case sensitively because the primary use
+is for URLs.
+
+Notes:
+
+- Property values are not URIs, but strings. This is a system
+ feature, not an RDF feature. Prefix mapping is name rewriting;
+ alternate names are not treated as equivalent resources in the rest
+ of Jena. While application writers are encouraged to use URIs to
+ identify files, this is not always possible.
+- There is no check to see if the alternative system resource is
+ equivalent to the original.
+
+A LocationMapper finds its configuration file by looking for the
+following files, in order:
+
+- `file:location-mapping.rdf`
+- `file:location-mapping.ttl`
+- `file:etc/location-mapping.rdf`
+- `file:etc/location-mapping.ttl`
+
+This is a specified as a path - note the path separator is always
+the character ';' regardless of operating system because URLs
+contain ':'.
+
+Applications can also set mappings programmatically. No
+configuration file is necessary.
+
+The base URI for reading models will be the original URI, not the alternative location.
+
+### Debugging
+
+Using log4j, set the logging level of the classes:
+
+* org.apache.jena.riot.stream.StreamManager
+* org.apache.jena.riot.stream.LocationMapper
+
+# Advanced examples
+
+## Filter the output of parsing.
+
+When working with very large files, it can be useful to process the stream of triples or quads produced
+by the parser so as to work in a streaming fashion.
+
+See [RIOT example 4](https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_4.java)
+
+## Add a new language
+
+The set of languages is fixed - a new languages can be added to RIOT as shown in
+[RIOT example 5](https://svn.apache.org/repos/asf/jena/trunk/jena-arq/src-examples/arq/examples/riot/ExRIOT_5.java)
+
-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](riot.html)
-
-- [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)
-- [RDF I/O with RIOT](riot.html)
Added: jena/site/trunk/content/documentation/io/rdf-json.html
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/rdf-json.html?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/rdf-json.html (added)
+++ jena/site/trunk/content/documentation/io/rdf-json.html Tue Jan 1 15:27:39 2013
@@ -0,0 +1,258 @@
+<html>
+<head>
+ <link href="http://jena.apache.org/css/jena.css" rel="stylesheet" type="text/css"/>
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+ <title>RDF JSON - docs.api</title>
+</head>
+<body>
+
+<div id="content" style="margin-left: 20px">
+
+<p>
+<small>This page is taken from <a href="http://docs.api.talis.com/platform-api/output-types/rdf-json">The Talis Systems documentation for RDF/JSON</a>.
+© Talis Systems Ltd. 2011. The content is available under
+<a href="http://creativecommons.org/licenses/by-sa/3.0/" target="">Attribution-Share Alike 3.0</a>
+</small> license.
+</p>
+
+ <h1>RDF JSON</h1>
+
+ <p><a href="http://json.org/">JSON</a> (the serialisation of data
+ in javascript object notation) is an increasingly popular data format,
+ largely because it is easy to parse (or, in the case of javascript, simply
+ evaluate) into a data structure of the consumer's programming language of
+ choice.</p>
+
+ <p>This is a specification for a resource-centric serialisation of RDF in
+ JSON. It aims to serialise RDF in a structure that is easy for developers
+ to work with.</p>
+
+ <h2>SyntaxSpecification</h2>
+
+ <p>RDF/JSON represents a set of RDF triples as a series of nested data structures.
+ Each unique subject in the set of triples is represented as a key in
+ JSON object (also known as associative array, dictionary or hash table).
+ The value of each key is a object whose keys are the URIs of the
+ properties associated with each subject. The value of each property key
+ is an array of objects representing the value of each property.</p>
+
+ <p>Blank node subjects are named using a string conforming to the <a href="http://www.dajobe.org/2004/01/turtle/#nodeID">nodeID production in Turtle</a>. For example:
+_:A1</p>
+
+ <p>In general, a triple (subject <b>S</b>, predicate <b>P</b>, object <b>O</b>) is encoded in the following
+structure:</p>
+
+<pre>{ "S" : { "P" : [ O ] } }</pre>
+
+<p>The object of the triple <b>O</b> is represented as a further JSON object with the following
+keys:</p>
+
+<dl>
+ <dt>type</dt>
+ <dd>one of 'uri', 'literal' or 'bnode' (<b>required</b>
+ and must be lowercase)</dd>
+
+ <dt>value</dt>
+ <dd>the lexical value of the
+ object (<b>required</b>, full URIs should be used, not
+ qnames)</dd>
+ <dt>lang</dt>
+ <dd>the language of a literal value
+ (<b>optional</b> but if supplied it must not be
+ empty)</dd>
+ <dt>datatype</dt>
+ <dd>the datatype URI of the literal value (<b>optional</b>)</dd>
+</dl>
+
+ <p>The 'lang' and 'datatype' keys should only be used if the value of the 'type' key is "literal".</p>
+
+ <p>For example, the following triple:</p>
+ <pre><http://example.org/about> <http://purl.org/dc/elements/1.1/title> "Anna's Homepage" .</pre>
+
+ <p>can be encoded in RDF/JSON as:</p>
+
+ <pre>{
+ "http://example.org/about" :
+ {
+ "http://purl.org/dc/elements/1.1/title": [ { "type" : "literal" , "value" : "Anna's Homepage" } ]
+ }
+}</pre>
+
+ <p>Here is an example of the RDF JSON specification in the format of
+ a <a href="http://json-schema.org/">JSON Schema</a>. The latest version can
+ also be found in the <a href="http://soapjr.org/schemas/RDF_JSON">schema
+ section</a> of the <a href="http://soapjr.org/">SOAPjr.org site</a>.</p>
+
+ <pre>{
+ "version":"0.3.0",
+ "id":"RDF-JSON",
+ "description":"RDF JSON definition",
+ "type":"object",
+ "properties":{
+ },
+ "additionalProperties":{
+ "type":"object",
+ "description":"subject (root object)",
+ "optional":"true",
+ "properties":{
+ },
+ "additionalProperties":{
+ "type":"array",
+ "description":"predicate (subject object)",
+ "optional":"true",
+ "items":{
+ "type":"object",
+ "description":"object (value array)",
+ "properties":{
+ "description":"content (value object)",
+ "type":{
+ "type":"string",
+ "enum":["uri","bnode","literal"]
+ },
+ "value":{
+ "type":"string"
+ },
+ "lang":{
+ "optional":true,
+ "description":"See ftp://ftp.isi.edu/in-notes/bcp/bcp47.txt",
+ "type":"string"
+ },
+ "datatype":{
+ "optional":true,
+ "format":"uri",
+ "type":"string"
+ }
+ }
+ }
+ }
+ }
+}
+</pre>
+
+ <h2>Examples</h2>
+
+ <p>The following RDF/XML:</p>
+ <pre><rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:foaf="http://xmlns.com/foaf/0.1/"
+ xmlns:dc="http://purl.org/dc/elements/1.1/">
+ <rdf:Description rdf:about="http://example.org/about">
+ <dc:creator>Anna Wilder</dc:creator>
+ <dc:title xml:lang="en">Anna's Homepage</dc:title>
+ <foaf:maker rdf:nodeID="person" />
+ </rdf:Description>
+ <rdf:Description rdf:nodeID="person">
+ <foaf:homepage rdf:resource="http://example.org/about" />
+ <foaf:made rdf:resource="http://example.org/about" />
+ <foaf:name>Anna Wilder</foaf:name>
+ <foaf:firstName>Anna</foaf:firstName>
+ <foaf:surname>Wilder</foaf:surname>
+ <foaf:depiction rdf:resource="http://example.org/pic.jpg" />
+ <foaf:nick>wildling</foaf:nick>
+ <foaf:nick>wilda</foaf:nick>
+ <foaf:mbox_sha1sum>69e31bbcf58d432950127593e292a55975bc66fd</foaf:mbox_sha1sum>
+ </rdf:Description>
+</rdf:RDF></pre>
+ <p>Can be represented as the following RDF/JSON structure:</p><pre>{
+ "http://example.org/about" : {
+ "http://purl.org/dc/elements/1.1/creator" : [ { "value" : "Anna Wilder", "type" : "literal" } ],
+ "http://purl.org/dc/elements/1.1/title" : [ { "value" : "Anna's Homepage", "type" : "literal", "lang" : "en" } ] ,
+ "http://xmlns.com/foaf/0.1/maker" : [ { "value" : "_:person", "type" : "bnode" } ]
+ } ,
+
+ "_:person" : {
+ "http://xmlns.com/foaf/0.1/homepage" : [ { "value" : "http://example.org/about", "type" : "uri" } ] ,
+ "http://xmlns.com/foaf/0.1/made" : [ { "value" : "http://example.org/about", "type" : "uri" } ] ,
+ "http://xmlns.com/foaf/0.1/name" : [ { "value" : "Anna Wilder", "type" : "literal" } ] ,
+ "http://xmlns.com/foaf/0.1/firstName" : [ { "value" : "Anna", "type" : "literal" } ] ,
+ "http://xmlns.com/foaf/0.1/surname" : [ { "value" : "Wilder", "type" : "literal" } ] ,
+ "http://xmlns.com/foaf/0.1/depiction" : [ { "value" : "http://example.org/pic.jpg", "type" : "uri" } ] ,
+ "http://xmlns.com/foaf/0.1/nick" : [
+ { "type" : "literal", "value" : "wildling"} ,
+ { "type" : "literal", "value" : "wilda" }
+ ] ,
+ "http://xmlns.com/foaf/0.1/mbox_sha1sum" : [ { "value" : "69e31bbcf58d432950127593e292a55975bc66fd", "type" : "literal" } ]
+ }
+}</pre>
+
+ <h2>Serialisation Algorithm</h2>
+
+ <p>Refer to <a href="http://json.org/">http://json.org/</a> for definitions of
+ terminology</p>
+
+ <ol>
+ <li>Start a JSON object (called the root object)</li>
+ <li>Group all the triples by subject</li>
+ <li>For each subject:
+ <ol>
+ <li>Create a JSON object for the subject (called the subject
+ object)</li>
+ <li>Group all triples having the current subject by predicate</li>
+ <li>For each predicate:<ol>
+ <li>Create a JSON array (called the value array)</li>
+ <li>Select all triples having the current subject and current
+ predicate</li>
+ <li>For each value:
+ <ol>
+ <li>Create a JSON object (called the value object)</li>
+
+ <li>Add a key/value pair to the value object with the key
+ being the string "value" and the value being the lexical
+ value of the triple value</li>
+
+ <li>Add a key/value pair to
+ the value object with the key being the string "type" and
+ the value being one of "literal", "uri" or "bnode"
+ depending on the type of the triple's value</li>
+ #content
+ <li>If the triple's value is a plain literal and has a
+ language then add a key/value pair to the value object with the key being
+ the string "lang" and the value being the language token</li>
+
+ <li>If the triple's value is a typed literal then add a
+ key/value pair to the value object with the key being the string
+ "datatype" and value being the URI of the datatype</li>
+
+ <li>Push the value object onto the end of the value array</li>
+ </ol>
+ </li>
+ <li>Add a key/value pair to the subject object with the key being the predicate URI and the value being the value
+ array</li>
+ </ol>
+ </li>
+ <li>Add a key/value pair to the root object with the key being the
+ URI or blank node identifier of the subject and the value being the
+ subject object created in the previous step</li>
+ </ol>
+ </li>
+ </ol>
+
+<!--
+ <h3>Further Examples</h3>
+
+ <p>RDF/XML can be converted into the specified RDF/JSON format by using
+ the <a href="http://convert.test.talis.com/">http://convert.test.talis.com</a>
+ web service.</p>
+-->
+ <h2>Publishing RDF/JSON on the web</h2>
+
+ <p>If doing content-negotiation, respond to, and send the content-type
+ as <code>application/json</code>. An empty graph (ie: no triples) should
+ be served as an empty object: <code>{}</code>.</p>
+
+ <h2>References</h2>
+
+ <ol>
+ <li><a href="http://www.ietf.org/rfc/rfc3066.txt">Tags
+ for the Identification of
+ Languages</a></li>
+ <li><a href="http://docs.api.talis.com/system/errors/NodeNotFound?suri=wuid:gx:785d2e15fb97c7a4">RDF JSON
+ Brainstorming</a></li>
+ <li><a href="http://json.org/">http://json.org/</a></li>
+ <li><a href="http://www.ietf.org/rfc/rfc3986.txt">Uniform
+ Resource Identifier (URI): Generic
+ Syntax</a>
+ </li>
+ </ol>
+ </div>
+</body>
+</html>
Added: jena/site/trunk/content/documentation/io/rdf-output.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/io/rdf-output.mdtext?rev=1427439&view=auto
==============================================================================
--- jena/site/trunk/content/documentation/io/rdf-output.mdtext (added)
+++ jena/site/trunk/content/documentation/io/rdf-output.mdtext Tue Jan 1 15:27:39 2013
@@ -0,0 +1,33 @@
+Title: RDF Output
+
+See the [Jena RDF/XML How-To](arp_howto.html) for details of RDF/XML and
+RDF/XML-ABBREV configuration.
+
+## Advanced Turtle Output
+
+The Turtle pretty printer (which is used by default)Â and the Turtle plain
+writer provide a number of properties to control their output. The
+properties all start: `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 Turtle 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 Turtle pretty printer print object lists as comma-separated lists.
+
Modified: jena/site/trunk/content/documentation/notes/model-factory.mdtext
URL: http://svn.apache.org/viewvc/jena/site/trunk/content/documentation/notes/model-factory.mdtext?rev=1427439&r1=1427438&r2=1427439&view=diff
==============================================================================
--- jena/site/trunk/content/documentation/notes/model-factory.mdtext (original)
+++ jena/site/trunk/content/documentation/notes/model-factory.mdtext Tue Jan 1 15:27:39 2013
@@ -7,13 +7,6 @@ different kinds of `Model` and ways of c
describes the Jena `ModelFactory`, a one-stop shop for
creating Jena models. `ModelFactory` lives in Java package
`com.hp.hpl.jena.rdf.model`.
-Most of `ModelFactory` methods have been around for a while now,
-but Jena 2.5's ModelFactory contains methods that use the
-`Assembler` API which appeared in Jena.4, which allows models to
-be created according to RDF descriptions that can be
-programmatically constructed or read in from external resources
-such as configuration files. (This API replaces the old `ModelSpec`
-API, which had proved unsatisfactory.)
This note is an introduction, not an exhaustive description. As
usual consult the Javadoc for details of the methods and classes to
@@ -26,82 +19,6 @@ The simplest way to create a model (if n
plain RDF model, stored in-memory, that does no inference and has
no special ontology interface.
-## ModelMakers
-
-Plain models can be given names which allows them to be "saved" and
-looked up by name later. This is handled by implementations of the
-interface `ModelMaker`; each `ModelMaker` produces Models of the
-same kind. The simplest kind of `ModelMaker` is a memory model
-maker, which you get by calling
-`ModelFactory.createMemModelMaker()`. The methods you'd want to use
-to start with on a ModelMaker are:
-
-- `createModel(String)`: create a model with the given name in the
-ModelMaker. If a model with that name already exists, then that
-model is used instead.
-
-- `openModel(String)`: open an existing model with the given name. If
-no such model exists, create a new empty one and give it that name.
-[createModel(String) and openModel(String) behave in the same way,
-but each has a two-argument form for which the behaviour is
-different. Use whichever one best fits your intention.]
-
-- `createModel()`: create a fresh anonymous model.
-
-- `getModel()`: each `ModelMaker` has a *default model*; this method
-returns that model.
-
-There are other methods, for removing models, additional control
-over create *vs* open, closing the maker, and looking names up; for
-those consult the
-[ModelMaker JavaDoc](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/ModelMaker.html).
-
-### File-based models
-
-The method `ModelFactory.createFileModelMaker(String)` returns a
-`ModelMaker` which attaches models to filing-system files. The
-`String` argument is the *fileBase*. When a file-ModelMaker opens a
-file, it reads it from a file in the directory named by the
-fileBase; when the model is closed (and *only* then, in the current
-implementation), the contents of the model are written back to the
-file.
-
-Because the names of models in a modelMaker can be arbitrary
-character strings, in particular URIs, they are translated slightly
-to avoid confusion with significant characters of common filing
-systems. In the current implementation,
-
-- colon : is converted to \\_C
-- slash \/ is converted to \\_S
-- underbar \_ is converted to \\_U
-
-## Reification styles
-
-Jena models have different *reification styles*, which are
-described in more detail in the
-[reification howto](reification.html). `ModelFactory` provides
-constants for those styles:
-
-- `ModelFactory.Standard`
-- `ModelFactory.Convenient`
-- `ModelFactory.Minimal`
-
-And methods corresponding to those already discussed:
-
-- `ModelFactory.createDefaultModel(style)` creates a default model
-with the specified reification style.
-
-- `ModelFactory.createMemModelMaker(style)` creates a ModelMaker that
-creates memory models with the specified reification style.
-
-- `ModelFactory.createFileModelMaker(root,style)`
-creates a ModelMaker that creates file-associated models with the
-specified reification style.
-
-Reification styles also appear in other Modelfactory methods,
-although they are not required. We shall not discuss them further
-in this document; consult the Javadoc for appropriate details.
-
## Database model creation
_Note:_ this section previously referred to creating database models
@@ -191,9 +108,10 @@ the full OWL Lite inference
## Creating models from Assembler descriptions
-A new feature of Jena since Jena 2.4 is the use of
-*assembler descriptions*, documented in the
-[assembler howto](../assembler/assembler-howto.html). Access to the
+A model can be built from a description of the required model.
+This is documented in the
+[assembler howto](../assembler/assembler-howto.html).
+Access to the
assembler system for model creation is provided by three
ModelFactory methods:
@@ -213,22 +131,64 @@ according to the description hanging fro
Assemblers can construct other things as well as models, and the
Assembler system is user-extensible: see the howto for details.
+### File-based models
+
+The method `ModelFactory.createFileModelMaker(String)` returns a
+`ModelMaker` which attaches models to filing-system files. The
+`String` argument is the *fileBase*. When a file-ModelMaker opens a
+file, it reads it from a file in the directory named by the
+fileBase; when the model is closed (and *only* then, in the current
+implementation), the contents of the model are written back to the
+file.
+
+Because the names of models in a modelMaker can be arbitrary
+character strings, in particular URIs, they are translated slightly
+to avoid confusion with significant characters of common filing
+systems. In the current implementation,
+
+- colon : is converted to \\_C
+- slash \/ is converted to \\_S
+- underbar \_ is converted to \\_U
+
+## ModelMakers
+
+Plain models can be given names which allows them to be "saved" and
+looked up by name later. This is handled by implementations of the
+interface `ModelMaker`; each `ModelMaker` produces Models of the
+same kind. The simplest kind of `ModelMaker` is a memory model
+maker, which you get by calling
+`ModelFactory.createMemModelMaker()`. The methods you'd want to use
+to start with on a ModelMaker are:
+
+- `createModel(String)`: create a model with the given name in the
+ModelMaker. If a model with that name already exists, then that
+model is used instead.
+
+- `openModel(String)`: open an existing model with the given name. If
+no such model exists, create a new empty one and give it that name.
+[createModel(String) and openModel(String) behave in the same way,
+but each has a two-argument form for which the behaviour is
+different. Use whichever one best fits your intention.]
+
+- `createModel()`: create a fresh anonymous model.
+
+- `getModel()`: each `ModelMaker` has a *default model*; this method
+returns that model.
+
+There are other methods, for removing models, additional control
+over create *vs* open, closing the maker, and looking names up; for
+those consult the
+[ModelMaker JavaDoc](/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/ModelMaker.html).
+
## Miscellany
Finally, `ModelFactory` contains a collection of methods for some
special cases not conveniently dealt with elsewhere.
-- `createModelForGraph(Graph g)` is used when an advanced user with
+`createModelForGraph(Graph g)` is used when an advanced user with
access to the Jena SPI has constructed or obtained a `Graph` and
wishes to present it as a model. This method wraps the graph up as
a plain model. Alterations to the graph are visible in the model,
and *vice versa*.
-- `withHiddenStatements(Model)` returns a new Model in which any
-reification quadlets (see the reification howto) that may be hidden
-in the base model are exposed in the result. It may return the base
-model, if it does not hide quadlets. This is useful if you want to
-see all the statements of the model as they will appear in a
-serialisation.
-