[dna-commits] DNA SVN: r1018 - in trunk/docs/reference/src/main/docbook/en-US: content/jcr and 1 other directory.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Tue Jun 9 15:46:45 EDT 2009
Author: rhauch
Date: 2009-06-09 15:46:45 -0400 (Tue, 09 Jun 2009)
New Revision: 1018
Added:
trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml
Modified:
trunk/docs/reference/src/main/docbook/en-US/master.xml
Log:
Moved the chapter on configuring the JCR engine into the part of the Reference Guide that talks about JCR.
Added: trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml (rev 0)
+++ trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml 2009-06-09 19:46:45 UTC (rev 1018)
@@ -0,0 +1,376 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss DNA (http://www.jboss.org/dna)
+ ~
+ ~ See the COPYRIGHT.txt file distributed with this work for information
+ ~ regarding copyright ownership. Some portions may be licensed
+ ~ to Red Hat, Inc. under one or more contributor license agreements.
+ ~ See the AUTHORS.txt file in the distribution for a full listing of
+ ~ individual contributors.
+ ~
+ ~ JBoss DNA is free software. Unless otherwise indicated, all code in JBoss DNA
+ ~ is licensed to you under the terms of the GNU Lesser General Public License as
+ ~ published by the Free Software Foundation; either version 2.1 of
+ ~ the License, or (at your option) any later version.
+ ~
+ ~ JBoss DNA is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
+ -->
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
+%CustomDTD;
+]>
+<chapter id="configuration">
+ <title>Configuring and Using JBoss DNA</title>
+ <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 id="jcr_engine">
+ <title>JBoss DNA's JcrEngine</title>
+ <para>
+ JBoss DNA encapsulates everything necessary to run one or more JCR repositories into a single &JcrEngine; instance.
+ This includes all underlying repository sources, the pools of connections to the sources, the sequencers,
+ the MIME type detector(s), and the &Repository; implementations.
+ </para>
+ <para>
+ Obtaining a &JcrEngine; instance is very easy - assuming that you have a valid &JcrConfiguration; instance. We'll see
+ how to get one of those in a little bit, but if you have one then all you have to do is build and start the engine:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+JcrEngine engine = config.build();
+engine.start();
+ ]]></programlisting>
+ <para>
+ Obtaining a JCR &Repository; instance is a matter of simply asking the engine for it by the name defined in the configuration:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+javax.jcr.Repository repository = engine.getRepository("Name of repository");
+ ]]></programlisting>
+ <para>
+ At this point, your application can proceed by working with the JCR API.
+ </para>
+ <para>
+ And, once you're finished with the &JcrEngine;, you should shut it down:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+engine.shutdown();
+engine.awaitTermination(3,TimeUnit.SECONDS); // optional
+ ]]></programlisting>
+ <para>
+ When the <code>shutdown()</code> method is called, the &Repository; instances managed by the engine are marked as being shut down,
+ and they will not be able to create new &Session;s. However, any existing &Session;s or ongoing operations (e.g., event notifications)
+ present at the time of the <code>shutdown()</code> call will be allowed to finish.
+ In essence, <code>shutdown()</code> is a <emphasis>graceful</emphasis> request, and since it may take some time to complete,
+ you can wait until the shutdown has completed by simply calling <code>awaitTermination(...)</code> as shown above.
+ This method will block until the engine has indeed shutdown or until the supplied time duration has passed (whichever comes first).
+ And, yes, you can call the <code>awaitTermination(...)</code> method repeatedly if needed.
+ </para>
+ </sect1>
+ <sect1 id="jcr_configuration">
+ <title>JcrConfiguration</title>
+ <para>
+ The previous section assumed the existence of a &JcrConfiguration;. It's not really that creating an instance is all that difficult.
+ In fact, there's only one no-argument constructor, so actually creating the instance is a piece of cake. What can be a little more challenging,
+ though, is setting up the &JcrConfiguration; instance, which must define the following components:
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="strong"><code>Repository sources</code></emphasis> are the POJO objects that each describe a particular
+ location where content is stored. Each repository source object is an instance of a JBoss DNA connector, and is configured
+ with the properties that particular source. JBoss DNA's &RepositorySource; classes are analogous to JDBC's &DataSource; classes -
+ they are implemented by specific connectors (aka, "drivers") for specific kinds of repository sources (aka, "databases").
+ Similarly, a &RepositorySource; instance is analogous to a &DataSource; instance, with bean properties for each configurable
+ parameter. Therefore, each repository source definition must supply the name of the &RepositorySource; class, any
+ bean properties, and, optionally, the classpath that should be used to load the class. </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>Repositories</code></emphasis> define the JCR repositories that are available. Each
+ repository has a unique name that is used to obtain the &Repository; instance from the &JcrEngine;'s <code>getRepository(String)</code>
+ method, but each repository definition also can include the predefined namespaces (other than those automatically defined by
+ JBoss DNA), various options, and the node types that are to be available in the repository without explicit registration
+ through the JCR API.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>Sequencers</code></emphasis> define the particular sequencers that are available for use.
+ Each sequencer definition provides the path expressions governing which nodes in the repository should be sequenced when those nodes change,
+ and where the resulting output generated by the sequencer should be placed. The definition also must state the name of
+ the sequencer class, any bean properties and, optionally, the classpath that should be used to load the class.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>MIME type detectors</code></emphasis> define the particular MIME type detector(s) that should
+ be made available. A MIME type detector does exactly what the name implies: it attempts to determine the MIME type given a
+ "filename" and contents. JBoss DNA automatically uses a detector that uses the file extension to identify the MIME type,
+ but also provides an implementation that uses an external library to identify the MIME type based upon the contents.
+ The definition must state the name of the detector class, any bean properties and, optionally, the classpath that should
+ be used to load the class.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ There really are three options:
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="strong"><code>Load from a file</code></emphasis> is conceptually the easiest and requires the least amount
+ of Java code, but it now requires a configuration file.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>Load from a configuration repository</code></emphasis> is not much more complicated than loading
+ from a file, but it does allow multiple &JcrEngine; instances (usually in different processes perhaps on different machines)
+ to easily access their (shared) configuration. And technically, loading the configuration from a file really just creates an
+ &InMemoryRepositorySource;, imports the configuration file into that source, and then proceeds with this approach.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>Programmatic configuration</code></emphasis> is always possible, even if the configuration is loaded
+ from a file or repository. Using the &JcrConfiguration;'s API, you can define (or update or remove) all of the definitions that make
+ up a configuration.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Each of these approaches has their obvious advantages, so the choice of which one to use is entirely up to you.
+ </para>
+ <sect2 id="loading_from_file">
+ <title>Loading from a configuration file</title>
+ <para>
+ Loading the JBoss DNA configuration from a file is actually very simple:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = new JcrConfiguration();
+configuration.loadFrom(file);
+ ]]></programlisting>
+ <para>
+ where the <code>file</code> parameter can actually be a &File; instance, a &URL; to the file, an &InputStream;
+ containing the contents of the file, or even a &String; containing the contents of the file.
+ </para>
+ <note>
+ <para>The <code>loadFrom(...)</code> method can be called any number of times, but each time it is called it completely wipes
+ out any current notion of the configuration and replaces it with the configuration found in the file.
+ </para>
+ </note>
+ <para>
+ There is an optional second parameter that defines the &Path; within the configuration file identifying the parent node of the various
+ configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be
+ located at a different location in the hierarchical structure. (This is not often required, but when it is required
+ this second parameter is very useful.)
+ </para>
+ <para>
+ Here is the configuration file that is used in the repository example, though it has been simplified a bit and most comments
+ have been removed for clarity):
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration xmlns="http://www.jboss.org/dna/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
+ <!--
+ Define the JCR repositories
+ -->
+ <dna:repositories>
+ <!--
+ Define a JCR repository that accesses the 'Cars' source directly.
+ This of course is optional, since we could access the same content through 'vehicles'.
+ -->
+ <dna:repository jcr:name="car repository" dna:source="Cars">
+ <options jcr:primaryType="dna:options"/>
+ <jaasLoginConfigName jcr:primaryType="dna:option" dna:value="dna-jcr"/>
+ </options>
+ </dna:repository>
+ </dna:repositories>
+ <!--
+ Define the sources for the content. These sources are directly accessible using the DNA-specific Graph API.
+ -->
+ <dna:sources jcr:primaryType="nt:unstructured">
+ <dna:source jcr:name="Cars"
+ dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource"
+ dna:retryLimit="3" dna:defaultWorkspaceName="workspace1"/>
+ <dna:source jcr:name="Aircraft"
+ dna:classname="org.jboss.dna.graph.connector.inmemory.InMemoryRepositorySource">
+ <!-- Define the name of the workspace used by default. Optional, but convenient. -->
+ <defaultWorkspaceName>workspace2</defaultWorkspaceName>
+ </dna:source>
+ </dna:sources>
+ <!--
+ Define the sequencers. This is an optional section. For this example, we're not using any sequencers.
+ -->
+ <dna:sequencers>
+ <!--dna:sequencer jcr:name="Image Sequencer">
+ <dna:classname>org.jboss.dna.sequencer.image.ImageMetadataSequencer</dna:classname>
+ <dna:description>Image metadata sequencer</dna:description>
+ <dna:pathExpression>/foo/source => /foo/target</dna:pathExpression>
+ <dna:pathExpression>/bar/source => /bar/target</dna:pathExpression>
+ </dna:sequencer-->
+ </dna:sequencers>
+ <dna:mimeTypeDetectors>
+ <dna:mimeTypeDetector jcr:name="Detector"
+ dna:description="Standard extension-based MIME type detector"/>
+ </dna:mimeTypeDetectors>
+</configuration>
+ ]]></programlisting>
+ </sect2>
+ <sect2 id="loading_from_repository">
+ <title>Loading from a configuration repository</title>
+ <para>
+ Loading the JBoss DNA configuration from an existing repository is also pretty straightforward. Simply create and configure the
+ &RepositorySource; instance to point to the desired repository, and then call the <code>loadFrom(&RepositorySource; source)</code>
+ method:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+RepositorySource configSource = ...
+JcrConfiguration config = new JcrConfiguration();
+configuration.loadFrom(configSource);
+ ]]></programlisting>
+ <para>
+ This really is a more advanced way to define your configuration, so we won't go into how you configure a &RepositorySource;.
+ For more information, consult the &ReferenceGuide;.
+ </para>
+ <note>
+ <para>The <code>loadFrom(...)</code> method can be called any number of times, but each time it is called it completely wipes
+ out any current notion of the configuration and replaces it with the configuration found in the file.
+ </para>
+ </note>
+ <para>
+ There is an optional second parameter that defines the name of the workspace in the supplied source where the configuration content
+ can be found. It is not needed if the workspace is the source's default workspace.
+ There is an optional third parameter that defines the &Path; within the configuration repository identifying the parent node of the various
+ configuration nodes. If not specified, it assumes "/". This makes it possible for the configuration content to be
+ located at a different location in the hierarchical structure. (This is not often required, but when it is required
+ this second parameter is very useful.)
+ </para>
+ </sect2>
+ <sect2 id="programmatic_configuration">
+ <title>Programmatic configuration</title>
+ <para>
+ Defining the configuration programmatically is not terribly complicated, and it for obvious reasons results in more verbose Java code.
+ But this approach is very useful and often the easiest approach when the configuration must change or is a reflection of other
+ dynamic information.
+ </para>
+ <para>
+ The &JcrConfiguration; class was designed to have an easy-to-use API that makes it easy to configure each of the different kinds of
+ components, especially when using an IDE with code completion. Here are several examples:
+ </para>
+ <sect3 id="programmatically_configuring_sources">
+ <title>Repository sources</title>
+ <para>Each repository source definition must include the name of the &RepositorySource; class as well as each bean property
+ that should be set on the object:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+config.repositorySource("source A")
+ .usingClass(InMemoryRepositorySource.class)
+ .setDescription("The repository for our content")
+ .setProperty("defaultWorkspaceName", workspaceName);
+ ]]></programlisting>
+ <para>
+ This example defines an in-memory source with the name "source A", a description, and a single "defaultWorkspaceName" bean property.
+ Different &RepositorySource; implementations will the bean properties that are required and optional.
+ Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
+ the classpath or from a specific classpath).
+ </para>
+ <note>
+ <para>Each time <code>repositorySource(String)</code> is called, it will either load the existing definition with the supplied
+ name or will create a new definition if one does not already exist. To remove a definition, simply call <code>remove()</code>
+ on the result of <code>repositorySource(String)</code>.
+ The set of existing definitions can be accessed with the <code>repositorySources()</code> method.
+ </para>
+ </note>
+ </sect3>
+ <sect3 id="programmatically_configuring_repositories">
+ <title>Repositories</title>
+ <para>Each repository must be defined to use a named repository source, but all other aspects (e.g., namespaces, node types, options)
+ are optional.</para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+config.repository("repository A")
+ .addNodeTypes("myCustomNodeTypes.cnd")
+ .setSource("source 1")
+ .registerNamespace("acme","http://www.example.com/acme")
+ .setOption(JcrRepository.Option.JAAS_LOGIN_CONFIG_NAME, "dna-jcr");
+ ]]></programlisting>
+ <para>
+ This example defines a repository that uses the "source 1" repository source (which could be a federated source, an in-memory source,
+ a database store, or any other source). Additionally, this example adds the node types in the "myCustomNodeTypes.cnd" file as those
+ that will be made available when the repository is accessed. It also defines the "http://www.example.com/acme" namespace,
+ and finally sets the "JAAS_LOGIN_CONFIG_NAME" option to define the name of the JAAS login configuration that should be used by
+ the JBoss DNA repository.
+ </para>
+ <note>
+ <para>Each time <code>repository(String)</code> is called, it will either load the existing definition with the supplied
+ name or will create a new definition if one does not already exist. To remove a definition, simply call <code>remove()</code>
+ on the result of <code>repository(String)</code>.
+ The set of existing definitions can be accessed with the <code>repositories()</code> method.
+ </para>
+ </note>
+ </sect3>
+ <sect3 id="programmatically_configuring_sequencers">
+ <title>Sequencers</title>
+ <para>Each defined sequencer must specify the name of the &StreamSequencer; implementation class as well as the path expressions
+ defining which nodes should be sequenced and the output paths defining where the sequencer output should be placed (often as a function
+ of the input path expression).</para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+config.sequencer("Image Sequencer")
+ .usingClass("org.jboss.dna.sequencer.image.ImageMetadataSequencer")
+ .loadedFromClasspath()
+ .setDescription("Sequences image files to extract the characteristics of the image")
+ .sequencingFrom("//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd)[*])/jcr:content[@jcr:data]")
+ .andOutputtingTo("/images/$1");
+ ]]></programlisting>
+ <para>
+ This shows an example of a sequencer definition named "Image Sequencer" that uses the &ImageMetadataSequencer; class
+ (loaded from the classpath), that is to sequence the "jcr:data" property on any new or changed nodes that are named
+ "jcr:content" below a parent node with a name ending in ".jpg", ".jpeg", ".gif", ".bmp", ".pcx", ".iff", ".ras",
+ ".pbm", ".pgm", ".ppm" or ".psd". The output of the sequencing operation should be placed at the "/images/$1" node,
+ where the "$1" value is captured as the name of the parent node. (The capture groups work the same was as regular expressions;
+ see the &ReferenceGuide; for more details.)
+ Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
+ the classpath or from a specific classpath).
+ </para>
+ <note>
+ <para>Each time <code>sequencer(String)</code> is called, it will either load the existing definition with the supplied
+ name or will create a new definition if one does not already exist. To remove a definition, simply call <code>remove()</code>
+ on the result of <code>sequencer(String)</code>.
+ The set of existing definitions can be accessed with the <code>sequencers()</code> method.
+ </para>
+ </note>
+ </sect3>
+ <sect3 id="programmatically_configuring_mime_type_detectors">
+ <title>MIME type detectors</title>
+ <para>Each defined MIME type detector must specify the name of the &MimeTypeDetector; implementation class as well as any
+ other bean properties required by the implementation.</para>
+ <programlisting role="JAVA"><![CDATA[
+JcrConfiguration config = ...
+config.mimeTypeDetector("Extension Detector")
+ .usingClass(org.jboss.dna.graph.mimetype.ExtensionBasedMimeTypeDetector.class);
+ ]]></programlisting>
+ <para>
+ Of course, the class can be specified as Class reference or a string (followed by whether the class should be loaded from
+ the classpath or from a specific classpath).
+ </para>
+ <note>
+ <para>Each time <code>mimeTypeDetector(String)</code> is called, it will either load the existing definition with the supplied
+ name or will create a new definition if one does not already exist. To remove a definition, simply call <code>remove()</code>
+ on the result of <code>mimeTypeDetector(String)</code>.
+ The set of existing definitions can be accessed with the <code>mimeTypeDetectors()</code> method.
+ </para>
+ </note>
+ </sect3>
+ </sect2>
+ </sect1>
+ <sect1 id="using_dna_whats_next">
+ <title>What's next</title>
+ <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.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/reference/src/main/docbook/en-US/content/jcr/configuration.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Modified: trunk/docs/reference/src/main/docbook/en-US/master.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-09 19:46:34 UTC (rev 1017)
+++ trunk/docs/reference/src/main/docbook/en-US/master.xml 2009-06-09 19:46:45 UTC (rev 1018)
@@ -85,7 +85,6 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/graph.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/connector.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/core/sequencing.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/jcr/configuration.xml"/>
</part>
<part id="jcr-part">
<title>JBoss DNA JCR</title>
@@ -97,6 +96,7 @@
</para>
</partintro>
<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>
More information about the dna-commits
mailing list