[exo-jcr-commits] exo-jcr SVN: r3380 - in jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules: ws and 1 other directory.
do-not-reply at jboss.org
do-not-reply at jboss.org
Tue Nov 2 10:29:13 EDT 2010
Author: aparfonov
Date: 2010-11-02 10:29:13 -0400 (Tue, 02 Nov 2010)
New Revision: 3380
Added:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws/overwrite-default-providers.xml
Modified:
jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws.xml
Log:
EXOJCR-1024 : add docbook with feature description
Added: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws/overwrite-default-providers.xml
===================================================================
--- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws/overwrite-default-providers.xml (rev 0)
+++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws/overwrite-default-providers.xml 2010-11-02 14:29:13 UTC (rev 3380)
@@ -0,0 +1,213 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="WS.OverwriteDefaultProviders">
+ <?dbhtml filename="overwrite-default-providers.html"?>
+
+ <title>OverwriteDefaultProviders</title>
+
+ <section>
+ <title>Motivation</title>
+
+ <para>There is set of providers embedded in eXo JAX-RS
+ implementation.</para>
+
+ <para>Implementations of MessageBodyReader and MessageBodyWriters are
+ taking care about serialization/deserialization of message body (HTTP
+ request/response's body).</para>
+
+ <para>The next set of media and Java types processed automatically, thanks
+ to embedded Readers (Writers).</para>
+
+ <table>
+ <title>Embedded Reader and Writers of message body</title>
+
+ <tgroup cols="2">
+ <colspec align="center" />
+
+ <thead>
+ <row>
+ <entry align="center">Media Type</entry>
+
+ <entry align="center">Java Type</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>*/*</entry>
+
+ <entry>byte[]</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>javax.activation.DataSource</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>java.io.File</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>java.io.InputStream</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>java.io.Reader</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>java.lang.String</entry>
+ </row>
+
+ <row>
+ <entry>*/*</entry>
+
+ <entry>javax.ws.rs.core.StreamingOutput (Writer ONLY)</entry>
+ </row>
+
+ <row>
+ <entry>application/json</entry>
+
+ <entry>1. Object with simple constructor + get/set methods; 2.
+ Java Collection (java.uitl.List<T>, java.uitl.Set<T>,
+ java.util.Map<String, T>, etc) where T as described in
+ 1.</entry>
+ </row>
+
+ <row>
+ <entry>application/x-www-form-urlencoded</entry>
+
+ <entry>javax.ws.rs.core.MultivaluedMap<String,
+ String></entry>
+ </row>
+
+ <row>
+ <entry>multipart/*</entry>
+
+ <entry>java.util.Iterator<org.apache.commons.fileupload.FileItem></entry>
+ </row>
+
+ <row>
+ <entry>application/xml, application/xhtml+xml, text/xml</entry>
+
+ <entry>javax.xml.bind.JAXBElement</entry>
+ </row>
+
+ <row>
+ <entry>application/xml, application/xhtml+xml, text/xml</entry>
+
+ <entry>Object with JAXB annotations</entry>
+ </row>
+
+ <row>
+ <entry>application/xml, application/xhtml+xml, text/xml</entry>
+
+ <entry>javax.xml.transform.stream.StreamSource</entry>
+ </row>
+
+ <row>
+ <entry>application/xml, application/xhtml+xml, text/xml</entry>
+
+ <entry>javax.xml.transform.sax.SAXSource</entry>
+ </row>
+
+ <row>
+ <entry>application/xml, application/xhtml+xml, text/xml</entry>
+
+ <entry>javax.xml.transform.dom.DOMSource</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>In some case it may be required to use alternative provider for the
+ same media and java type but such changes must not impact to any other
+ services.</para>
+ </section>
+
+ <section>
+ <title>Usage</title>
+
+ <para>To be able overwrite default JAX-RS provider(s) developer
+ need:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Deploy own RESTful service(s) by using subclass of
+ javax.ws.rs.core.Application (hereinafter Application).</para>
+ </listitem>
+
+ <listitem>
+ <para>Service(s) NOT NEED to implement marker interface
+ ResourceContainer and MUST NOT be configured as component(s) of eXo
+ Container. Instead of it Application must be configured as component
+ of eXo Container.</para>
+ </listitem>
+
+ <listitem>
+ <para>If RESTful services or providers require some dependencies from
+ eXo Container then Application should inject it by own constructor and
+ then delegate to services or providers. As alternative method
+ getClasses() may be used for deliver services/providers classes
+ instead of instances. In this case services/providers will work in
+ per-request mode and RESTful framework will take care about resolving
+ dependencies.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Example</title>
+
+ <para>In example below see how to use Jackson JSON provider instead of
+ embedded in eXo RESTful framework.</para>
+
+ <para>Create subclass of javax.ws.rs.core.Application with code as bellow
+ and add it to the eXo Container configuration.</para>
+
+ <programlisting>package org.exoplatform.test.jackson;
+
+import org.codehaus.jackson.jaxrs.JacksonJaxbJsonProvider;
+
+import java.util.HashSet;
+import java.util.Set;
+
+import javax.ws.rs.core.Application;
+
+public class Application1 extends Application
+{
+ @Override
+ public Set<Class<?>> getClasses()
+ {
+ Set<Class<?>> cls = new HashSet<Class<?>>(1);
+ cls.add(Resource1.class);
+ return cls;
+ }
+
+ @Override
+ public Set<Object> getSingletons()
+ {
+ Set<Object> objs = new HashSet<Object>(1);
+ objs.add(new JacksonJaxbJsonProvider());
+ return objs;
+ }
+}</programlisting>
+
+ <para>In this example we assumes Resource1 is Java class which carries
+ JAX-RS annotations and it uses JSON. In this case RESTful framework will
+ use JacksonJaxbJsonProvider for serializing/deserializing of all messages
+ to/from Resource1. But it will not impact to other services in any kind.
+ </para>
+ </section>
+</chapter>
Modified: jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws.xml
===================================================================
--- jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws.xml 2010-11-02 13:47:09 UTC (rev 3379)
+++ jcr/trunk/exo.jcr.docs/exo.jcr.docs.developer/en/src/main/docbook/en-US/modules/ws.xml 2010-11-02 14:29:13 UTC (rev 3380)
@@ -12,6 +12,9 @@
<xi:include href="ws/introduction-to-rest.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="ws/overwrite-default-providers.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
<xi:include href="ws/restservicelist-service.xml"
xmlns:xi="http://www.w3.org/2001/XInclude" />
More information about the exo-jcr-commits
mailing list