Author: rhauch Date: 2009-06-09 16:12:01 -0400 (Tue, 09 Jun 2009) New Revision: 1020 Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml trunk/docs/reference/src/main/docbook/en-US/master.xml Log: Minor edits and changes to the Reference Guide. Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2009-06-09 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/connector.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -637,9 +637,9 @@ In this chapter, we covered all the aspects of JBoss DNA connectors, including the connector API, how DNA's JCR implementation works with connectors, what connectors are available (and how to use them), and how to write your own connector. So now that you know how to set up and use JBoss DNA repositories, - the <link linkend="sequencing-framework">next chapter</link> describes the sequencing framework and how - to build your own custom sequencers. After that, we'll get into <link linkend="configuration">how to configure - JBoss DNA</link> to use the connectors and sequencers. + the <link linkend="sequencing_framework">next chapter</link> describes the sequencing framework and how + to build your own custom sequencers. After that, we'll get into <link linkend="jcr-part">how to configure + JBoss DNA and use JCR</link>. </para> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml 2009-06-09 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/content/core/sequencing.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -521,7 +521,7 @@ In this chapter, we described how JBoss DNA sequences files as they're uploaded into a repository. We've also learned in previous chapters about the JBoss DNA <link linkend="execution-context">execution contexts</link>, <link linkend="graph-model">graph model</link>, and <link linkend="connector-framework">connectors</link>. - In the <link linkend="jcr">next part</link> we'll put all these pieces together to learn how + In the <link linkend="jcr-part">next part</link> we'll put all these pieces together to learn how to set up a JBoss DNA repository and access it using the JCR API. </para> </sect1> Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2009-06-09 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -369,8 +369,7 @@ <para> This chapter outline how you configure JBoss DNA, how you then access a <code>javax.jcr.Repository</code> instance, and use the standard JCR API to interact with the repository. The - <link linkend="downloading_and_running">next chapter </link> walks you through downloading - and running the JBoss DNA examples. + <link linkend="jcr">next chapter</link> talks about using the JCR API with your JBoss DNA repository. </para> </sect1> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2009-06-09 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -29,7 +29,7 @@ %CustomDTD; ]> <chapter id="jcr"> - <title>The JBoss DNA Content Repository for Java (JCR) Implementation</title> + <title>Using the JCR API with JBoss DNA</title> <para> The <ulink url="&JSR170;">Content Repository for Java technology API</ulink> @@ -38,7 +38,7 @@ JBoss DNA provides a partial JCR 1.0 implementation that allows you to work with the contents of a repository using the JCR API. For information about how to use the JCR API, please see the <ulink url="&JSR170;">JSR-170</ulink> specification. <note> - <para>In the interests of brevity, this chapter does not attempt to reproduce the JSR-170 specification in order to provide + <para>In the interests of brevity, this chapter does not attempt to reproduce the JSR-170 specification nor provide an exhaustive definition of JBoss DNA JCR capabilities. Rather, this chapter will describe any deviations from the specification as well as any DNA-specific public APIs and configuration. </para> @@ -282,9 +282,10 @@ <sect1> <title>Summary</title> <para> - In this chapter, we covered how to use JCR with JBoss DNA and learned about how it implements the JCR specification. Now that you know how JBoss DNA repositories work, - and how to use JCR to work with DNA repositories, we'll move on in - the <link linkend="deploying_dna_jcr">next chapter</link> to describing in detail how the sequencing of file content works. + In this chapter, we covered how to use JCR with JBoss DNA and learned about how it implements the JCR specification. + Now that you know how JBoss DNA repositories work and how to use JCR to work with DNA repositories, we'll move on in + the <link linkend="rest_service">next chapter</link> to show how you can use the RESTful web service to + provide access to the content in a JCR repository to clients. </para> </sect1> </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 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/rest_service.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -29,10 +29,10 @@ %CustomDTD; ]> <chapter id="rest_service"> - <title>The JBoss DNA REST Server</title> + <title>The JBoss DNA RESTful Web Service</title> <para> - JBoss DNA now provides a RESTful interface to its JCR implementation that allows HTTP-based publishing - and unpublishing of content. Although the initial version of this REST server only supports the JBoss DNA + JBoss DNA now provides a RESTful interface to its JCR implementation that allows HTTP-based + access and updating of content. Although the initial version of this REST server only supports the JBoss DNA JCR implementation, it has been designed to make integration with other JCR implementors easy. This chapter describes how to configure and deploy the REST server. </para> @@ -240,7 +240,7 @@ <!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> + <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. @@ -248,15 +248,15 @@ <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> + <!-- + 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 @@ -266,16 +266,16 @@ <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> + <!-- + 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> @@ -285,41 +285,40 @@ <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 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> + 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 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 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 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> + <!-- 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> @@ -327,42 +326,42 @@ <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. + <!-- + 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> + 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> + 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> + <!-- + 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> + <!-- + This must match the role-name in the auth-constraint above. + --> + <security-role> + <role-name>connect</role-name> + </security-role> </web-app> ]]></programlisting> @@ -384,8 +383,9 @@ 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"> +<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> @@ -502,7 +502,6 @@ 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 @@ -533,7 +532,6 @@ 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 Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-09 20:08:03 UTC (rev 1019) +++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-09 20:12:01 UTC (rev 1020) @@ -93,10 +93,12 @@ The JBoss DNA project provides an implementation of the <ulink url="&JSR170;">JCR API</ulink>, which is built on top of the <link linkend="core-part">core libraries</link> discussed earlier. This implementation as well as a number of JCR-related components are described in this part of the document. + But before talking about how to use the JCR API with a JBoss DNA repository, first we need to + show how to set up a JBoss DNA engine. </para> </partintro> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/configuration.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/jcr.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/configuration.xml"/> <!-- xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/deploying_dna_jcr.xml"/ --> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/rest_service.xml"/> </part>