Author: bcarothers Date: 2009-06-09 07:17:52 -0400 (Tue, 09 Jun 2009) New Revision: 1008 Modified: trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml Log: Final draft of the JCR 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 10:49:08 UTC (rev 1007) +++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/jcr.xml 2009-06-09 11:17:52 UTC (rev 1008) @@ -37,14 +37,33 @@ Java Community Process under <ulink url="&JSR170;">JSR-170</ulink> (JCR 1.0) and is being revised under <ulink url="&JSR283;">JSR-283</ulink>. 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 + 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> + </note> </para> - <sect1 id="jcr-repositories"> - <title>Obtaining JCR repositories</title> - <para>Add reference to how to use JcrConfiguration to obtain a JcrEngine. + <para>Using JBoss DNA within your application is actually quite straightforward. As you'll see in this chapter, + the first step is setting up JBoss DNA and starting the <code>JcrEngine</code>. After that, you obtain the + <code>javax.jcr.Repository</code> instance for a named repository and just use the standard JCR API throughout your + application. + </para> + <sect1> + <title>Obtaining JCR Repositories</title> + <para>Once you've obtained a reference to a <code>JcrEngine</code> as described in + <link linkend="configuration">the previous chapter</link>, obtaining a repository is as easy as calling + the <code>getRepository(String)</code> method with the name of the repository that you just configured. +<programlisting> +&String; repositoryName = ...; +&JcrEngine; jcrEngine = ...; +&Repository; repository = jcrEngine.getRepository(repositoryName); +</programlisting> + At this point, your application can proceed by working with the JCR API. </para> </sect1> <sect1 id="jcr-sessions"> - <title>Creating JCR sessions</title> + <title>Creating JCR Sessions</title> <para>Once you have obtained a reference to the JCR &Repository;, you can create a JCR session using one of its <code>login(...)</code> methods. The <ulink url="&JSR170;">JSR-170</ulink> specification provides four login methods. </para> @@ -57,7 +76,8 @@ &Session; session = (&Session;) Subject.doAsPrivileged(subject, new PrivilegedExceptionAction&lt;&Session;&gt;() { public Session run() throws Exception { return repository.login(); - }}, AccessController.getContext()); + } +}, AccessController.getContext()); </programlisting> This approach will yield a session with the same user name and roles as <code>subject</code>. There is a comparable version of <code>login(...)</code> that allows the workspace to be specified by name. @@ -104,7 +124,7 @@ &ServletSecurityContext; securityContext = new ServletSecurityContext(request); &Session; session = repository.login(new &SecurityContextCredentials;(securityContext); </programlisting> - Once the &Session; is obtained, the repository content can be access and modified like any other JCR repository. No roles are required to connect + Once the &Session; is obtained, the repository content can be accessed and modified like any other JCR repository. No roles are required to connect to any workspace at this time. Restrictions on workspace connections will likely be added to JBoss DNA in the near future. The roles from the JAAS information or the &HttpServletRequest; are used to control read and write access to the repository. Please see the <ulink linkend="dna_jcr_security">JCR Security section</ulink> for more details on how access is controlled. @@ -168,7 +188,14 @@ </sect2> <sect2> <title>Built-In Node Types</title> - <para>Add description of the DNA built-in node types.</para> + <para>JBoss DNA supports all of the built-in node types described in the JSR-170 specification. However, several of these node types + (mix:lockable, mix:versionable, nt:version, nt:versionLabels, nt:versionHistory, and nt:frozenNode) are semantically meaningless + as JBoss DNA does not yet support the locking or versioning optional features. + </para> + <para>Although JBoss DNA does define some custom node types in the <code>dna</code> namespace, none of these + node types are intended to be used by developers integrating with JBoss DNA and may be changed or removed + at any time. + </para> </sect2> <sect2> <title>Custom Node Type Registration</title> @@ -244,7 +271,7 @@ nodeTypeManager.registerNodeTypes(nodeTypeSource); </programlisting> <note> - <para> JBoss DNA does not yet support a simple means on unregistering types at this time, so be careful before registering types outside of a + <para> JBoss DNA does not yet support a simple means of unregistering types at this time, so be careful before registering types outside of a sandboxed environment. </para> </note> @@ -257,7 +284,7 @@ <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="sequencing">next chapter</link> to describing in detail how the sequencing of file content works. + the <link linkend="deploying_dna_jcr">next chapter</link> to describing in detail how the sequencing of file content works. </para> </sect1> </chapter>