Author: bcarothers Date: 2009-06-09 12:45:30 -0400 (Tue, 09 Jun 2009) New Revision: 1014 Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml trunk/docs/reference/src/main/docbook/en-US/custom.dtd trunk/extensions/dna-web-jcr-rest-war/src/main/webapp/WEB-INF/web.xml trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrApplication.java Log: Final draft of REST chapter 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 2009-06-09 16:36:50 UTC (rev 1013) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2009-06-09 16:45:30 UTC (rev 1014) @@ -89,7 +89,7 @@ </programlisting> This request would generate a response that mapped the names of the available repositories to metadata information about the repositories like so: -<programlisting> +<programlisting><![CDATA[ { "dna%3arepository" : { "repository" : { @@ -98,7 +98,7 @@ } } } -</programlisting> +]]></programlisting> The actual response wouldn't be pretty-printed like the example, but the format would be the same. The name of the repository ("dna:repository" URL-encoded) is mapped to a repository object that contains a name (the redundant "dna:repository") and a list of available resources within the repository and their respective @@ -115,7 +115,7 @@ require that security be configured. This process is described in more detail in <link linkend="dna_rest_server_configuration">a later section</link>. Assuming that security has been properly configured, the response would look something like this: -<programlisting> +<programlisting><![CDATA[ { "default" : { "workspace" : { @@ -124,7 +124,7 @@ } } } -</programlisting> +]]></programlisting> Like the first response, this response consists of a list of workspace names mapped to metadata about the workspaces. The example above only lists one workspace for simplicity, but there could be many different workspaces returned in a real deployment. Note that the "items" resource builds the full URI to the root @@ -137,14 +137,14 @@ </programlisting> Any other item in the repository could be accessed by appending its path to the URI above. In a default repository with no content, this would return the following response: -<programlisting> +<programlisting><![CDATA[ { "properties": { "jcr:primaryType": "dna:root", "jcr:uuid": "97d7e2ef-996e-4d99-8ec2-dc623e6c2239" }, "children": ["jcr:system"] -</programlisting> +]]></programlisting> The response contains a mapping of property names to their values and an array of child names. Had one of the properties been multi-valued, the values for that property would have been provided as an array as well, as will shortly be shown. @@ -156,7 +156,7 @@ GET http://www.example.com/resources/dna%3arepository/default/items?dna:depth=2 </programlisting> Then the response would have contained details for the children of the root node as well. -<programlisting> +<programlisting><![CDATA[ { "properties": { "jcr:primaryType": "dna:root", @@ -169,7 +169,7 @@ } } } -</programlisting> +]]></programlisting> </para> <para> It is also possible to use the RESTful API to add, modify and remove repository content. Removes are simple - @@ -182,7 +182,7 @@ Adding content simply requires a POST to the name of the <emphasis>relative</emphasis> root node of the content that you wish to add and a request body in the same format as the response from a GET. Adding multiple nodes at once is supported, as shown below. -<programlisting> +<programlisting><![CDATA[ POST http://www.example.com/resources/dna%3arepository/default/items/newNode { @@ -197,7 +197,7 @@ } } } -</programlisting> +]]></programlisting> Note that protected properties like jcr:uuid are not provided but that the primary type and mixin types are provided as properties. The REST server will translate these into the appropriate calls behind the scenes. The response from the request will be empty by convention. @@ -205,21 +205,21 @@ <para> The PUT method allows for updates of nodes and properties. If the URI points to a property, the body of the request should be the new JSON-encoded value for the property. -<programlisting> +<programlisting><![CDATA[ PUT http://www.example.com/resources/dna%3arepository/default/items/newNode/s... "bar" -</programlisting> +]]></programlisting> Setting multiple properties at once can be performed by providing a URI to a node instead of a property. The body of the request should then be a JSON object that maps property names to their new values. -<programlisting> +<programlisting><![CDATA[ PUT http://www.example.com/resources/dna%3arepository/default/items/newNode { "someProperty": "foobar", "someOtherProperty": "newValue" } -</programlisting> +]]></programlisting> <note> <para> The PUT method doesn't currently support adding or removing mixin types. This will be corrected in the future. @@ -229,32 +229,320 @@ </note> </para> </sect1> - <sect1 id="jcr_rest_spi"> - <title>Repository Providers</title> - <para> - One of the objects that must be supplied to many JBoss DNA components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). - </para> - </sect1> <sect1 id="dna_rest_server_configuration"> <title>Configuring the DNA REST Server</title> <para> - One of the objects that must be supplied to many JBoss DNA components is an &ExecutionContext;. Some components - require this context to be passed into individual methods, allowing the context to vary with each method invocation. - Other components require the context to be provided before it's used, and will use that context for all its operations - (until it is given a different one). + The DNA REST server is deployed as a WAR and configured mostly through its web configuration file (web.xml). + Here is an example web configuration that is used for integration testing of the DNA REST server along with + an explanation of its parts. +<programlisting role="xml"><![CDATA[ +<?xml version="1.0"?> +<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" + "http://java.sun.com/dtd/web-app_2_3.dtd"> +<web-app> + <display-name>JBoss DNA JCR RESTful Interface</display-name> +]]></programlisting> + This first section is largely boilerplate and should look familiar to anyone who has deployed a servlet-based + application before. The display-name can be customized, of course. </para> + <para> + The next stanza configures the <link linkend="jcr_rest_spi">repository provider</link>. +<programlisting role="xml"><![CDATA[ + <!-- + This parameter provides the fully-qualified name of a class that implements + the o.j.d.web.jcr.rest.spi.RepositoryProvider interface. It is required + by the DnaJcrDeployer that controls the lifecycle for the DNA REST server. + --> + <context-param> + <param-name>org.jboss.dna.web.jcr.rest.REPOSITORY_PROVIDER</param-name> + <param-value>org.jboss.dna.web.jcr.rest.spi.DnaJcrRepositoryProvider</param-value> + </context-param> +]]></programlisting> + As noted above, this parameter informs the &DnaJcrDeployer; of the specific repository provider in use. + Unless you are using the JBoss DNA REST server to connect to a different JCR implementation, this should + never change. + </para> + + <para> + Next we configure the DNA &JcrEngine; itself. +<programlisting role="xml"><![CDATA[ + <!-- + This parameter, specific to the DnaJcrRepositoryProvider implementation, specifies + the name of the configuration file to initialize the repository or repositories. + This configuration file must be on the classpath and is given as a classpath-relative + directory. + --> + <context-param> + <param-name>org.jboss.dna.web.jcr.rest.CONFIG_FILE</param-name> + <param-value>/configRepository.xml</param-value> + </context-param> +]]></programlisting> + If you are not familiar with the file format for a &JcrEngine; configuration file, you can build one + programatically with the &JcrConfiguration; class and call <code>save(...)</code> instead of <code>build()</code> + to output the configuration file that equates to the configuration. + </para> + + <para> + This is followed by a bit of RESTEasy and JAX-RS boilerplate. +<programlisting role="xml"><![CDATA[ + <!-- + This parameter defines the JAX-RS application class, which is really just a metadata class + that lets the JAX-RS engine (RESTEasy in this case) know which classes implement pieces + of the JAX-RS specification like exception handling and resource serving. + + This should not be modified. + --> + <context-param> + <param-name>javax.ws.rs.Application</param-name> + <param-value>org.jboss.dna.web.jcr.rest.JcrApplication</param-value> + </context-param> + + <!-- Required parameter for RESTEasy - should not be modified --> + <listener> + <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class> + </listener> + + <!-- Required parameter for JBoss DNA REST - should not be modified --> + <listener> + <listener-class>org.jboss.dna.web.jcr.rest.DnaJcrDeployer</listener-class> + </listener> + + <!-- Required parameter for RESTEasy - should not be modified --> + <servlet> + <servlet-name>Resteasy</servlet-name> + <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> + </servlet> + + <!-- Required parameter for JBoss DNA REST - should not be modified --> + <servlet-mapping> + <servlet-name>Resteasy</servlet-name> + <url-pattern>/*</url-pattern> + </servlet-mapping> + + +]]></programlisting> + In general, this part of the web configuration file should not be modified. + </para> + + <para> + Finally, security must be configured for the REST server. +<programlisting role="xml"><![CDATA[ + <!-- + The JBoss DNA REST implementation leverages the HTTP credentials to for authentication and authorization + within the JCR repository. It makes no sense to try to log into the JCR repository without credentials, + so this constraint helps lock down the repository. + + This should generally not be modified. + --> + <security-constraint> + <display-name>DNA REST</display-name> + <web-resource-collection> + <web-resource-name>RestEasy</web-resource-name> + <url-pattern>/*</url-pattern> + </web-resource-collection> + <auth-constraint> + <!-- + A user must be assigned this role to connect to any JCR repository, in addition to needing the READONLY + or READWRITE roles to actually read or modify the data. This is not used internally, so another + role could be substituted here. + --> + <role-name>connect</role-name> + </auth-constraint> + </security-constraint> + + <!-- + Any auth-method will work for JBoss DNA. BASIC is used this example for simplicity. + --> + <login-config> + <auth-method>BASIC</auth-method> + </login-config> + + <!-- + This must match the role-name in the auth-constraint above. + --> + <security-role> + <role-name>connect</role-name> + </security-role> +</web-app> + +]]></programlisting> + As noted above, the REST server will not function properly unless security is configured. All authorization + methods supported by the Servlet specification are supported by JBoss DNA and can be used interchangeable, as + long as authenticated users have the connect role listed above. + </para> + </sect1> <sect1 id="dna_rest_server_deployment"> <title>Deploying the DNA REST Server</title> <para> - One such implementation is the &JaasSecurityContext;, which delegates any authentication or authorization requests to a - <ulink url="http://java.sun.com/javase/technologies/security/">Java Authentication and Authorization Service (JAAS)</ulink> - provider. This is the standard approach for authenticating and authorizing in Java, and is the default mechanism - used by the &JcrEngine;. + Deploying the DNA REST server only requires three steps: <link linkend="dna_rest_server_configuration"> + preparing the web configuration</link>, configuring the users and their roles in your web container + (outside the scope of this document), and assembling the WAR. This section describes the requirements + for assembling the WAR. </para> + <para> + If you are using Maven to build your projects, the WAR can be built from a POM. Here is a portion of the + POM used to build the JBoss DNA REST Server integration subproject. +<programlisting role='xml'> <![CDATA[ +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> + <modelVersion>4.0.0</modelVersion> + <parent> + <artifactId>dna</artifactId> + <groupId>org.jboss.dna</groupId> + <version>0.5-SNAPSHOT</version> + <relativePath>../..</relativePath> + </parent> + <artifactId>dna-web-jcr-rest-war</artifactId> + <packaging>war</packaging> + <name>JBoss DNA JCR REST Servlet</name> + <description>JBoss DNA servlet that provides RESTful access to JCR items</description> + <url>http://labs.jboss.org/dna</url> + <dependencies> + <dependency> + <groupId>org.jboss.dna</groupId> + <artifactId>dna-web-jcr-rest</artifactId> + <version>${pom.version}</version> + </dependency> + + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-log4j12</artifactId> + <version>1.4.3</version> + <scope>runtime</scope> + </dependency> + + <dependency> + <groupId>org.jboss.resteasy</groupId> + <artifactId>resteasy-client</artifactId> + <version>1.0-beta-8</version> + </dependency> + </dependencies> +</project> + +]]></programlisting> + If you use this approach, make sure that web configuration file is in the <code>/src/main/webapp/WEB-INF</code> + directory. + </para> + <para> + The JBoss REST Server WAR is still easy enough to build if you are not using Maven. Simply construct a WAR with + the following contents: +<programlisting> ++ /WEB-INF + + /classes + | + configRepository.xml + | + log4j.properties (Optional) + + /lib + | + activation-1.1.jar + | + antlr-runtime-3.1.3.jar + | + commons-codec-1.2.jar + | + commons-httpclient-3.1.jar + | + commons-logging-1.0.4.jar + | + dna-cnd-0.5-SNAPSHOT.jar + | + dna-common-0.5-SNAPSHOT.jar + | + dna-connector-federation-0.5-SNAPSHOT.jar + | + dna-graph-0.5-SNAPSHOT.jar + | + dna-jcr-0.5-SNAPSHOT.jar + | + dna-repository-0.5-SNAPSHOT.jar + | + dna-web-jcr-rest-0.5-SNAPSHOT.jar + | + FastInfoset-1.2.2.jar + | + google-collect-snapshot-20080530.jar + | + hamcrest-core-1.1.jar + | + javassist-3.6.0.GA.jar + | + jaxb-api-2.1.jar + | + jaxb-impl-2.1.9.jar + | + jaxrs-api-1.1-RC2.jar + | + jcip-annotations-1.0.jar + | + jcr-1.0.1.jar + | + jettison-1.0.1.jar + | + joda-time-1.4.jar + | + jsr250-api-1.0.jar + | + junit-dep-4.4.jar + | + resteasy-client-1.0-beta-8.jar + | + resteasy-common-1.0-beta-8.jar + | + resteasy-jaxb-provider-1.1-RC2.jar + | + resteasy-jaxrs-1.1-RC2.jar + | + scannotation-1.0.2.jar + | + servlet-api-2.5.jar + | + sjsxp-1.0.1.jar + | + slf4j-api-1.4.3.jar + | + slf4j-log4j12-1.4.3.jar + | + slf4j-simple-1.5.2.jar + | + stax-api-1.0-2.jar + | + webserver-1.3.3.jar + + web.xml + +</programlisting> + If you are using sequencers or any connectors other than the in-memory or federated connector, you will also have + to add the JARs for those dependencies into the <code>WEB-INF/lib</code> directory as well. You will also have to + change the version numbers on the JARs to reflect the current version of JBoss DNA. + </para> + <para> + This WAR can be deployed into your servlet container. + </para> </sect1> + <sect1 id="jcr_rest_spi"> + <title>Repository Providers</title> + <para> + The JBoss DNA REST server can also be used as an interface to to other JCR repositories by creating + an implementation of the &RepositoryProvider; interface that connects to the other repository. + </para> + <para> + The &RepositoryProvider; only has a few methods that must be implemented. When the &DnaJcrDeployer; starts + up, it will dynamically load the &RepositoryProvider; implementation (as noted above) and call the <code> + startup(ServletContext)</code> method on the provider. The provider can use this method to load any + required configuration parameters from the web configuration (web.xml) and initialize the repository. + </para> + <para> + As an example, here's the DNA JCR provider implementation of this method with exception handling omitted for brevity. +<programlisting><![CDATA[ +public void startup( ServletContext context ) { + String configFile = context.getInitParameter(CONFIG_FILE); + + InputStream configFileInputStream = getClass().getResourceAsStream(configFile); + jcrEngine = new JcrConfiguration().loadFrom(configFileInputStream).build(); + jcrEngine.start(); + +} +]]></programlisting> + As you can see, the name of configuration file for the &JcrEngine; is read from the servlet context and used + to initialize the engine. + Once the repository has been started, it is now ready to accept the main methods that provide the interface + to the repository. + </para> + <para> + The first method returns the set of repository names supported by this REST server. +<programlisting><![CDATA[ +public Set<String> getJcrRepositoryNames() { + return new HashSet<String>(jcrEngine.getRepositoryNames()); +} +]]></programlisting> + The JBoss DNA JCR repository does support multiple repositories on the same server. Other JCR implementations + that don't support multiple repositories are free to return a singleton set containing any string from this method. + </para> + <para> + The other required method returns an open JCR &Session; for the user from the current request in a given repository + and workspace. The provider can use the &HttpServletRequest; to get the authentication credentials for the + HTTP user. +<programlisting><![CDATA[ +public Session getSession( HttpServletRequest request, + String repositoryName, + String workspaceName ) throws RepositoryException { + Repository repository = getRepository(repositoryName); + + SecurityContext context = new ServletSecurityContext(request); + Credentials credentials = new SecurityContextCredentials(context); + return repository.login(credentials, workspaceName); + +} +]]></programlisting> + The <code>getSession(...)</code> method is used by most of the REST server methods to access the JCR + repository and return results as needed. + </para> + <para> + Finally, the <code>shutdown()</code> method signals that the web context is being undeployed and the JCR + repository should shutdown and clean up any resources that are in use. + </para> + </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/custom.dtd =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-09 16:36:50 UTC (rev 1013) +++ trunk/docs/reference/src/main/docbook/en-US/custom.dtd 2009-06-09 16:45:30 UTC (rev 1014) @@ -185,4 +185,6 @@ <!ENTITY ImageMetadata "<ulink url='&API;sequencer/image/ImageMetadata.html'><classname>ImageMetadata</classname></ulink>"> <!ENTITY ImageSequencerI18n "<ulink url='&API;sequencer/image/ImageSequencerI18n.html'><classname>ImageSequencerI18n</classname></ulink>"> <!ENTITY ApertureMimeTypeDetector "<ulink url='&API;mimetype/aperture/ApertureMimeTypeDetector.html'><classname>ApertureMimeTypeDetector</classname></ulink>"> +<!ENTITY DnaJcrDeployer "<ulink url='&API;web/jcr/rest/DnaJcrDeployer.html'><classname>DnaJcrDeployer</classname></ulink>"> +<!ENTITY RepositoryProvider "<ulink url='&API;web/jcr/rest/spi/RepositoryProvider.html'><classname>RepositoryProvider</classname></ulink>"> Modified: trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrApplication.java =================================================================== --- trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrApplication.java 2009-06-09 16:36:50 UTC (rev 1013) +++ trunk/extensions/dna-web-jcr-rest/src/main/java/org/jboss/dna/web/jcr/rest/JcrApplication.java 2009-06-09 16:45:30 UTC (rev 1014) @@ -23,7 +23,8 @@ */ package org.jboss.dna.web.jcr.rest; -import java.util.Collections; +import java.util.Arrays; +import java.util.HashSet; import java.util.Set; import javax.ws.rs.core.Application; @@ -41,7 +42,12 @@ */ @Override public Set<Class<?>> getClasses() { - return Collections.<Class<?>>singleton(JcrResources.class); + return new HashSet<Class<?>>(Arrays.asList(new Class<?>[] { + JcrResources.class, + JcrResources.JSONExceptionMapper.class, + JcrResources.NotFoundExceptionMapper.class, + JcrResources.RepositoryExceptionMapper.class, + })); } } Modified: trunk/extensions/dna-web-jcr-rest-war/src/main/webapp/WEB-INF/web.xml =================================================================== --- trunk/extensions/dna-web-jcr-rest-war/src/main/webapp/WEB-INF/web.xml 2009-06-09 16:36:50 UTC (rev 1013) +++ trunk/extensions/dna-web-jcr-rest-war/src/main/webapp/WEB-INF/web.xml 2009-06-09 16:45:30 UTC (rev 1014) @@ -22,46 +22,68 @@ <web-app> <display-name>JBoss DNA JCR RESTful Interface</display-name> + <!-- + This parameter provides the fully-qualified name of a class that implements + the o.j.d.web.jcr.rest.spi.RepositoryProvider interface. It is required + by the DnaJcrDeployer that controls the lifecycle for the DNA REST server. + --> <context-param> <param-name>org.jboss.dna.web.jcr.rest.REPOSITORY_PROVIDER</param-name> <param-value>org.jboss.dna.web.jcr.rest.spi.DnaJcrRepositoryProvider</param-value> </context-param> + <!-- + This parameter, specific to the DnaJcrRepositoryProvider implementation, specifies + the name of the configuration file to initialize the repository or repositories. + This configuration file must be on the classpath and is given as a classpath-relative + directory. + --> <context-param> <param-name>org.jboss.dna.web.jcr.rest.CONFIG_FILE</param-name> <param-value>/configRepository.xml</param-value> </context-param> + <!-- + This parameter defines the JAX-RS application class, which is really just a metadata class + that lets the JAX-RS engine (RESTEasy in this case) know which classes implement pieces + of the JAX-RS specification like exception handling and resource serving. + + This should not be modified. + --> <context-param> - <param-name>resteasy.providers</param-name> - <param-value>org.jboss.dna.web.jcr.rest.JcrResources$NotFoundExceptionMapper, - org.jboss.dna.web.jcr.rest.JcrResources$JSONExceptionMapper, - org.jboss.dna.web.jcr.rest.JcrResources$RepositoryExceptionMapper</param-value> - </context-param> - - <context-param> <param-name>javax.ws.rs.Application</param-name> <param-value>org.jboss.dna.web.jcr.rest.JcrApplication</param-value> </context-param> + <!-- Required parameter for RESTEasy - should not be modified --> <listener> <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class> </listener> + <!-- Required parameter for JBoss DNA REST - should not be modified --> <listener> <listener-class>org.jboss.dna.web.jcr.rest.DnaJcrDeployer</listener-class> </listener> + <!-- Required parameter for RESTEasy - should not be modified --> <servlet> <servlet-name>Resteasy</servlet-name> <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class> </servlet> + <!-- Required parameter for JBoss DNA REST - should not be modified --> <servlet-mapping> <servlet-name>Resteasy</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> + <!-- + The JBoss DNA REST implementation leverages the HTTP credentials to for authentication and authorization + within the JCR repository. It makes no sense to try to log into the JCR repository without credentials, + so this constraint helps lock down the repository. + + This should generally not be modified. + --> <security-constraint> <display-name>DNA REST</display-name> <web-resource-collection> @@ -69,14 +91,25 @@ <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> + <!-- + A user must be assigned this role to connect to any JCR repository, in addition to needing the READONLY + or READWRITE roles to actually read or modify the data. This is not used internally, so another + role could be substituted here. + --> <role-name>connect</role-name> </auth-constraint> </security-constraint> + <!-- + Any auth-method will work for JBoss DNA. BASIC is used this example for simplicity. + --> <login-config> <auth-method>BASIC</auth-method> </login-config> + <!-- + This must match the role-name in the auth-constraint above. + --> <security-role> <role-name>connect</role-name> </security-role>