http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/RdfSchema.java ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/RdfSchema.java b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/RdfSchema.java new file mode 100644 index 0000000..1347939 --- /dev/null +++ b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/RdfSchema.java @@ -0,0 +1,92 @@ +// *************************************************************************************************************************** +// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * +// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * +// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * +// * with the License. You may obtain a copy of the License at * +// * * +// * http://www.apache.org/licenses/LICENSE-2.0 * +// * * +// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * +// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * +// * specific language governing permissions and limitations under the License. * +// *************************************************************************************************************************** +package org.apache.juneau.jena.annotation; + +import static java.lang.annotation.ElementType.*; +import static java.lang.annotation.RetentionPolicy.*; + +import java.lang.annotation.*; + +/** + * Identifies the default RDF namespaces at the package level. + */ +@Documented +@Target(PACKAGE) +@Retention(RUNTIME) +@Inherited +public @interface RdfSchema { + + /** + * Sets the default RDF prefix for all classes in this and child packages. + * <p> + * Must either be matched with a {@link #namespace()} annotation, or an {@link #rdfNs()} mapping with the + * same {@link RdfNs#prefix} value. + * </p> + */ + public String prefix() default ""; + + /** + * Sets the default RDF namespace URL for all classes in this and child packages. + * <p> + * Must either be matched with a {@link #prefix()} annotation, or an {@link #rdfNs()} mapping with the + * same {@link RdfNs#namespaceURI} value. + * </p> + */ + public String namespace() default ""; + + /** + * Lists all namespace mappings to be used on all classes within this package. + * <p> + * The purpose of this annotation is to allow namespace mappings to be defined in a single location + * and referred to by name through just the {@link Rdf#prefix()} annotation. + * <p> + * Inherited by child packages. + * + * <h6 class='topic'>Example:</h6> + * <p> + * Contents of <code>package-info.java</code>... + * </p> + * <p class='bcode'> + * <jc>// XML namespaces used within this package.</jc> + * <ja>@RdfSchema</ja>(prefix=<js>"ab"</js>, + * namespaces={ + * <ja>@RdfNs</ja>(prefix=<js>"ab"</js>, namespaceURI=<js>"http://www.apache.org/addressBook/";</js>), + * <ja>@RdfNs</ja>(prefix=<js>"per"</js>, namespaceURI=<js>"http://www.apache.org/person/";</js>), + * <ja>@RdfNs</ja>(prefix=<js>"addr"</js>, namespaceURI=<js>"http://www.apache.org/address/";</js>), + * <ja>@RdfNs</ja>(prefix=<js>"mail"</js>, namespaceURI="<js>http://www.apache.org/mail/";</js>) + * } + * ) + * <jk>package</jk> org.apache.juneau.samples.addressbook; + * <jk>import</jk> org.apache.juneau.rdf.annotation.*; + * </p> + * <p> + * Class in package using defined namespaces... + * </p> + * <p class='bcode'> + * <jk>package</jk> org.apache.juneau.samples.addressbook; + * + * <jc>// Bean class, override "ab" namespace on package.</jc> + * <ja>@Rdf</ja>(prefix=<js>"addr"</js>) + * <jk>public class</jk> Address { + * + * <jc>// Bean property, use "addr" namespace on class.</jc> + * <jk>public int</jk> <jf>id</jf>; + * + * <jc>// Bean property, override with "mail" namespace.</jc> + * <ja>@Rdf</ja>(prefix=<js>"mail"</js>) + * <jk>public</jk> String <jf>street</jf>, <jf>city</jf>, <jf>state</jf>; + * } + * </p> + */ + public RdfNs[] rdfNs() default {}; +}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/package.html ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/package.html b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/package.html new file mode 100644 index 0000000..c72c12e --- /dev/null +++ b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/annotation/package.html @@ -0,0 +1,41 @@ +<!DOCTYPE HTML> +<!-- +/*************************************************************************************************************************** + * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the + * specific language governing permissions and limitations under the License. + * + ***************************************************************************************************************************/ + --> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <style type="text/css"> + /* For viewing in Page Designer */ + @IMPORT url("../../../../../../../javadoc.css"); + + /* For viewing in REST interface */ + @IMPORT url("../htdocs/javadoc.css"); + body { + margin: 20px; + } + </style> + <script> + /* Replace all @code and @link tags. */ + window.onload = function() { + document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>'); + document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>'); + } + </script> +</head> +<body> +<p>RDF annotations</p> +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_HTML.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_HTML.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_HTML.png new file mode 100644 index 0000000..b4a3576 Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_HTML.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_N3.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_N3.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_N3.png new file mode 100644 index 0000000..16613a4 Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_N3.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_NTriple.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_NTriple.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_NTriple.png new file mode 100644 index 0000000..9da3ffa Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_NTriple.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXML.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXML.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXML.png new file mode 100644 index 0000000..13f2b43 Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXML.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXMLABBREV.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXMLABBREV.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXMLABBREV.png new file mode 100644 index 0000000..e1ffa09 Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_RDFXMLABBREV.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_Turtle.png ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_Turtle.png b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_Turtle.png new file mode 100644 index 0000000..0fd2b36 Binary files /dev/null and b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/doc-files/Example_Turtle.png differ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/java/org/apache/juneau/jena/package.html ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/java/org/apache/juneau/jena/package.html b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/package.html new file mode 100644 index 0000000..6036583 --- /dev/null +++ b/juneau-core-rdf/src/main/java/org/apache/juneau/jena/package.html @@ -0,0 +1,1445 @@ +<!DOCTYPE HTML> +<!-- +/*************************************************************************************************************************** + * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the + * specific language governing permissions and limitations under the License. + * + ***************************************************************************************************************************/ + --> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <style type="text/css"> + /* For viewing in Page Designer */ + @IMPORT url("../../../../../../javadoc.css"); + + /* For viewing in REST interface */ + @IMPORT url("../htdocs/javadoc.css"); + body { + margin: 20px; + } + </style> + <script> + /* Replace all @code and @link tags. */ + window.onload = function() { + document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>'); + document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>'); + } + </script> +</head> +<body> +<p>Jena-based RDF serialization and parsing support</p> +<script> + function toggle(x) { + var div = x.nextSibling; + while (div != null && div.nodeType != 1) + div = div.nextSibling; + if (div != null) { + var d = div.style.display; + if (d == 'block' || d == '') { + div.style.display = 'none'; + x.className += " closed"; + } else { + div.style.display = 'block'; + x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' ); + } + } + } +</script> + +<a id='TOC'></a><h5 class='toc'>Table of Contents</h5> +<ol class='toc'> + <li><p><a class='doclink' href='#RdfOverview'>RDF support overview</a></p> + <ol> + <li><p><a class='doclink' href='#RdfOverviewExample'>Example</a></p> + </ol> + <li><p><a class='doclink' href='#RdfSerializer'>RdfSerializer class</a></p> + <ol> + <li><p><a class='doclink' href='#Namespaces'>Namespaces</a></p> + <li><p><a class='doclink' href='#UriProperties'>URI properties</a></p> + <li><p><a class='doclink' href='#BeanAnnotations'>@Bean and @BeanProperty annotations</a></p> + <li><p><a class='doclink' href='#Collections'>Collections</a></p> + <li><p><a class='doclink' href='#RootProperty'>Root property</a></p> + <li><p><a class='doclink' href='#TypedLiterals'>Typed literals</a></p> + <li><p><a class='doclink' href='#Recursion'>Non-tree models and recursion detection</a></p> + <li><p><a class='doclink' href='#SerializerConfigurableProperties'>Configurable properties</a></p> + <li><p><a class='doclink' href='#SerializerOtherNotes'>Other notes</a></p> + </ol> + <li><p><a class='doclink' href='#RdfParser'>RdfParser class</a></p> + <ol> + <li><p><a class='doclink' href='#GenericParsing'>Parsing into generic POJO models</a></p> + <li><p><a class='doclink' href='#ParserConfigurableProperties'>Configurable properties</a></p> + <li><p><a class='doclink' href='#ParserOtherNotes'>Other notes</a></p> + </ol> + <li><p><a class='doclink' href='#RestApiSupport'>REST API support</a></p> + <ol> + <li><p><a class='doclink' href='#RestServerSupport'>REST server support</a></p> + <ol> + <li><p><a class='doclink' href='#RestServletJenaDefault'>Using RestServletJenaDefault</a></p> + <li><p><a class='doclink' href='#RestServlet'>Using RestServlet with annotations</a></p> + <li><p><a class='doclink' href='#DefaultJenaProvider'>Using JAX-RS DefaultJenaProvider</a></p> + <li><p><a class='doclink' href='#BaseProvider'>Using JAX-RS BaseProvider with annotations</a></p> + </ol> + <li><p><a class='doclink' href='#RestClientSupport'>REST client support</a></p> + </ol> +</ol> + + +<!-- ======================================================================================================== --> +<a id="RdfOverview"></a> +<h2 class='topic' onclick='toggle(this)'>1 - RDF support overview</h2> +<div class='topic'> + <p> + Juneau supports serializing and parsing arbitrary POJOs to and from the following RDF formats: + </p> + <ul> + <li>RDF/XML + <li>Abbreviated RDF/XML + <li>N-Triple + <li>Turtle + <li>N3 + </ul> + <p> + Juneau can serialize and parse instances of any of the following POJO types: + </p> + <ul class='spaced-list'> + <li>Java primitive objects (e.g. <code>String</code>, <code>Integer</code>, <code>Boolean</code>, <code>Float</code>). + <li>Java collections framework objects (e.g. <code>HashSet</code>, <code>TreeMap</code>) containing anything on this list. + <li>Multi-dimensional arrays of any type on this list. + <li>Java Beans with properties of any type on this list. + <li>Classes with standard transformations to and from <code>Strings</code> (e.g. classes containing <code>toString()</code>, + <code>fromString()</code>, <code>valueOf()</code>, <code>constructor(String)</code>). + </ul> + <p> + In addition to the types shown above, Juneau includes the ability to define 'swaps' to transform non-standard object and + property types to serializable forms (e.g. to transform <code>Calendars</code> to and from <code>ISO8601</code> strings, + or <code>byte[]</code> arrays to and from base-64 encoded strings).<br> + These can be associated with serializers/parsers, or can be associated with classes or bean properties through type and method annotations. + </p> + <p> + Refer to <a href='../../../../overview-summary.html#Core.PojoCategories' class='doclink'>POJO Categories</a> for a complete definition of supported POJOs. + </p> + <h6 class='topic'>Prerequisites</h6> + <p> + Juneau uses the Jena library for these formats. <br> + The predefined serializers and parsers convert POJOs to and from RDF models and then uses Jena to convert them to and from the various RDF languages. + </p> + <p> + Jena libraries must be provided on the classpath separately if you plan on making use of the RDF support. + </p> + <p> + The minimum list of required jars are: + </p> + <ul> + <li><code>jena-core-2.7.1.jar</code> + <li><code>jena-iri-0.9.2.jar</code> + <li><code>log4j-1.2.16.jar</code> + <li><code>slf4j-api-1.6.4.jar</code> + <li><code>slf4j-log4j12-1.6.4.jar</code> + </ul> + + <!-- ======================================================================================================== --> + <a id="RdfOverviewExample"></a> + <h3 class='topic' onclick='toggle(this)'>1.1 - RDF support overview - example</h3> + <div class='topic'> + <p> + The example shown here is from the Address Book resource located in the <code>org.apache.juneau.sample.war</code> application. + </p> + <p> + The POJO model consists of a <code>List</code> of <code>Person</code> beans, with each <code>Person</code> containing + zero or more <code>Address</code> beans. + </p> + <p> + When you point a browser at <code>/sample/addressBook</code>, the POJO is rendered as HTML: + </p> + <img class='bordered' src="doc-files/Example_HTML.png"> + <p> + By appending <code>?Accept=<i>mediaType</i>&plainText=true</code> to the URL, you can view the data in the various RDF supported formats. + </p> + + <h6 class='figure'>RDF/XML</h6> + <img class='bordered' src="doc-files/Example_RDFXML.png"> + + <h6 class='figure'>Abbreviated RDF/XML</h6> + <img class='bordered' src="doc-files/Example_RDFXMLABBREV.png"> + + <h6 class='figure'>N-Triple</h6> + <img class='bordered' src="doc-files/Example_NTriple.png"> + + <h6 class='figure'>Turtle</h6> + <img class='bordered' src="doc-files/Example_Turtle.png"> + + <h6 class='figure'>N3</h6> + <img class='bordered' src="doc-files/Example_N3.png"> + </div> +</div> + +<!-- ======================================================================================================== --> +<a id="RdfSerializer"></a> +<h2 class='topic' onclick='toggle(this)'>2 - RdfSerializer class</h2> +<div class='topic'> + <p> + The {@link org.apache.juneau.jena.RdfSerializer} class is the top-level class for all Jena-based serializers.<br> + Language-specific serializers are defined as inner subclasses of the <code>RdfSerializer</code> class: + </p> + <ul> + <li>{@link org.apache.juneau.jena.RdfSerializer.Xml} + <li>{@link org.apache.juneau.jena.RdfSerializer.XmlAbbrev} + <li>{@link org.apache.juneau.jena.RdfSerializer.NTriple} + <li>{@link org.apache.juneau.jena.RdfSerializer.Turtle} + <li>{@link org.apache.juneau.jena.RdfSerializer.N3} + </ul> + <p> + Static reusable instances of serializers are also provided with default settings: + </p> + <ul> + <li>{@link org.apache.juneau.jena.RdfSerializer#DEFAULT_XML} + <li>{@link org.apache.juneau.jena.RdfSerializer#DEFAULT_XMLABBREV} + <li>{@link org.apache.juneau.jena.RdfSerializer#DEFAULT_TURTLE} + <li>{@link org.apache.juneau.jena.RdfSerializer#DEFAULT_NTRIPLE} + <li>{@link org.apache.juneau.jena.RdfSerializer#DEFAULT_N3} + </ul> + <p> + Abbreviated RDF/XML is currently the most widely accepted and readable RDF syntax, so the examples shown here will use that format. + </p> + <p> + For brevity, the examples will use public fields instead of getters/setters to reduce the size of the examples.<br> + In the real world, you'll typically want to use standard bean getters and setters. + </p> + <p> + To start off simple, we'll begin with the following simplified bean and build it up. + </p> + <p class='bcode'> + <jk>public class</jk> Person { + <jc>// Bean properties</jc> + <jk>public int</jk> <jf>id</jf>; + <jk>public</jk> String <jf>name</jf>; + + <jc>// Bean constructor (needed by parser)</jc> + <jk>public</jk> Person() {} + + <jc>// Normal constructor</jc> + <jk>public</jk> Person(<jk>int</jk> id, String name) { + <jk>this</jk>.<jf>id</jf> = id; + <jk>this</jk>.<jf>name</jf> = name; + } + } + </p> + <p> + The following code shows how to convert this to abbreviated RDF/XML: + </p> + <p class='bcode'> + <jc>// Create a new serializer with readable output.</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev().setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3); + + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>); + + <jc>// Serialize the bean to RDF/XML.</jc> + String rdfXml = s.serialize(p); + </p> + <p> + It should be noted that serializers can also be created by cloning existing serializers: + </p> + <p class='bcode'> + <jc>// Create a new serializer with readable output by cloning an existing serializer.</jc> + RdfSerializer s = RdfSerializer.<jsf>DEFAULT_XMLABBREV</jsf>.clone().setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3); + </p> + <p> + This code produces the following output: + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs><xt>></xt> + <xt><rdf:Description></xt> + <xt><jp:id></xt>1<xt></jp:id></xt> + <xt><jp:name></xt>John Smith<xt></jp:name></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + <p> + Notice that we've taken an arbitrary POJO and converted it to RDF.<br> + The Juneau serializers and parsers are designed to work with arbitrary POJOs without requiring + any annotations.<br> + That being said, several annotations are provided to customize how POJOs are handled to produce usable RDF. + </p> + + <!-- ======================================================================================================== --> + <a id="Namespaces"></a> + <h3 class='topic' onclick='toggle(this)'>2.1 - Namespaces</h3> + <div class='topic'> + <p> + You'll notice in the previous example that Juneau namespaces are used to represent bean property names.<br> + These are used by default when namespaces are not explicitly specified. + </p> + <p> + The <code>juneau</code> namespace is used for generic names for objects that don't have namespaces associated with them. + </p> + <p> + The <code>juneaubp</code> namespace is used on bean properties that don't have namespaces associated with them. + </p> + <p> + The easiest way to specify namespaces is through annotations.<br> + In this example, we're going to associate the prefix <code>'per'</code> to our bean class and all + properties of this class.<br> + We do this by adding the following annotation to our class: + </p> + <p class='bcode'> + <ja>@Rdf</ja>(prefix=<js>"per"</js>) + <jk>public class</jk> Person { + </p> + <p> + In general, the best approach is to define the namespace URIs at the package level using a <code>package-info.java</code> + class, like so: + </p> + <p class='bcode'> + <jc>// RDF namespaces used in this package</jc> + <ja>@RdfSchema</ja>( + prefix=<js>"ab"</js>, + rdfNs={ + <ja>@RdfNs</ja>(prefix=<js>"ab"</js>, namespaceURI=<js>"http://www.apache.org/addressBook/";</js>), + <ja>@RdfNs</ja>(prefix=<js>"per"</js>, namespaceURI=<js>"http://www.apache.org/person/";</js>), + <ja>@RdfNs</ja>(prefix=<js>"addr"</js>, namespaceURI=<js>"http://www.apache.org/address/";</js>), + <ja>@RdfNs</ja>(prefix=<js>"mail"</js>, namespaceURI=<js>"http://www.apache.org/mail/";</js>) + } + ) + <jk>package</jk> org.apache.juneau.sample.addressbook; + <jk>import</jk> org.apache.juneau.xml.annotation.*; + </p> + <p> + This assigns a default prefix of <js>"ab"</js> for all classes and properties within the project, + and specifies various other prefixes used within this project. + </p> + <p> + Now when we rerun the sample code, we'll get the following: + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs><xt>></xt> + <xt><rdf:Description></xt> + <xt><per:id></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + <p> + Namespace auto-detection ({@link org.apache.juneau.xml.XmlSerializerContext#XML_autoDetectNamespaces}) is enabled + on serializers by default.<br> + This causes the serializer to make a first-pass over the data structure to look for namespaces.<br> + In high-performance environments, you may want to consider disabling auto-detection and providing an explicit list of namespaces to the serializer + to avoid this scanning step. + </p> + <p class='bcode'> + <jc>// Create a new serializer, but manually specify the namespaces.</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev() + .setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3) + .setProperty(XmlSerializerContext.<jsf>XML_autoDetectNamespaces</jsf>, <jk>false</jk>) + .setProperty(XmlSerializerContext.<jsf>XML_namespaces</jsf>, <js>"{per:'http://www.apache.org/person/'}"</js>); + </p> + <p> + This code change will produce the same output as before, but will perform slightly better since it doesn't have to crawl the POJO tree before serializing the result. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="UriProperties"></a> + <h3 class='topic' onclick='toggle(this)'>2.2 - URI properties</h3> + <div class='topic'> + <p> + Bean properties of type <code>java.net.URI</code> or <code>java.net.URL</code> have special meaning to the RDF serializer.<br> + They are interpreted as resource identifiers. + </p> + <p> + In the following code, we're adding 2 new properties.<br> + The first property is annotated with <ja>@BeanProperty</ja> to identify that this property is the + resource identifier for this bean.<br> + The second unannotated property is interpreted as a reference to another resource. + </p> + <p class='bcode'> + <jk>public class</jk> Person { + + <jc>// Bean properties</jc> + <ja>@Rdf</ja>(beanUri=<jk>true</jk>) + <jk>public</jk> URI <jf>uri</jf>; + + <jk>public</jk> URI <jf>addressBookUri</jf>; + + ... + + <jc>// Normal constructor</jc> + <jk>public</jk> Person(<jk>int</jk> id, String name, String uri, String addressBookUri) <jk>throws</jk> URISyntaxException { + <jk>this</jk>.<jf>id</jf> = id; + <jk>this</jk>.<jf>name</jf> = name; + <jk>this</jk>.<jf>uri</jf> = <jk>new</jk> URI(uri); + <jk>this</jk>.<jf>addressBookUri</jf> = <jk>new</jk> URI(addressBookUri); + } + } + </p> + <p> + We alter our code to pass in values for these new properties. + </p> + <p class='bcode'> + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>); + </p> + <p> + Now when we run the sample code, we get the following: + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs><xt>></xt> + <xt><rdf:Description <b><xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1";</xs></b>></xt> + <xt><per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook";</xs><xt>/></xt> + <xt><per:id></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + <p> + The {@link org.apache.juneau.annotation.URI} annotation can also be used on classes and properties + to identify them as URLs when they're not instances of <code>java.net.URI</code> or <code>java.net.URL</code> + (not needed if <code><ja>@Rdf</ja>(beanUri=<jk>true</jk>)</code> is already specified). + </p> + <p> + The following properties would have produced the same output as before. Note that the <ja>@URI</ja> annotation is only needed + on the second property. + </p> + <p class='bcode'> + <jk>public class</jk> Person { + + <jc>// Bean properties</jc> + <ja>@Rdf</ja>(beanUri=<jk>true</jk>) <jk>public</jk> String <jf>uri</jf>; + + <ja>@URI</ja> <jk>public</jk> String <jf>addressBookUri</jf>; + </p> + <p> + Also take note of the {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_relativeUriBase} and {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_absolutePathUriBase} + settings that can be specified on the serializer to resolve relative and context-root-relative URIs to fully-qualfied URIs. + </p> + <p> + This can be useful if you want to keep the URI authority and context root information out of the bean logic layer. + </p> + <p> + The following code produces the same output as before, but the URIs on the beans are relative. + </p> + <p class='bcode'> + <jc>// Create a new serializer with readable output.</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev() + .setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3); + .setProperty(SerializerContext.<jsf>SERIALIZER_relativeUriBase</jsf>, <js>"http://myhost/sample";</js>); + .setProperty(SerializerContext.<jsf>SERIALIZER_absolutePathUriBase</jsf>, <js>"http://myhost";</js>); + + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"person/1"</js>, <js>"/"</js>); + + <jc>// Serialize the bean to RDF/XML.</jc> + String rdfXml = s.serialize(p); + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="BeanAnnotations"></a> + <h3 class='topic' onclick='toggle(this)'>2.3 - @Bean and @BeanProperty annotations</h3> + <div class='topic'> + <p> + The {@link org.apache.juneau.annotation.Bean} and {@link org.apache.juneau.annotation.BeanProperty} annotations + are used to customize the behavior of beans across the entire framework.<br> + In addition to using them to identify the resource URI for the bean shown above, they have various other uses: + </p> + <ul class='spaced-list'> + <li>Hiding bean properties. + <li>Specifying the ordering of bean properties. + <li>Overriding the names of bean properties. + <li>Associating transforms at both the class and property level (to convert non-serializable POJOs to serializable forms). + </ul> + <p> + For example, we now add a <code>birthDate</code> property, and associate a swap with it to transform + it to an ISO8601 date-time string in GMT time.<br> + By default, <code>Calendars</code> are treated as beans by the framework, which is usually not how you want them serialized.<br> + Using swaps, we can convert them to standardized string forms. + </p> + <p class='bcode'> + <jk>public class</jk> Person { + + <jc>// Bean properties</jc> + <ja>@BeanProperty</ja>(swap=CalendarSwap.ISO8601DTZ.<jk>class</jk>) <jk>public</jk> Calendar birthDate; + ... + + <jc>// Normal constructor</jc> + <jk>public</jk> Person(<jk>int</jk> id, String name, String uri, String addressBookUri, String birthDate) <jk>throws</jk> Exception { + ... + <jk>this</jk>.<jf>birthDate</jf> = <jk>new</jk> GregorianCalendar(); + <jk>this</jk>.<jf>birthDate</jf>.setTime(DateFormat.<jsm>getDateInstance</jsm>(DateFormat.<jsf>MEDIUM</jsf>).parse(birthDate)); + } + } + </p> + <p> + And we alter our code to pass in the birthdate. + </p> + <p class='bcode'> + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + </p> + <p> + Now when we rerun the sample code, we'll get the following: + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs><xt>></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1";</xs>></xt> + <xt><per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook";</xs><xt>/></xt> + <xt><per:id></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <xt><per:birthDate></xt>1946-08-12T00:00:00Z<xt></per:birthDate></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + </div> + + + <!-- ======================================================================================================== --> + <a id="Collections"></a> + <h3 class='topic' onclick='toggle(this)'>2.4 - Collections</h3> + <div class='topic'> + <p> + Collections and arrays are converted to RDF sequences.<br> + In our example, let's add a list-of-beans property to our sample class: + </p> + <p class='bcode'> + <jk>public class</jk> Person { + + <jc>// Bean properties</jc> + <jk>public</jk> LinkedList<Address> <jf>addresses</jf> = <jk>new</jk> LinkedList<Address>(); + ... + } + </p> + <p> + The <code>Address</code> class has the following properties defined: + </p> + <p class='bcode'> + <ja>@Rdf</ja>(prefix=<js>"addr"</js>) + <jk>public class</jk> Address { + + <jc>// Bean properties</jc> + <ja>@Rdf</ja>(beanUri=<jk>true</jk>) <jk>public</jk> URI <jf>uri</jf>; + <jk>public</jk> URI <jf>personUri</jf>; + + <jk>public int</jk> <jf>id</jf>; + + <ja>@Rdf</ja>(prefix=<js>"mail"</js>) + <jk>public</jk> String <jf>street</jf>, <jf>city</jf>, <jf>state</jf>; + + <ja>@Rdf</ja>(prefix=<js>"mail"</js>) + <jk>public int</jk> <jf>zip</jf>; + + <jk>public boolean</jk> <jf>isCurrent</jf>; + } + </p> + <p> + Next, add some quick-and-dirty code to add an address to our person bean: + </p> + <p class='bcode'> + <jc>// Create a new serializer (revert back to namespace autodetection).</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev().setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3); + + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Address a = <jk>new</jk> Address(); + a.<jf>uri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/address/1";</js>); + a.<jf>personUri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/person/1";</js>); + a.<jf>id</jf> = 1; + a.<jf>street</jf> = <js>"100 Main Street"</js>; + a.<jf>city</jf> = <js>"Anywhereville"</js>; + a.<jf>state</jf> = <js>"NY"</js>; + a.<jf>zip</jf> = 12345; + a.<jf>isCurrent</jf> = <jk>true</jk>; + p.<jf>addresses</jf>.add(a); + </p> + <p> + Now when we run the sample code, we get the following: + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs> + <b><xa>xmlns:mail</xa>=<xs>"http://www.apache.org/mail/";</xs></b> + <b><xa>xmlns:addr</xa>=<xs>"http://www.apache.org/address/";</xs></b><xt>></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1";</xs>></xt> + <xt><per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook";</xs><xt>/></xt> + <xt><per:id></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <b><xt><per:addresses></xt> + <xt><rdf:Seq></xt> + <xt><rdf:li></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/address/1";</xs>></xt> + <xt><addr:personUri <xa>rdf:resource</xa>=<xs>"http://sample/addressBook/person/1";</xs>/></xt> + <xt><addr:id></xt>1<xt></addr:id></xt> + <xt><mail:street></xt>100 Main Street<xt></mail:street></xt> + <xt><mail:city></xt>Anywhereville<xt></mail:city></xt> + <xt><mail:state></xt>NY<xt></mail:state></xt> + <xt><mail:zip></xt>12345<xt></mail:zip></xt> + <xt><addr:isCurrent></xt>true<xt></addr:isCurrent></xt> + <xt></rdf:Description></xt> + <xt></rdf:li></xt> + <xt></rdf:Seq></xt> + <xt></per:addresses></xt></b> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + </div> + + + <!-- ======================================================================================================== --> + <a id="RootProperty"></a> + <h3 class='topic' onclick='toggle(this)'>2.5 - Root property</h3> + <div class='topic'> + <p> + For all RDF languages, the POJO objects get broken down into simple triplets.<br> + Unfortunately, for tree-structured data like the POJOs shown above, this causes the root node of the tree to become lost.<br> + There is no easy way to identify that <code>person/1</code> is the root node in our tree once in triplet form, and in + some cases it's impossible. + </p> + <p> + By default, the {@link org.apache.juneau.jena.RdfParser} class handles this by scanning + all the nodes and identifying the nodes without incoming references.<br> + However, this is inefficient, especially for large models.<br> + And in cases where the root node is referenced by another node in the model by URL, it's not possible to locate the root at all. + </p> + <p> + To resolve this issue, the property {@link org.apache.juneau.jena.RdfSerializerContext#RDF_addRootProperty} was introduced.<br> + When enabled, this adds a special <code>root</code> attribute to the root node to make it easy to locate by the parser. + </p> + <p> + To enable, set the <jsf>RDF_addRootProperty</jsf> property to <jk>true</jk> on the serializer: + </p> + <p class='bcode'> + <jc>// Create a new serializer.</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev() + .setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3), + .setProperty(RdfSerializerContext.<jsf>RDF_addRootProperty</jsf>, <jk>true</jk>); + </p> + <p> + Now when we rerun the sample code, we'll see the added <code>root</code> attribute on the root resource. + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs> + <xa>xmlns:mail</xa>=<xs>"http://www.apache.org/mail/";</xs> + <xa>xmlns:addr</xa>=<xs>"http://www.apache.org/address/";</xs><xt>></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1";</xs>></xt> + <b><xt><j:root></xt>true<xt></j:root></xt></b> + <xt><per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook";</xs><xt>/></xt> + <xt><per:id></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <xt><per:addresses></xt> + <xt><rdf:Seq></xt> + <xt><rdf:li></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/address/1";</xs>></xt> + <xt><addr:personUri <xa>rdf:resource</xa>=<xs>"http://sample/addressBook/person/1";</xs>/></xt> + <xt><addr:id></xt>1<xt></addr:id></xt> + <xt><mail:street></xt>100 Main Street<xt></mail:street></xt> + <xt><mail:city></xt>Anywhereville<xt></mail:city></xt> + <xt><mail:state></xt>NY<xt></mail:state></xt> + <xt><mail:zip></xt>12345<xt></mail:zip></xt> + <xt><addr:isCurrent></xt>true<xt></addr:isCurrent></xt> + <xt></rdf:Description></xt> + <xt></rdf:li></xt> + <xt></rdf:Seq></xt> + <xt></per:addresses></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + </div> + + + <!-- ======================================================================================================== --> + <a id="TypedLiterals"></a> + <h3 class='topic' onclick='toggle(this)'>2.6 - Typed literals</h3> + <div class='topic'> + <p> + XML-Schema datatypes can be added to non-<code>String</code> literals through the {@link org.apache.juneau.jena.RdfSerializerContext#RDF_addLiteralTypes} + setting. + </p> + <p> + To enable, set the <jsf>RDF_addLiteralTypes</jsf> property to <jk>true</jk> on the serializer: + </p> + <p class='bcode'> + <jc>// Create a new serializer (revert back to namespace autodetection).</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev() + .setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3), + .setProperty(RdfSerializerContext.<jsf>RDF_addLiteralTypes</jsf>, <jk>true</jk>); + </p> + <p> + Now when we rerun the sample code, we'll see the added <code>root</code> attribute on the root resource. + </p> + <p class='bcode'> + <xt><rdf:RDF</xt> + <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#";</xs> + <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/";</xs> + <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/";</xs> + <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/";</xs> + <xa>xmlns:mail</xa>=<xs>"http://www.apache.org/mail/";</xs> + <xa>xmlns:addr</xa>=<xs>"http://www.apache.org/address/";</xs><xt>></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1";</xs>></xt> + <xt><per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook";</xs><xt>/></xt> + <xt><per:id</xt> <b><xa>rdf:datatype</xa>=<xs>"http://www.w3.org/2001/XMLSchema#int";</xs></b><xt>></xt>1<xt></per:id></xt> + <xt><per:name></xt>John Smith<xt></per:name></xt> + <xt><per:addresses></xt> + <xt><rdf:Seq></xt> + <xt><rdf:li></xt> + <xt><rdf:Description <xa>rdf:about</xa>=<xs>"http://sample/addressBook/address/1";</xs>></xt> + <xt><addr:personUri <xa>rdf:resource</xa>=<xs>"http://sample/addressBook/person/1";</xs>/></xt> + <xt><addr:id</xt> <b><xa>rdf:datatype</xa>=<xs>"http://www.w3.org/2001/XMLSchema#int";</xs></b>></xt>1<xt></addr:id></xt> + <xt><mail:street></xt>100 Main Street<xt></mail:street></xt> + <xt><mail:city></xt>Anywhereville<xt></mail:city></xt> + <xt><mail:state></xt>NY<xt></mail:state></xt> + <xt><mail:zip</xt> <b><xa>rdf:datatype</xa>=<xs>"http://www.w3.org/2001/XMLSchema#int";</xs></b>></xt>12345<xt></mail:zip></xt> + <xt><addr:isCurrent</xt> <b><xa>rdf:datatype</xa>=<xs>"http://www.w3.org/2001/XMLSchema#boolean";</xs></b>></xt>true<xt></addr:isCurrent></xt> + <xt></rdf:Description></xt> + <xt></rdf:li></xt> + <xt></rdf:Seq></xt> + <xt></per:addresses></xt> + <xt></rdf:Description></xt> + <xt></rdf:RDF></xt> + </p> + </div> + + + <!-- ======================================================================================================== --> + <a id="Recursion"></a> + <h3 class='topic' onclick='toggle(this)'>2.7 - Non-tree models and recursion detection</h3> + <div class='topic'> + <p> + The RDF serializer is designed to be used against tree structures.<br> + It expects that there not be loops in the POJO model (e.g. children with references to parents, etc...).<br> + If you try to serialize models with loops, you will usually cause a <code>StackOverflowError</code> to + be thrown (if {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_maxDepth} is not reached first). + </p> + <p> + If you still want to use the XML serializer on such models, Juneau provides the + {@link org.apache.juneau.serializer.SerializerContext#SERIALIZER_detectRecursions} setting.<br> + It tells the serializer to look for instances of an object in the current branch of the tree and + skip serialization when a duplicate is encountered. + </p> + <p> + Recursion detection introduces a performance penalty of around 20%.<br> + For this reason the setting is disabled by default. + </p> + </div> + + + <!-- ======================================================================================================== --> + <a id="SerializerConfigurableProperties"></a> + <h3 class='topic' onclick='toggle(this)'>2.8 - Configurable properties</h3> + <div class='topic'> + <p> + See the following classes for all configurable properties that can be used on this serializer: + </p> + <ul class='spaced-list'> + <li>{@link org.apache.juneau.BeanContext} - Bean context properties. + <li>{@link org.apache.juneau.jena.RdfSerializerContext} - Serializer context properties. + </ul> + </div> + + + <!-- ======================================================================================================== --> + <a id="SerializerOtherNotes"></a> + <h3 class='topic' onclick='toggle(this)'>2.9 - Other notes</h3> + <div class='topic'> + <ul class='spaced-list'> + <li>Like all other Juneau serializers, the RDF serializer is thread safe and maintains an internal cache of bean classes encountered. + For performance reasons, it's recommended that serializers be reused whenever possible instead of always creating new instances. + </ul> + </div> +</div> + + +<!-- ======================================================================================================== --> +<a id="RdfParser"></a> +<h2 class='topic' onclick='toggle(this)'>3 - RdfParser class</h2> +<div class='topic'> + <p> + The {@link org.apache.juneau.jena.RdfParser} class is the top-level class for all Jena-based parsers.<br> + Language-specific parsers are defined as inner subclasses of the <code>RdfParser</code> class: + </p> + <ul> + <li>{@link org.apache.juneau.jena.RdfParser.Xml} + <li>{@link org.apache.juneau.jena.RdfParser.NTriple} + <li>{@link org.apache.juneau.jena.RdfParser.Turtle} + <li>{@link org.apache.juneau.jena.RdfParser.N3} + </ul> + <p> + The <code>RdfParser.Xml</code> parser handles both regular and abbreviated RDF/XML. + </p> + <p> + Static reusable instances of parsers are also provided with default settings: + </p> + <ul> + <li>{@link org.apache.juneau.jena.RdfParser#DEFAULT_XML} + <li>{@link org.apache.juneau.jena.RdfParser#DEFAULT_TURTLE} + <li>{@link org.apache.juneau.jena.RdfParser#DEFAULT_NTRIPLE} + <li>{@link org.apache.juneau.jena.RdfParser#DEFAULT_N3} + </ul> + <p> + For an example, we will build upon the previous example and parse the generated RDF/XML back into the original bean. + </p> + <p class='bcode'> + <jc>// Create a new serializer with readable output.</jc> + RdfSerializer s = <jk>new</jk> RdfSerializer.XmlAbbrev() + .setProperty(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3) + .setProperty(RdfSerializerContext.<jsf>RDF_addRootProperty</jsf>, <jk>true</jk>); + + <jc>// Create our bean.</jc> + Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1";</js>, <js>"http://sample/addressBook";</js>, <js>"Aug 12, 1946"</js>); + Address a = <jk>new</jk> Address(); + a.<jf>uri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/address/1";</js>); + a.<jf>personUri</jf> = <jk>new</jk> URI(<js>"http://sample/addressBook/person/1";</js>); + a.<jf>id</jf> = 1; + a.<jf>street</jf> = <js>"100 Main Street"</js>; + a.<jf>city</jf> = <js>"Anywhereville"</js>; + a.<jf>state</jf> = <js>"NY"</js>; + a.<jf>zip</jf> = 12345; + a.<jf>isCurrent</jf> = <jk>true</jk>; + p.<jf>addresses</jf>.add(a); + + <jc>// Serialize the bean to RDF/XML.</jc> + String rdfXml = s.serialize(p); + + <jc>// Parse it back into a bean using the reusable XML parser.</jc> + p = RdfParser.<jsf>DEFAULT_XML</jsf>.parse(rdfXml, Person.<jk>class</jk>); + + <jc>// Render it as JSON.</jc> + String json = JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>.serialize(p); + System.<jsm>err</jsm>.println(json); + </p> + <p> + We print it out to JSON to show that all the data has been preserved: + </p> + <p class='bcode'> + { + uri: <js>'http://sample/addressBook/person/1'</js>, + addressBookUri: <js>'http://sample/addressBook'</js>, + id: 1, + name: <js>'John Smith'</js>, + birthDate: <js>'1946-08-12T00:00:00Z'</js>, + addresses: [ + { + uri: <js>'http://sample/addressBook/address/1'</js>, + personUri: <js>'http://sample/addressBook/person/1'</js>, + id: 1, + street: <js>'100 Main Street'</js>, + city: <js>'Anywhereville'</js>, + state: <js>'NY'</js>, + zip: 12345, + isCurrent: <jk>true</jk> + } + ] + } + </p> + + + <!-- ======================================================================================================== --> + <a id="GenericParsing"></a> + <h3 class='topic' onclick='toggle(this)'>3.1 - Parsing into generic POJO models</h3> + <div class='topic'> + <p> + The RDF parser is not limited to parsing back into the original bean classes.<br> + If the bean classes are not available on the parsing side, the parser can also be used to + parse into a generic model consisting of <code>Maps</code>, <code>Collections</code>, and primitive + objects. + </p> + <p> + You can parse into any <code>Map</code> type (e.g. <code>HashMap</code>, <code>TreeMap</code>), but + using {@link org.apache.juneau.ObjectMap} is recommended since it has many convenience methods + for converting values to various types. <br> + The same is true when parsing collections. You can use any Collection (e.g. <code>HashSet</code>, <code>LinkedList</code>) + or array (e.g. <code>Object[]</code>, <code>String[]</code>, <code>String[][]</code>), but using + {@link org.apache.juneau.ObjectList} is recommended. + </p> + <p> + When the map or list type is not specified, or is the abstract <code>Map</code>, <code>Collection</code>, or <code>List</code> types, + the parser will use <code>ObjectMap</code> and <code>ObjectList</code> by default. + </p> + <p> + In the following example, we parse into an <code>ObjectMap</code> and use the convenience methods for performing data conversion on values in the map. + </p> + <p class='bcode'> + <jc>// Parse RDF into a generic POJO model.</jc> + ObjectMap m = RdfParser.<jsf>DEFAULT_XML</jsf>.parse(rdfXml, ObjectMap.<jk>class</jk>); + + <jc>// Get some simple values.</jc> + String name = m.getString(<js>"name"</js>); + <jk>int</jk> id = m.getInt(<js>"id"</js>); + + <jc>// Get a value convertable from a String.</jc> + URI uri = m.get(URI.<jk>class</jk>, <js>"uri"</js>); + + <jc>// Get a value using a swap.</jc> + CalendarSwap swap = <jk>new</jk> CalendarSwap.ISO8601DTZ(); + Calendar birthDate = m.get(swap, <js>"birthDate"</js>); + + <jc>// Get the addresses.</jc> + ObjectList addresses = m.getObjectList(<js>"addresses"</js>); + + <jc>// Get the first address and convert it to a bean.</jc> + Address address = addresses.get(Address.<jk>class</jk>, 0); + </p> + + <p> + However, there are caveats when parsing into generic models due to the nature of RDF.<br> + Watch out for the following: + </p> + <ul class='spaced-list'> + <li>The ordering of entries are going to be inconsistent.<br><br> + <li>Bean URIs are always going to be denoted with the key <js>"uri"</js>.<br> + Therefore, you cannot have a bean with a URI property and a separate property named <js>"uri"</js>.<br> + The latter will overwrite the former.<br> + This isn't a problem when parsing into beans instead of generic POJO models. + <li>All values are strings.<br> + This normally isn't a problem when using <code>ObjectMap</code> and <code>ObjectList</code> since + various methods are provided for converting to the correct type anyway. + <li>The results may not be what is expected if there are lots of URL reference loops in the RDF model.<br> + As nodes are processed from the root node down through the child nodes, the parser keeps + track of previously processed parent URIs and handles them accordingly.<br> + If it finds that the URI has previously been processed, it handles it as a normal URI string and doesn't + process further.<br> + However, depending on how complex the reference loops are, the parsed data may end up having the + same data in it, but structured differently from the original POJO. + </ul> + <p> + We can see some of these when we render the <code>ObjectMap</code> back to JSON. + </p> + <p class='bcode'> + System.<jsm>err</jsm>.println(JsonSerializer.<jsf>DEFAULT_LAX_READABLE</jsf>.serialize(m)); + </p> + <p> + This is what's produced: + </p> + <p class='bcode'> + { + uri: <js>'http://sample/addressBook/person/1'</js>, + addresses: [ + { + uri: <js>'http://sample/addressBook/address/1'</js>, + isCurrent: <js>'true'</js>, + zip: <js>'12345'</js>, + state: <js>'NY'</js>, + city: <js>'Anywhereville'</js>, + street: <js>'100 Main Street'</js>, + id: <js>'1'</js>, + personUri: <js>'http://sample/addressBook/person/1'</js> + } + ], + birthDate: <js>'1946-08-12T00:00:00Z'</js>, + addressBookUri: <js>'http://sample/addressBook'</js>, + name: <js>'John Smith'</js>, + id: <js>'1'</js>, + root: <js>'true'</js> + } + </p> + <p> + As a general rule, parsing into beans is often more efficient than parsing into generic models.<br> + And working with beans is often less error prone than working with generic models. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="ParserConfigurableProperties"></a> + <h3 class='topic' onclick='toggle(this)'>3.2 - Configurable properties</h3> + <!-- TODO --> + <div class='topic'> + <p> + See the following classes for all configurable properties that can be used on this parser: + </p> + <ul class='spaced-list'> + <li>{@link org.apache.juneau.BeanContext} - Bean context properties. + <li>{@link org.apache.juneau.jena.RdfParserContext} - Parser context properties. + </ul> + </div> + + <!-- ======================================================================================================== --> + <a id="ParserOtherNotes"></a> + <h3 class='topic' onclick='toggle(this)'>3.3 - Other notes</h3> + <div class='topic'> + <ul class='spaced-list'> + <li>Like all other Juneau parsers, the RDF parser is thread safe and maintains an internal cache of bean classes encountered. + For performance reasons, it's recommended that parser be reused whenever possible instead of always creating new instances. + </ul> + </div> + +</div> + + +<!-- ======================================================================================================== --> +<a id="RestApiSupport"></a> +<h2 class='topic' onclick='toggle(this)'>4 - REST API support</h2> +<div class='topic'> + <p> + Juneau provides fully-integrated support for RDF serialization/parsing in the REST server and client APIs. + </p> + <p> + The next two sections describe these in detail. + </p> + + <!-- ======================================================================================================== --> + <a id="RestServerSupport"></a> + <h3 class='topic' onclick='toggle(this)'>4.1 - REST server support</h3> + <div class='topic'> + <p> + There are four general ways of defining REST interfaces with support for RDF media types.<br> + Two using the built-in Juneau Server API, and two using the JAX-RS integration component. + </p> + <ul class='spaced-list'> + <li>Create a servlet that subclasses from {@link org.apache.juneau.server.jena.RestServletJenaDefault}.<br> + This includes serialization and parsing for all Jena supported types, including all supported flavors of RDF. + <li>Create a servlet that subclasses from {@link org.apache.juneau.server.RestServlet} and specify the + RDF serializers and parsers using the {@link org.apache.juneau.server.annotation.RestResource#serializers()} and + {@link org.apache.juneau.server.annotation.RestResource#parsers()} on the entire servlet class, or + the {@link org.apache.juneau.server.annotation.RestMethod#serializers()} and {@link org.apache.juneau.server.annotation.RestMethod#parsers()} + annotations on individual methods within the class. + <li>Register {@link org.apache.juneau.server.jaxrs.rdf.DefaultJenaProvider} with JAX-RS to provide support RDF support for all JAX-RS resource.<br> + This includes serialization and parsing for all Juneau supported types (JSON, XML, HTML...), including all supported flavors of RDF. + <li>Create and register a subclass of {@link org.apache.juneau.server.jaxrs.BaseProvider} and specify the serializers and parsers to use on JAX-RS resources. + </ul> + <p> + In general, the Juneau REST server API is much more configurable and easier to use than JAX-RS, but beware that the author may be slightly biased in this statement. + </p> + + <!-- ======================================================================================================== --> + <a id="RestServletJenaDefault"></a> + <h4 class='topic' onclick='toggle(this)'>4.1.1 - Using RestServletJenaDefault</h4> + <div class='topic'> + <p> + The quickest way to implement a REST resource with RDF support is to create a subclass of {@link org.apache.juneau.server.jena.RestServletJenaDefault}.<br> + This class provides support for all the RDF flavors in addition to JSON, XML, HTML, and URL-Encoding. + </p> + <p> + The reason why RDF support was not added to {@link org.apache.juneau.server.RestServletDefault} directly was to keep the Jena prerequisites + out of the <code>org.apache.juneau.server</code> package. + </p> + <p> + The <code>AddressBookResource</code> example shown in the first chapter uses the <code>RestServletJenaDefault</code> class.<br> + The start of the class definition is shown below: + </p> + <p class='bcode'> + <jc>// Proof-of-concept resource that shows off the capabilities of working with POJO resources. + // Consists of an in-memory address book repository.</jc> + <ja>@RestResource</ja>( + messages=<js>"nls/AddressBookResource"</js>, + properties={ + <ja>@Property</ja>(name=RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, value=<js>"3"</js>), + <ja>@Property</ja>(name=RdfSerializerContext.<jsf>RDF_addRootProperty</jsf>, value=<js>"true"</js>), + <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>), + <ja>@Property</ja>(name=HtmlSerializerContext.<jsf>HTML_uriAnchorText</jsf>, value=<jsf>TO_STRING</jsf>), + <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_title</jsf>, value=<js>"$L{title}"</js>), + <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_description</jsf>, value=<js>"$L{description}"</js>), + <ja>@Property</ja>(name=HtmlDocSerializerContext.<jsf>HTMLDOC_links</jsf>, value=<js>"{options:'?method=OPTIONS',doc:'doc'}"</js>) + }, + encoders=GzipEncoder.<jk>class</jk> + ) + <jk>public class</jk> AddressBookResource <jk>extends</jk> RestServletJenaDefault { + </p> + <p> + Notice how serializer and parser properties can be specified using the <code>@RestResource.properties()</code> annotation.<br> + The <jsf>RDF_rdfxml_tab</jsf> and <jsf>RDF_addRootProperty</jsf> are properties on the RDF serializers.<br> + The <jsf>SERIALIZER_quoteChar</jsf> property is common to all serializers.<br> + The remaining properties are specific to the HTML serializer. + </p> + <p> + The <code>$L{...}</code> variable represent localized strings pulled from the resource bundle identified by the <code>messages</code> annotation. + These variables are replaced at runtime based on the HTTP request locale. + Several built-in runtime variable types are defined, and the API can be extended to include user-defined variables. + See {@link org.apache.juneau.server.RestServlet#getVarResolver()} for more information. + </p> + <p> + This document won't go into all the details of the Juneau <code>RestServlet</code> class.<br> + Refer to the {@link org.apache.juneau.server} documentation for more information on the REST servlet class in general. + </p> + <p> + The rest of the code in the resource class consists of REST methods that simply accept and return POJOs.<br> + The framework takes care of all content negotiation, serialization/parsing, and error handling.<br> + Below are 3 of those methods to give you a general idea of the concept: + </p> + <p class='bcode'> + <jc>// GET person request handler</jc> + <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/people/{id}/*"</js>, rc={200,404}) + <jk>public</jk> Person getPerson(RestRequest req, <ja>@Path</ja> <jk>int</jk> id) throws Exception { + properties.put(HtmlDocSerializerContext.<jsf>HTMLDOC_title</jsf>, req.getPathInfo()); + <jk>return</jk> findPerson(id); + } + + <jc>// POST person handler</jc> + <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/people"</js>, guards=AdminGuard.<jk>class</jk>, rc={307,404}) + <jk>public void</jk> createPerson(RestResponse res, <ja>@Body</ja> CreatePerson cp) <jk>throws</jk> Exception { + Person p = addressBook.createPerson(cp); + res.sendRedirect(p.<jf>uri</jf>); + } + + <jc>// DELETE person handler</jc> + <ja>@RestMethod</ja>(name=<js>"DELETE"</js>, path=<js>"/people/{id}"</js>, guards=AdminGuard.<jk>class</jk>, rc={200,404}) + <jk>public</jk> String deletePerson(RestResponse res, <ja>@Path</ja> <jk>int</jk> id) <jk>throws</jk> Exception { + Person p = findPerson(id); + addressBook.remove(p); + <jk>return</jk> <js>"DELETE successful"</js>; + } + </p> + <p> + The resource class can be registered with the web application like any other servlet, or can be + defined as a child of another resource through the {@link org.apache.juneau.server.annotation.RestResource#children()} annotation. + </div> + + <!-- ======================================================================================================== --> + <a id="RestServlet"></a> + <h4 class='topic' onclick='toggle(this)'>4.1.2 - Using RestServlet with annotations</h4> + <div class='topic'> + <p> + For fine-tuned control of media types, the {@link org.apache.juneau.server.RestServlet} class + can be subclassed directly.<br> + The serializers/parsers can be specified through annotations at the class and/or method levels. + </p> + <p> + An equivalent <code>AddressBookResource</code> class could be defined to only support RDF/XML using + the following definition: + </p> + <p class='bcode'> + <ja>@RestResource</ja>( + serializers={RdfSerializer.XmlAbbrev.<jk>class</jk>}, + parsers={RdfParser.Xml.<jk>class</jk>}, + properties={ + <ja>@Property</ja>(name=RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, value=<js>"3"</js>), + <ja>@Property</ja>(name=RdfSerializerContext.<jsf>RDF_addRootProperty</jsf>, value=<js>"true"</js>), + <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) + } + ) + <jk>public class</jk> AddressBookResource <jk>extends</jk> RestServlet { + </p> + <p> + Likewise, serializers and parsers can be specified/augmented/overridden at the method level like so: + </p> + <p class='bcode'> + <jc>// GET person request handler</jc> + <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/people/{id}/*"</js>, rc={200,404}, + serializers={RdfSerializer.XmlAbbrev.<jk>class</jk>}, + parsers={RdfParser.Xml.<jk>class</jk>}, + properties={ + <ja>@Property</ja>(name=RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, value=<js>"3"</js>), + <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) + } + ) + <jk>public</jk> Person getPerson(RestRequest req, <ja>@Path</ja> <jk>int</jk> id) throws Exception { + properties.put(HtmlDocSerializerContext.<jsf>HTMLDOC_title</jsf>, req.getPathInfo()); + <jk>return</jk> findPerson(id); + } + </p> + <p> + The {@link org.apache.juneau.server.annotation.RestMethod#serializersInherit()} and + {@link org.apache.juneau.server.annotation.RestMethod#parsersInherit()} control how various artifacts + are inherited from the parent class.<br> + Refer to {@link org.apache.juneau.server} for additional information on using these annotations. + </p> + </div> + + <!-- ======================================================================================================== --> + <a id="DefaultJenaProvider"></a> + <h4 class='topic' onclick='toggle(this)'>4.1.3 - Using JAX-RS DefaultJenaProvider</h4> + <div class='topic'> + <p> + RDF media type support in JAX-RS can be achieved by using the {@link org.apache.juneau.server.jaxrs.rdf.DefaultJenaProvider} class.<br> + It implements the JAX-RS <code>MessageBodyReader</code> and <code>MessageBodyWriter</code> interfaces for all Juneau supported media types. + </p> + <p> + The <code>DefaultJenaProvider</code> class definition is shown below: + </p> + <p class='bcode'> + <ja>@Provider</ja> + <ja>@Produces</ja>( + <js>"application/json,text/json,"</js>+ <jc>// JsonSerializer</jc> + <js>"application/json+simple,text/json+simple,"</js>+ <jc>// JsonSerializer.Simple</jc> + <js>"application/json+schema,text/json+schema,"</js>+ <jc>// JsonSchemaSerializer</jc> + <js>"text/xml,"</js>+ <jc>// XmlDocSerializer</jc> + <js>"text/xml+simple,"</js>+ <jc>// XmlDocSerializer.Simple</jc> + <js>"text/xml+schema,"</js>+ <jc>// XmlSchemaDocSerializer</jc> + <js>"text/html,"</js>+ <jc>// HtmlDocSerializer</jc> + <js>"application/x-www-form-urlencoded,"</js>+ <jc>// UrlEncodingSerializer</jc> + <js>"text/xml+soap,"</js>+ <jc>// SoapXmlSerializer</jc> + <js>"text/xml+rdf,"</js>+ <jc>// RdfSerializer.Xml</jc> + <js>"text/xml+rdf+abbrev,"</js>+ <jc>// RdfSerializer.XmlAbbrev</jc> + <js>"text/n-triple,"</js>+ <jc>// RdfSerializer.NTriple</jc> + <js>"text/turtle,"</js>+ <jc>// RdfSerializer.Turtle</jc> + <js>"text/n3,"</js>+ <jc>// RdfSerializer.N3</jc> + <js>"application/x-java-serialized-object"</js> <jc>// JavaSerializedObjectSerializer</jc> + ) + <ja>@Consumes</ja>( + <js>"application/json,text/json,"</js>+ <jc>// JsonParser</jc> + <js>"text/xml,"</js>+ <jc>// XmlParser</jc> + <js>"text/html,"</js>+ <jc>// HtmlParser</jc> + <js>"application/x-www-form-urlencoded,"</js>+ <jc>// UrlEncodingParser</jc> + <js>"text/xml+rdf,"</js>+ <jc>// RdfParser.Xml</jc> + <js>"text/n-triple,"</js>+ <jc>// RdfParser.NTriple</jc> + <js>"text/turtle,"</js>+ <jc>// RdfParser.Turtle</jc> + <js>"text/n3,"</js>+ <jc>// RdfParser.N3</jc> + <js>"application/x-java-serialized-object"</js> <jc>// JavaSerializedObjectParser</jc> + ) + <ja>@JuneauProvider</ja>( + serializers={ + JsonSerializer.<jk>class</jk>, + JsonSerializer.Simple.<jk>class</jk>, + JsonSchemaSerializer.<jk>class</jk>, + XmlDocSerializer.<jk>class</jk>, + XmlDocSerializer.Simple.<jk>class</jk>, + XmlSchemaDocSerializer.<jk>class</jk>, + HtmlDocSerializer.<jk>class</jk>, + UrlEncodingSerializer.<jk>class</jk>, + SoapXmlSerializer.<jk>class</jk>, + RdfSerializer.Xml.<jk>class</jk>, + RdfSerializer.XmlAbbrev.<jk>class</jk>, + RdfSerializer.NTriple.<jk>class</jk>, + RdfSerializer.Turtle.<jk>class</jk>, + RdfSerializer.N3.<jk>class</jk>, + JavaSerializedObjectSerializer.<jk>class</jk> + }, + parsers={ + JsonParser.<jk>class</jk>, + XmlParser.<jk>class</jk>, + HtmlParser.<jk>class</jk>, + UrlEncodingParser.<jk>class</jk>, + RdfParser.Xml.<jk>class</jk>, + RdfParser.NTriple.<jk>class</jk>, + RdfParser.Turtle.<jk>class</jk>, + RdfParser.N3.<jk>class</jk>, + JavaSerializedObjectParser.<jk>class</jk>, + } + ) + <jk>public final class</jk> DefaultJenaProvider <jk>extends</jk> BaseProvider {} + </p> + <p> + That's the entire class. It consists of only annotations to hook up media types to Juneau serializers and parsers.<br> + The <ja>@Provider</ja>, <ja>@Produces</ja>, and <ja>@Consumes</ja> annotations are standard JAX-RS annotations, and the <ja>@JuneauProvider</ja> annotation is from Juneau. + </p> + <p> + To enable the provider, you need to make the JAX-RS environment aware of it.<br> + In Wink, this is accomplished by adding an entry to a config file. + </p> + <p class='bcode'> + <xt><web-app</xt> <xa>version</xa>=<xs>"2.3"</xs><xt>></xt> + <xt><servlet></xt> + <xt><servlet-name></xt>WinkService<xt></servlet-name></xt> + <xt><servlet-class></xt>org.apache.wink.server.internal.servlet.RestServlet<xt></servlet-class></xt> + <xt><init-param></xt> + <xt><param-name></xt>applicationConfigLocation<xt></param-name></xt> + <xt><param-value></xt>/WEB-INF/wink.cfg<xt></param-value></xt> + <xt></init-param></xt> + <xt></servlet></xt> + </p> + <p> + Simply include a reference to the provider in the configuration file. + <p class='bcode'> + org.apache.juneau.server.jaxrs.DefaultJenaProvider + </p> + <p> + Properties can be specified on providers through the {@link org.apache.juneau.server.jaxrs.JuneauProvider#properties()} annotation. + </p> + <p> + Properties can also be specified at the method level by using the {@link org.apache.juneau.server.annotation.RestMethod#properties} annotation, like so: + </p> + <p class='bcode'> + <ja>@GET</ja> + <ja>@Produces</ja>(<js>"*/*"</js>) + <ja>@RestMethod</ja>( <jc>/* Override some properties */</jc> + properties={ + <ja>@Property</ja>(name=RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, value=<js>"3"</js>), + <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) + } + ) + <jk>public</jk> Message getMessage() { + <jk>return</jk> message; + } + </p> + <h6 class='topic'>Limitations</h6> + <p> + In general, the Juneau REST API is considerably more flexible than the JAX-RS API, since you can specify and override + serializers, parsers, properties, transforms, converters, guards, etc... at both the class and method levels.<br> + Therefore, the JAX-RS API has the following limitations that the Juneau Server API does not: + </p> + <ul class='spaced-list'> + <li>The ability to specify different media type providers at the class and method levels.<br> + For example, you may want to use <code>RdfSerializer.Xml</code> with one set of properties on + one class, and another instance with different properties on another class.<br> + There is currently no way to define this at the class level.<br> + You can override properties at the method level, but this can be cumbersome since it would have to be + done for all methods in the resource. + <li>The Juneau Server API allows you to manipulate properties programatically through the {@link org.apache.juneau.server.RestResponse#setProperty(String,Object)} + method, and through the {@link org.apache.juneau.server.annotation.Properties} annotation.<br> + There is no equivalent in JAX-RS. + </ul> + </div> + + <!-- ======================================================================================================== --> + <a id="BaseProvider"></a> + <h4 class='topic' onclick='toggle(this)'>4.1.4 - Using JAX-RS BaseProvider with annotations</h4> + <div class='topic'> + <p> + To provide support for only RDF media types, you can define your own provider class, like so: + </p> + <p class='bcode'> + <ja>@Provider</ja> + <ja>@Produces</ja>( + <js>"text/xml+rdf,"</js>+ <jc>// RdfSerializer.Xml</jc> + <js>"text/xml+rdf+abbrev,"</js>+ <jc>// RdfSerializer.XmlAbbrev</jc> + <js>"text/n-triple,"</js>+ <jc>// RdfSerializer.NTriple</jc> + <js>"text/turtle,"</js>+ <jc>// RdfSerializer.Turtle</jc> + <js>"text/n3"</js>+ <jc>// RdfSerializer.N3</jc> + ) + <ja>@Consumes</ja>( + <js>"text/xml+rdf,"</js>+ <jc>// RdfParser.Xml</jc> + <js>"text/n-triple,"</js>+ <jc>// RdfParser.NTriple</jc> + <js>"text/turtle,"</js>+ <jc>// RdfParser.Turtle</jc> + <js>"text/n3"</js> <jc>// RdfParser.N3</jc> + ) + <ja>@JuneauProvider</ja>( + serializers={ + RdfSerializer.Xml.<jk>class</jk>, + RdfSerializer.XmlAbbrev.<jk>class</jk>, + RdfSerializer.NTriple.<jk>class</jk>, + RdfSerializer.Turtle.<jk>class</jk>, + RdfSerializer.N3.<jk>class</jk>, + }, + parsers={ + RdfParser.Xml.<jk>class</jk>, + RdfParser.NTriple.<jk>class</jk>, + RdfParser.Turtle.<jk>class</jk>, + RdfParser.N3.<jk>class</jk>, + }, + properties={ + <ja>@Property</ja>(name=RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, value=<js>"3"</js>), + <ja>@Property</ja>(name=SerializerContext.<jsf>SERIALIZER_quoteChar</jsf>, value=<js>"'"</js>) + } + ) + <jk>public final class</jk> MyRdfProvider <jk>extends</jk> BaseProvider {} + </p> + <p> + Then register it with Wink the same way as <code>DefaultJenaProvider</code>. + </p> + </div> + + </div> + + <!-- ======================================================================================================== --> + <a id="RestClientSupport"></a> + <h3 class='topic' onclick='toggle(this)'>4.2 - REST client support</h3> + <div class='topic'> + <p> + The {@link org.apache.juneau.client.RestClient} class provides an easy-to-use REST client interface with + pluggable media type handling using any of the Juneau serializers and parsers. + </p> + <p> + Defining a client to support RDF media types on HTTP requests and responses can be done in one line of code: + </p> + <p class='bcode'> + <jc>// Create a client to handle RDF/XML requests and responses.</jc> + RestClient client = <jk>new</jk> RestClient(RdfSerializer.XmlAbbrev.<jk>class</jk>, RdfParser.Xml.<jk>class</jk>); + </p> + <p> + The client handles all content negotiation based on the registered serializers and parsers. + </p> + <p> + The following code is pulled from the main method of the <code>ClientTest</code> class in the sample web application, and + is run against the <code>AddressBookResource</code> class running within the sample app. + It shows how the client can be used to interact with the REST API while completely hiding the negotiated content type and working with nothing more than beans. + </p> + <p class='bcode'> + String root = <js>"http://localhost:9080/sample/addressBook";</js>; + + <jc>// Get the current contents of the address book</jc> + AddressBook ab = client.doGet(root).getResponse(AddressBook.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Number of entries = "</js> + ab.size()); + + <jc>// Delete the existing entries</jc> + <jk>for</jk> (Person p : ab) { + String r = client.doDelete(p.<jf>uri</jf>).getResponse(String.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Deleted person "</js> + p.<jf>name</jf> + <js>", response = "</js> + r); + } + + <jc>// Make sure they're gone</jc> + ab = client.doGet(root).getResponse(AddressBook.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Number of entries = "</js> + ab.size()); + + <jc>// Add 1st person again</jc> + CreatePerson cp = <jk>new</jk> CreatePerson( + <js>"Barack Obama"</js>, + <jsm>toCalendar</jsm>(<js>"Aug 4, 1961"</js>), + <jk>new</jk> CreateAddress(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>true</jk>), + <jk>new</jk> CreateAddress(<js>"5046 S Greenwood Ave"</js>, <js>"Chicago"</js>, <js>"IL"</js>, 60615, <jk>false</jk>) + ); + Person p = client.doPost(root + <js>"/people"</js>, cp).getResponse(Person.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Created person "</js> + p.<jf>name</jf> + <js>", uri = "</js> + p.<jf>uri</jf>); + + <jc>// Add 2nd person again, but add addresses separately</jc> + cp = <jk>new</jk> CreatePerson( + <js>"George Walker Bush"</js>, + toCalendar(<js>"Jul 6, 1946"</js>) + ); + p = client.doPost(root + <js>"/people"</js>, cp).getResponse(Person.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Created person "</js> + p.<jf>name</jf> + <js>", uri = "</js> + p.<jf>uri</jf>); + + <jc>// Add addresses to 2nd person</jc> + CreateAddress ca = <jk>new</jk> CreateAddress(<js>"43 Prairie Chapel Rd"</js>, <js>"Crawford"</js>, <js>"TX"</js>, 76638, <jk>true</jk>); + Address a = client.doPost(p.<jf>uri</jf> + <js>"/addresses"</js>, ca).getResponse(Address.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Created address "</js> + a.<jf>uri</jf>); + + ca = <jk>new</jk> CreateAddress(<js>"1600 Pennsylvania Ave"</js>, <js>"Washington"</js>, <js>"DC"</js>, 20500, <jk>false</jk>); + a = client.doPost(p.<jf>uri</jf> + "/addresses"</js>, ca).getResponse(Address.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Created address "</js> + a.<jf>uri</jf>); + + <jc>// Find 1st person, and change name</jc> + Person[] pp = client.doGet(root + <js>"?q={name:\"'Barack+Obama'\"}"</js>).getResponse(Person[].<jk>class</jk>); + String r = client.doPut(pp[0].<jf>uri</jf> + <js>"/name"</js>, <js>"Barack Hussein Obama"</js>).getResponse(String.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"Changed name, response = "</js> + r); + p = client.doGet(pp[0].<jf>uri</jf>).getResponse(Person.<jk>class</jk>); + System.<jsm>out</jsm>.println(<js>"New name = "</js> + p.<jf>name</jf>); + </p> + <p> + The code above produces the following output. + </p> + <p class='bcode'> + Number of entries = 2 + Deleted person Barack Obama, response = DELETE successful + Deleted person George Walker Bush, response = DELETE successful + Number of entries = 0 + Created person Barack Obama, uri = http://localhost:9080/sample/addressBook/people/3 + Created person George Walker Bush, uri = http://localhost:9080/sample/addressBook/people/4 + Created address http://localhost:9080/sample/addressBook/addresses/7 + Created address http://localhost:9080/sample/addressBook/addresses/8 + Changed name, response = PUT successful + New name = Barack Hussein Obama + </p> + </div> +</div> +<p align="center"><i><b>*** fÃn ***</b></i></p> + +</body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-rdf/src/main/resources/.gitignore ---------------------------------------------------------------------- diff --git a/juneau-core-rdf/src/main/resources/.gitignore b/juneau-core-rdf/src/main/resources/.gitignore new file mode 100644 index 0000000..8a0051a --- /dev/null +++ b/juneau-core-rdf/src/main/resources/.gitignore @@ -0,0 +1,12 @@ + *************************************************************************************************************************** + * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * + * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * + * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * + * with the License. You may obtain a copy of the License at * + * * + * http://www.apache.org/licenses/LICENSE-2.0 * + * * + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * + * specific language governing permissions and limitations under the License. * + *************************************************************************************************************************** http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-test/.gitignore ---------------------------------------------------------------------- diff --git a/juneau-core-test/.gitignore b/juneau-core-test/.gitignore new file mode 100644 index 0000000..5b1eab9 --- /dev/null +++ b/juneau-core-test/.gitignore @@ -0,0 +1,5 @@ +/target/ +/.DS_Store +/.settings/ +/.classpath +/bin/ http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/e4dfdf81/juneau-core-test/.project ---------------------------------------------------------------------- diff --git a/juneau-core-test/.project b/juneau-core-test/.project new file mode 100644 index 0000000..fe1874b --- /dev/null +++ b/juneau-core-test/.project @@ -0,0 +1,28 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + *************************************************************************************************************************** + * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * + * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * + * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * + * with the License. You may obtain a copy of the License at * + * * + * http://www.apache.org/licenses/LICENSE-2.0 * + * * + * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * + * specific language governing permissions and limitations under the License. * + *************************************************************************************************************************** +--> +<projectDescription> + <name>juneau-core</name> + <comment>Base toolkit for serializers, parsers, and bean contexts. NO_M2ECLIPSE_SUPPORT: Project files created with the maven-eclipse-plugin are not supported in M2Eclipse.</comment> + <projects/> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> \ No newline at end of file
