You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jena.apache.org by bu...@apache.org on 2012/01/24 12:41:24 UTC
svn commit: r803175 -
/websites/staging/jena/trunk/content/jena/documentation/notes/typed-literals.html
Author: buildbot
Date: Tue Jan 24 11:41:24 2012
New Revision: 803175
Log:
Staging update by buildbot for jena
Modified:
websites/staging/jena/trunk/content/jena/documentation/notes/typed-literals.html
Modified: websites/staging/jena/trunk/content/jena/documentation/notes/typed-literals.html
==============================================================================
--- websites/staging/jena/trunk/content/jena/documentation/notes/typed-literals.html (original)
+++ websites/staging/jena/trunk/content/jena/documentation/notes/typed-literals.html Tue Jan 24 11:41:24 2012
@@ -160,18 +160,11 @@
values defined - plain literals (which are basically strings with
an optional language tag) and XML literals (which are more or less
plain literals plus a "well-formed-xml" flag).</p>
-<p>Part of the remit for the current
+<p>Part of the remit for the 2001
<a href="http://www.w3.org/2001/sw/RDFCore/">RDF Core</a> working group was to
-add to RDF support for typed values, i.e. things like numbers. At
-the time of writing the core specification for these has been
-published in the last call documents though some modifications to
-the way xml:Lang tags are treated have been proposed in response to
-last call comments.</p>
-<p>These notes describe the support for typed literals built into
-Jena2 at present. Some of the details have been changed recently in
-response to the recent working group decisions. We will now attempt
-to keep the API as stable as we can, unless some major shifting in
-the specifications occurs.</p>
+add to RDF support for typed values, i.e. things like numbers.
+These notes describe the support for typed literals in
+Jena2.</p>
<p>Before going into the Jena details here are some informal reminders
of how typed literals work in RDF. We refer readers to the RDF core
<a href="http://www.w3.org/TR/rdf-mt/">semantics</a>,
@@ -183,8 +176,8 @@ the literal) and a datatype (identified
supposed to denote a mapping from lexical forms to some space of
values. The pair comprising the literal then denotes an element of
the value space of the datatype. For example, a typed literal
-comprising ("true", xsd:boolean) would denote the abstract true
-value T.</p>
+comprising <code>("true", xsd:boolean)</code> would denote the abstract true
+value <code>T</code>.</p>
<p>In the RDF/XML syntax typed literals are notated with syntax such
as:</p>
<div class="codehilite"><pre><span class="nt"><age</span> <span class="na">rdf:datatype=</span><span class="s">"http://www.w3.org/2001/XMLSchema#int"</span><span class="nt">></span>13<span class="nt"></age></span>
@@ -196,7 +189,12 @@ as:</p>
</pre></div>
-<p>and this <code>^^</code> notation will appear in literals printed by Jena.</p>
+<p>In Turtle, it can be abbreviated:</p>
+<div class="codehilite"><pre><span class="s">"13"</span><span class="o">^^</span><span class="n">xsd:int</span>
+</pre></div>
+
+
+<p>This <code>^^</code> notation will appear in literals printed by Jena.</p>
<p>Note that a literal is either typed or plain (an old style literal)
and which it is can be determined statically. There is no way to
define a literal as having a lexical value of, say "13" but leave
@@ -204,37 +202,46 @@ its datatype open and then infer the dat
ontology definition.</p>
<p>In the new scheme of things well-formed XML literals are treated as
typed literals whose datatype is the special type
-"rdf:XMLLiteral".</p>
+<code>rdf:XMLLiteral</code>.</p>
<h2 id="basic_api_operations">Basic API operations</h2>
-<p>Jena2 will correctly parse typed literals within RDF/XML, NTriple
-and N3 source files. The same Java object,
-<code><a href="../javadoc/com/hp/hpl/jena/rdf/model/Literal.html">Literal</a></code>,
+<p>Jena will correctly parse typed literals within RDF/XML, NTriple
+and Turtle source files. The same Java object,
+<a href="/jena/documentation/javadoc/jena/com/hp/hpl/jena/rdf/model/Literal.html"><code>Literal</code></a>
will represent "plain" and "typed" literals. Literal now supports
some new methods:</p>
+<ul>
+<li>
<p><code>getDatatype()</code>
Returns null for a plain literal or a Java object which represents
-the datatype of a typed Literal.
-<code>getDatatypeURI()</code>
+the datatype of a typed Literal.</p>
+</li>
+<li>
+<p><code>getDatatypeURI()</code>
Returns null for a plain literal or the URI of the datatype of a
-typed Literal.
-<code>getValue()</code>
+typed Literal.</p>
+</li>
+<li>
+<p><code>getValue()</code>
Returns a Java object representing the value of the literal, for
example for an xsd:int this will be a java.lang.Integer, for plain
literals it will be a String.
The converse operation of creating a Java object to represent a
typed literal in a model can be achieved using:</p>
-<blockquote>
-<p><code>model.createTypedLiteral</code>(value, datatype)</p>
-</blockquote>
-<p>This allows the <code>value</code> to be specified by a lexical form (i.e. a
+</li>
+<li>
+<p><code>model.createTypedLiteral(value, datatype)</code>
+This allows the <code>value</code> to be specified by a lexical form (i.e. a
String) or by a Java object representing the typed value; the
<code>datatype</code> can be specified by a URI string or a Java object
representing the datatype.</p>
+</li>
+</ul>
<p>In addition there is a built in mapping from standard Java wrapper
objects to XSD datatypes (see later) so that the simpler call:</p>
-<blockquote>
-<p><code>model.createTypedLiteral(Object)</code></p>
-</blockquote>
+<div class="codehilite"><pre><span class="n">model</span><span class="o">.</span><span class="n">createTypedLiteral</span><span class="p">(</span><span class="n">Object</span><span class="p">)</span>
+</pre></div>
+
+
<p>will create a typed literal with the datatype appropriate for
representing that java object. For example,</p>
<div class="codehilite"><pre><span class="n">Literal</span> <span class="n">l</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">createTypedLiteral</span><span class="p">(</span><span class="k">new</span> <span class="n">Integer</span><span class="p">(</span><span class="mi">25</span><span class="p">));</span>
@@ -242,7 +249,7 @@ representing that java object. For examp
<p>will create a typed literal with the lexical value "25", of type
-xsd:int.</p>
+<code>xsd:int</code>.</p>
<p>Note that there are also functions which look similar but do not
use typed literals. For example::</p>
<div class="codehilite"><pre><span class="n">Literal</span> <span class="n">l</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">createLiteral</span><span class="p">(</span><span class="mi">25</span><span class="p">);</span>
@@ -253,7 +260,7 @@ use typed literals. For example::</p>
<p>These worked by converting the primitive to a string and storing
the resulting string as a plain literal. The inverse operation then
attempts to parse the string of the plain literal (as an int in
-this example). These are for backward compability with earlier
+this example). These are for backward compatibility with earlier
versions of Jena and older datasets. In normal circumstances
<code>createTypedLiteral</code> is preferable.</p>
<h3 id="equality_issues">Equality issues</h3>
@@ -272,7 +279,7 @@ made it impossible to cache literals in
<h2 id="how_datatypes_are_represented">How datatypes are represented</h2>
<p>Datatypes for typed literals are represented by instances of the
interface
-<a href="../javadoc/com/hp/hpl/jena/datatypes/RDFDatatype.html"><code>com.hp.hpl.jena.datatypes.RDFDatatype</code></a>.
+<a href="/jena/documentation/javadoc/com/hp/hpl/jena/datatypes/RDFDatatype.html"><code>com.hp.hpl.jena.datatypes.RDFDatatype</code></a>.
Instances of this interface can be used to parse and serialized
typed data, test for equality and test if a typed or lexical value
is a legal value for this datatype.</p>
@@ -324,32 +331,60 @@ base64Binary date time dateTime duration
gYearMonth gMonthDay</p>
</blockquote>
<p>These are all available as static member variables from
-<a href="../javadoc/com/hp/hpl/jena/datatypes/xsd/XSDDatatype.html"><code>com.hp.hpl.jena.datatypes.xsd.XSDDatatype</code></a>.</p>
+<a href="/jena/documentation/javadoc/com/hp/hpl/jena/datatypes/xsd/XSDDatatype.html"><code>com.hp.hpl.jena.datatypes.xsd.XSDDatatype</code></a>.</p>
<p>Of these types, the following are registered as the default type to
use to represent certain Java classes:</p>
-<p>Java class
-xsd type
-Float
-float
-Double
-double
-Integer
-int
-Long
-long
-Short
-short
-Byte
-byte
-BigInteger
-integer
-BigDecimal
-decimal
-Boolean
-Boolean
-String
-string
-Thus when creating a typed literal from a Java <code>BigInteger</code> then
+<table>
+<thead>
+<tr>
+<th>Java class</th>
+<th>xsd type</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Float</td>
+<td>float</td>
+</tr>
+<tr>
+<td>Double</td>
+<td>double</td>
+</tr>
+<tr>
+<td>Integer</td>
+<td>int</td>
+</tr>
+<tr>
+<td>Long</td>
+<td>long</td>
+</tr>
+<tr>
+<td>Short</td>
+<td>short</td>
+</tr>
+<tr>
+<td>Byte</td>
+<td>byte</td>
+</tr>
+<tr>
+<td>BigInteger</td>
+<td>integer</td>
+</tr>
+<tr>
+<td>BigDecimal</td>
+<td>decimal</td>
+</tr>
+<tr>
+<td>Boolean</td>
+<td>Boolean</td>
+</tr>
+<tr>
+<td>String</td>
+<td>string</td>
+</tr>
+</tbody>
+</table>
+<p>Thus when creating a typed literal from a Java <code>BigInteger</code> then
<code>xsd:integer</code> will be used. The converse mapping is more adaptive.
When parsing an xsd:integer the Java value object used will be an
Integer, Long or BigInteger depending on the size of the specific
@@ -427,7 +462,7 @@ then tries to create and use two instanc
standard for how to map the datatype URI to a datatype definition.</p>
<p>Within Jena2 we allow new datatypes to be created and registered by
using the
-<a href="../javadoc/com/hp/hpl/jena/datatypes/TypeMapper.html"><code>TypeMapper</code></a>
+<a href="/jena/documentation/javadoc/com/hp/hpl/jena/datatypes/TypeMapper.html"><code>TypeMapper</code></a>
class.</p>
<p>The easiest way to define a new RDFDatatype is to subclass
BaseDatatype and define implementations for parse, unparse and