4:24 p.m.
Author: elvisisking
Date: 2010-01-07 17:24:56 -0500 (Thu, 07 Jan 2010)
New Revision: 1555
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml
trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml
Log:
DNA-629 Document The REST Client API In The Reference Guide: Added new section and
modified introduction. Reviewed by Brian C.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2010-01-07
19:12:33 UTC (rev 1554)
+++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2010-01-07
22:24:56 UTC (rev 1555)
@@ -519,6 +519,14 @@
can be consulted as a template for how to deploy the RESTful services in a
custom implementation.
</para>
</listitem>
+ <listitem>
+ <para>
+ <emphasis
role="strong">dna-web-jcr-rest-client</emphasis>
+ is an API that uses POJOs to access the REST web service. This API eliminates
the need for applications to know how
+ to create HTTP request URLs and payloads, and how to parse the JSON
responses. It can be used to publish (upload)
+ and unpublish (delete) files from DNA repositories.
+ </para>
+ </listitem>
</itemizedlist>
There are also documentation modules (located in the source under the
<code>docs/</code>
Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2010-01-07
19:12:33 UTC (rev 1554)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2010-01-07
22:24:56 UTC (rev 1555)
@@ -578,5 +578,66 @@
repository should shutdown and clean up any resources that are in use.
</para>
</sect1>
+
+ <sect1 id="dna_rest_client_api">
+ <title>DNA REST Client API</title>
+ <para>
+ The DNA REST Client API provides a POJO way of using the DNA REST web service
to publish (upload) and
+ unpublish (delete) files from DNA repositories. Java objects open the HTTP
connection, create the HTTP request URLs,
+ attach the payload associated with <code>PUT</code> and
<code>POST</code> requests, parse the HTTP JSON response back
+ into Java objects, and close the HTTP connection.
+ </para>
+ <para>
+ Here are the Java business objects you will need (all found in the
<code>org.jboss.dna.web.jcr.rest.client.domain</code>
+ package):
+
+ <itemizedlist>
+ <listitem>
+ <para><code>Server</code> - hosts one or more DNA
JCR repositories,</para>
+ </listitem>
+ <listitem>
+ <para><code>Repository</code> - a DNA JCR
repository containing one or more workspaces, and</para>
+ </listitem>
+ <listitem>
+ <para><code>Workspace</code> - a DNA JCR repository
workspace.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Along with the POJOs above, an
<code>org.jboss.dna.web.jcr.rest.client.IRestClient</code> is needed. The
+ <code>IRestClient</code> is responsible for executing the
publishing and unpublishing operations. You can also use the
+ <code>IRestClient</code> to find out what repositories and
workspaces are available on a DNA server.
+
+ <note>
+ <para>
+ The only implementation of <code>IRestClient</code> is
<code>JsonRestClient</code> as JSON-encoded responses are
+ all that are currently available.
+ </para>
+ </note>
+
+ Here's a code snippet that publishes (uploads) a file:
+
+ <programlisting><![CDATA[
+// Setup POJOs
+Server server = new Server("http://localhost:8080", "username",
"password");
+Repository repository = new Repository("repositoryName", server);
+Workspace workspace = new Workspace("workspaceName", repository);
+
+// Publish
+File file = new File("/path/to/file");
+IRestClient restClient = new JsonRestClient();
+Status status = restClient.publish(workspace, "/workspace/path/", file);
+
+if (status.isError() {
+ // Handle error here
+}
+ ]]></programlisting>
+ </para>
+ <para>
+ Results of successfully executing the above code is a JCR folder node
(<code>nt:folder</code>) for each segment of the
+ workspace path (a node is created if it doesn't already exist). Also, a
JCR file node (a node with primary type <code>nt:file</code>) is
+ created or updated under the last folder node and the file contents are
encoded and uploaded into a child node of that file node.
+ </para>
+ </sect1>
</chapter>