[dna-commits] DNA SVN: r989 - in trunk/docs: examples/gettingstarted/sequencers/src/main/java/org/jboss/example/dna/sequencer and 3 other directories.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Sun Jun 7 18:33:47 EDT 2009
Author: rhauch
Date: 2009-06-07 18:33:45 -0400 (Sun, 07 Jun 2009)
New Revision: 989
Added:
trunk/docs/gettingstarted/src/main/docbook/en-US/content/conclusion.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd
Removed:
trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml
Modified:
trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/ConsoleInput.java
trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java
trunk/docs/examples/gettingstarted/sequencers/src/main/java/org/jboss/example/dna/sequencer/SequencingClient.java
trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml
trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml
Log:
DNA-389 Updated the Getting Started document to reflect the new configuration approach, and restructured the document to better focus on the examples and high-level introduction, leaving the more detailed discussions for the Reference Guide (and removing more of the duplication).
Modified: trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/ConsoleInput.java
===================================================================
--- trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/ConsoleInput.java 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/ConsoleInput.java 2009-06-07 22:33:45 UTC (rev 989)
@@ -125,14 +125,13 @@
try {
// Terminate ...
System.out.println();
- System.out.print("done.\nShutting down repositories and services ... ");
+ System.out.print("done.\nShutting down repositories ... ");
client.shutdown();
System.out.print("done.");
System.out.println();
System.out.println();
} catch (Exception err) {
- System.out.println("Error shutting down sequencing service and repository: "
- + err.getLocalizedMessage());
+ System.out.println("Error shutting down repository: " + err.getLocalizedMessage());
err.printStackTrace(System.err);
}
}
Modified: trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java
===================================================================
--- trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/examples/gettingstarted/repositories/src/main/java/org/jboss/example/dna/repository/RepositoryClient.java 2009-06-07 22:33:45 UTC (rev 989)
@@ -202,7 +202,7 @@
if (loginContext == null) {
if (jaasContextName != null) {
loginContext = new LoginContext(jaasContextName, this.userInterface.getCallbackHandler());
- loginContext.login();
+ loginContext.login(); // This authenticates the user
}
}
return loginContext;
Modified: trunk/docs/examples/gettingstarted/sequencers/src/main/java/org/jboss/example/dna/sequencer/SequencingClient.java
===================================================================
--- trunk/docs/examples/gettingstarted/sequencers/src/main/java/org/jboss/example/dna/sequencer/SequencingClient.java 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/examples/gettingstarted/sequencers/src/main/java/org/jboss/example/dna/sequencer/SequencingClient.java 2009-06-07 22:33:45 UTC (rev 989)
@@ -68,7 +68,7 @@
throw new IllegalStateException(ex);
}
- // Configure the DNA JCR engine. This could be done by loading a configuration from a file, or by
+ // Configure the DNA configuration. This could be done by loading a configuration from a file, or by
// using a (local or remote) configuration repository, or by setting up the configuration programmatically.
// This example uses the programmatic approach...
String repositoryId = "content";
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -24,7 +24,10 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE authorgroup 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;
+]>
<authorgroup>
<corpauthor>Randall M. Hauch</corpauthor>
<corpauthor>John Verhaeg</corpauthor>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/conclusion.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/conclusion.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/conclusion.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,75 @@
+<?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 chapter 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="conclusion">
+ <title>Wrapping Up</title>
+ <para>
+ This document provided a very high-level overview of JBoss DNA, introducing you to what would be required to use JBoss DNA
+ in your own application. We saw two simple examples that showed two different aspects of JBoss DNA: the sequencing system
+ and the connector system. Each of these examples showed how to create a JBoss DNA configuration, how to start up
+ the JBoss DNA engine, and how to then access a <code>javax.jcr.Repository</code> instance, and after that your application
+ just uses the standard JCR API.
+ </para>
+ <para>
+ For a more in-depth description of JBoss DNA and the internal workings, see our &ReferenceGuide;.
+ This also describes how to write your own custom sequencers or connectors.
+ If you have any questions or comments, please feel free to contact JBoss DNA's
+ <ulink url="mailto:dna-users at jboss.org">user mailing list</ulink>
+ or use the
+ <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=272">user forums</ulink>
+ or (preferably) the
+ <ulink url="http://www.jboss.org/dna/lists.html">mailing lists</ulink>. If you find a bug or have a suggestion, please
+ create a new issue in the project's
+ <ulink url="http://jira.jboss.org/jira/browse/DNA">JIRA issue management system</ulink>
+ . If there's something in particular you're interested in, talk with the community - there may be others interested in the
+ same thing.
+ </para>
+ <sect1 id="future">
+ <title>Future directions</title>
+ <para>
+ What's next for JBoss DNA? Well, the sequencing system is just the beginning. With this release, the sequencing system
+ is stable enough so that more <link linkend="sequencers">sequencers</link> can be developed and used within your own applications.
+ We've also established the foundation for JBoss DNA repositories, including a number of <link linkend="repository-connectors">connectors</link>.
+ We'll continue to expand our library of sequencers and connectors, as well as expand our support of JCR.
+ Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific
+ views of information in the repository. These components are farther out on our roadmap, and at this time have not been
+ targeted to a particular release.
+ </para>
+ </sect1>
+ <sect1 id="get_involved">
+ <title>Getting involved</title>
+ <para>
+ If you're interested in getting involved with the JBoss DNA project, consider picking up one of the sequencers or connectors on our
+ <ulink url="&Roadmap;">roadmap</ulink>.
+ Or, check out <ulink url="&JIRA;">JIRA</ulink>
+ for the list of features we've thought of. If you think of one that's not there, please add it to JIRA!
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/content/conclusion.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Deleted: trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -1,346 +0,0 @@
-<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="custom_sequencers">
- <title>Creating custom sequencers</title>
- <para>The current release of JBoss DNA comes with six sequencers. However, it's very easy to create your own
- sequencers and to then configure JBoss DNA to use them in your own application.
- </para>
- <para>
- Creating a custom sequencer involves the following steps:
- <itemizedlist>
- <listitem>
- <para>Create a Maven 2 project for your sequencer;</para>
- </listitem>
- <listitem>
- <para>Implement the <code>org.jboss.dna.spi.sequencers.StreamSequencer</code> interface with your own implementation, and create unit tests to verify
- the functionality and expected behavior;</para>
- </listitem>
- <listitem>
- <para>Add the sequencer configuration to the JBoss DNA <code>SequencingService</code> in your application
- as described in the <link linkend="using_dna">previous chapter</link>; and</para>
- </listitem>
- <listitem>
- <para>Deploy the JAR file with your implementation (as well as any dependencies), and make them available to JBoss DNA
- in your application.</para>
- </listitem>
- </itemizedlist>
- It's that simple.
- </para>
- <sect1 id="custom_sequencer_project">
- <title>Creating the Maven 2 project</title>
- <para>The first step is to create the Maven 2 project that you can use to compile your code and build the JARs.
- Maven 2 automates a lot of the work, and since you're already <link linkend="downloading_and_running">set up to use Maven</link>,
- using Maven for your project will save you a lot of time and effort. Of course, you don't have to use Maven 2, but then you'll
- have to get the required libraries and manage the compiling and building process yourself.</para>
- <note>
- <para>JBoss DNA may provide in the future a Maven archetype for creating sequencer projects. If you'd find this useful
- and would like to help create it, please <link linkend="preface">join the community</link>.</para>
- </note>
- <note>
- <para>The <code>dna-sequencer-images</code> project is a small, self-contained sequencer implementation that
- has only the minimal dependencies. Starting with this project's source and modifying it to suit your needs may be the easiest way to get started.
- See the subversion repository: <ulink url="http://anonsvn.jboss.org/repos/dna/trunk/extensions/dna-sequencer-images/">http://anonsvn.jboss.org/repos/dna/trunk/sequencers/dna-sequencer-images/</ulink>
- </para>
- </note>
- <para>You can create your Maven project any way you'd like. For examples, see the <ulink url="http://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project">Maven 2 documentation</ulink>.
- Once you've done that, just add the dependencies in your project's <code>pom.xml</code> dependencies section:</para>
- <programlisting role="XML"><![CDATA[
-<dependency>
- <groupId>org.jboss.dna</groupId>
- <artifactId>dna-common</artifactId>
- <version>0.5</version>
-</dependency>
-<dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-api</artifactId>
-</dependency>
- ]]></programlisting>
- <para>These are minimum dependencies required for compiling a sequencer. Of course, you'll have to add
- other dependencies that your sequencer needs.</para>
- <para>As for testing, you probably will want to add more dependencies, such as those listed here:</para>
- <programlisting role="XML"><![CDATA[
-<dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.4</version>
- <scope>test</scope>
-</dependency>
-<dependency>
- <groupId>org.hamcrest</groupId>
- <artifactId>hamcrest-library</artifactId>
- <version>1.1</version>
- <scope>test</scope>
-</dependency>
-<!-- Logging with Log4J -->
-<dependency>
- <groupId>org.slf4j</groupId>
- <artifactId>slf4j-log4j12</artifactId>
- <version>1.4.3</version>
- <scope>test</scope>
-</dependency>
-<dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.14</version>
- <scope>test</scope>
-</dependency>
- ]]></programlisting>
- <para>Testing JBoss DNA sequencers does not require a JCR repository or the JBoss DNA services. (For more detail,
- see the <link linkend="testing_custom_sequencers">testing section</link>.) However, if you want to do
- integration testing with a JCR repository and the JBoss DNA services, you'll need additional dependencies for these libraries.</para>
- <programlisting role="XML"><![CDATA[
-<!-- JBoss DNA JCR Repository -->
-<dependency>
- <groupId>org.jboss.dna</groupId>
- <artifactId>dna-jcr</artifactId>
- <version>0.5</version>
- <scope>test</scope>
-</dependency>
-<!-- Java Content Repository API -->
-<dependency>
- <groupId>javax.jcr</groupId>
- <artifactId>jcr</artifactId>
- <version>1.0.1</version>
- <scope>test</scope>
-</dependency>
- ]]></programlisting>
- <para>At this point, your project should be set up correctly, and you're ready to move on to
- <link linkend="custom_sequencer_implementation">writing the Java implementation</link> for your sequencer.</para>
- </sect1>
- <sect1 id="custom_sequencer_implementation">
- <title>Implementing the StreamSequencer interface</title>
- <para>After creating the project and setting up the dependencies, the next step is to create a Java class that implements
- the <code>org.jboss.dna.spi.sequencers.StreamSequencer</code> interface. This interface is very straightforward
- and involves a single method:</para>
- <programlisting role="JAVA"><![CDATA[
-public interface StreamSequencer {
-
- /**
- * Sequence the data found in the supplied stream, placing the output
- * information into the supplied map.
- *
- * @param stream the stream with the data to be sequenced; never null
- * @param output the output from the sequencing operation; never null
- * @param context the context for the sequencing operation; never null
- */
- void sequence( InputStream stream, SequencerOutput output, SequencerContext context );
- ]]></programlisting>
- <para>The job of a stream sequencer is to process the data in the supplied stream, and place into the <code>SequencerOutput</code>
- any information that is to go into the JCR repository. JBoss DNA figures out when your sequencer should be called
- (of course, using the sequencing configuration you'll add in a bit), and then makes sure the generated information
- is saved in the correct place in the repository.
- </para>
- <para>The <code>SequencerContext</code> provides information about
- the current sequencing operation, including the location and properties of the node being sequenced, the MIME type
- of the node being sequenced, and a location to record problems that aren't severe enough to warrant throwing an exception.
- </para>
- <para>The <code>SequencerOutput</code> class is fairly easy to use. There are basically two methods you need to call.
- One method sets the property values, while the other sets references to other nodes in the repository. Use these
- methods to describe the properties of the nodes you want to create, using relative paths for the nodes and
- valid JCR property names for properties and references. JBoss DNA will ensure that nodes are created or updated
- whenever they're needed.</para>
- <programlisting role="JAVA"><![CDATA[
-public interface SequencerOutput {
-
- /**
- * Set the supplied property on the supplied node. The allowable
- * values are any of the following:
- * - primitives (which will be autoboxed)
- * - String instances
- * - String arrays
- * - byte arrays
- * - InputStream instances
- * - Calendar instances
- *
- * @param nodePath the path to the node containing the property;
- * may not be null
- * @param property the name of the property to be set
- * @param values the value(s) for the property; may be empty if
- * any existing property is to be removed
- */
- void setProperty( String nodePath, String property, Object... values );
-
- /**
- * Set the supplied reference on the supplied node.
- *
- * @param nodePath the path to the node containing the property;
- * may not be null
- * @param property the name of the property to be set
- * @param paths the paths to the referenced property, which may be
- * absolute paths or relative to the sequencer output node;
- * may be empty if any existing property is to be removed
- */
- void setReference( String nodePath, String property, String... paths );
-}
- ]]></programlisting>
- <para>JBoss DNA will create nodes of type <code>nt:unstructured</code> unless you specify the value for the
- <code>jcr:primaryType</code> property. You can also specify the values for the <code>jcr:mixinTypes</code> property
- if you want to add mixins to any node.</para>
- <para>For a complete example of a sequencer, let's look at the <code>org.jboss.dna.sequencers.image.ImageMetadataSequencer</code>
- implementation:</para>
- <programlisting role="JAVA"><![CDATA[
-public class ImageMetadataSequencer implements StreamSequencer {
-
- public static final String METADATA_NODE = "image:metadata";
- public static final String IMAGE_PRIMARY_TYPE = "jcr:primaryType";
- public static final String IMAGE_MIXINS = "jcr:mixinTypes";
- public static final String IMAGE_MIME_TYPE = "jcr:mimeType";
- public static final String IMAGE_ENCODING = "jcr:encoding";
- public static final String IMAGE_FORMAT_NAME = "image:formatName";
- public static final String IMAGE_WIDTH = "image:width";
- public static final String IMAGE_HEIGHT = "image:height";
- public static final String IMAGE_BITS_PER_PIXEL = "image:bitsPerPixel";
- public static final String IMAGE_PROGRESSIVE = "image:progressive";
- public static final String IMAGE_NUMBER_OF_IMAGES = "image:numberOfImages";
- public static final String IMAGE_PHYSICAL_WIDTH_DPI = "image:physicalWidthDpi";
- public static final String IMAGE_PHYSICAL_HEIGHT_DPI = "image:physicalHeightDpi";
- public static final String IMAGE_PHYSICAL_WIDTH_INCHES = "image:physicalWidthInches";
- public static final String IMAGE_PHYSICAL_HEIGHT_INCHES = "image:physicalHeightInches";
-
- /**
- * {@inheritDoc}
- */
- public void sequence( InputStream stream, SequencerOutput output,
- SequencerContext context ) {
- ImageMetadata metadata = new ImageMetadata();
- metadata.setInput(stream);
- metadata.setDetermineImageNumber(true);
- metadata.setCollectComments(true);
-
- // Process the image stream and extract the metadata ...
- if (!metadata.check()) {
- metadata = null;
- }
-
- // Generate the output graph if we found useful metadata ...
- if (metadata != null) {
- // Place the image metadata into the output map ...
- output.setProperty(METADATA_NODE, IMAGE_PRIMARY_TYPE, "image:metadata");
- // output.psetProperty(METADATA_NODE, IMAGE_MIXINS, "");
- output.setProperty(METADATA_NODE, IMAGE_MIME_TYPE, metadata.getMimeType());
- // output.setProperty(METADATA_NODE, IMAGE_ENCODING, "");
- output.setProperty(METADATA_NODE, IMAGE_FORMAT_NAME, metadata.getFormatName());
- output.setProperty(METADATA_NODE, IMAGE_WIDTH, metadata.getWidth());
- output.setProperty(METADATA_NODE, IMAGE_HEIGHT, metadata.getHeight());
- output.setProperty(METADATA_NODE, IMAGE_BITS_PER_PIXEL, metadata.getBitsPerPixel());
- output.setProperty(METADATA_NODE, IMAGE_PROGRESSIVE, metadata.isProgressive());
- output.setProperty(METADATA_NODE, IMAGE_NUMBER_OF_IMAGES, metadata.getNumberOfImages());
- output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_DPI, metadata.getPhysicalWidthDpi());
- output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_DPI, metadata.getPhysicalHeightDpi());
- output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_WIDTH_INCHES, metadata.getPhysicalWidthInch());
- output.setProperty(METADATA_NODE, IMAGE_PHYSICAL_HEIGHT_INCHES, metadata.getPhysicalHeightInch());
- }
- }
-}
- ]]></programlisting>
- <para>
- Notice how the image metadata is extracted and the output graph is generated. A single node is created with the name <code>image:metadata</code>
- and with the <code>image:metadata</code> node type. No mixins are defined for the node, but several properties are set on the node
- using the values obtained from the image metadata. After this method returns, the constructed graph will be saved to the repository
- in all of the places defined by its configuration. (This is why only relative paths are used in the sequencer.)
- </para>
- </sect1>
- <sect1 id="testing_custom_sequencers">
- <title>Testing custom sequencers</title>
- <para>The sequencing framework was designed to make testing sequencers much easier. In particular, the
- <code>StreamSequencer</code> interface does not make use of the JCR API. So instead of requiring a fully-configured
- JCR repository and JBoss DNA system, unit tests for a sequencer can focus on testing that the content is
- processed correctly and the desired output graph is generated.</para>
- <note>
- <para>For a complete example of a sequencer unit test, see the <code>ImageMetadataSequencerTest</code> unit test
- in the <code>org.jboss.dna.sequencer.images</code> package of the <code>dna-sequencers-image</code> project.
- </para>
- </note>
- <para>The following code fragment shows one way of testing a sequencer, using JUnit 4.4 assertions and
- some of the classes made available by JBoss DNA. Of course,
- this example code does not do any error handling and does not make all the assertions a real test would.</para>
- <programlisting role="JAVA"><![CDATA[
-Sequencer sequencer = new ImageMetadataSequencer();
-MockSequencerOutput output = new MockSequencerOutput();
-MockSequencerContext context = new MockSequencerContext();
-InputStream stream = null;
-try {
- stream = this.getClass().getClassLoader().getResource("caution.gif").openStream();
- sequencer.sequence(stream,output,context); // writes to 'output'
- assertThat(output.getPropertyValues("image:metadata", "jcr:primaryType"),
- is(new Object[] {"image:metadata"}));
- assertThat(output.getPropertyValues("image:metadata", "jcr:mimeType"),
- is(new Object[] {"image/gif"}));
- // ... make more assertions here
- assertThat(output.hasReferences(), is(false));
-} finally {
- stream.close();
-}
- ]]></programlisting>
- <para>It's also useful to test that a sequencer produces no output for something it should not understand:</para>
- <programlisting role="JAVA"><![CDATA[
-Sequencer sequencer = new ImageMetadataSequencer();
-MockSequencerOutput output = new MockSequencerOutput();
-MockSequencerContext context = new MockSequencerContext();
-InputStream stream = null;
-try {
- stream = this.getClass().getClassLoader().getResource("caution.pict").openStream();
- sequencer.sequence(stream,output,context); // writes to 'output'
- assertThat(output.hasProperties(), is(false));
- assertThat(output.hasReferences(), is(false));
-} finally {
- stream.close();
-}
- ]]></programlisting>
- <para>These are just two simple tests that show ways of testing a sequencer. Some tests may get quite involved,
- especially if a lot of output data is produced.
- </para>
- <para>It may also be useful to create some integration tests
- that <link linkend="using_dna">configure JBoss DNA</link> to use a custom sequencer, and to then upload
- content using the JCR API, verifying that the custom sequencer did run. However, remember that JBoss DNA
- runs sequencers asynchronously in the background, and you must sychronize your tests to ensure that the
- sequencers have a chance to run before checking the results. (One way of doing this (although, granted, not always reliable) is to wait for a second
- after uploading your content, shutdown the <code>SequencingService</code> and await its termination,
- and then check that the sequencer output has been saved to the JCR repository. For an example of this technique,
- see the <code>SequencingClientTest</code> unit test in the example application.)
- </para>
- </sect1>
- <sect1 id="deploying_custom_sequencers">
- <title>Deploying custom sequencers</title>
- <para>The first step of deploying a sequencer consists of adding/changing the sequencer configuration (e.g., <code>SequencerConfig</code>)
- in the <code>SequencingService</code>. This was covered in the <link linkend="sequencing_service">previous chapter</link>.
- </para>
- <para>
- The second step is to make the sequencer implementation available to JBoss DNA. At this time, the JAR containing
- your new sequencer, as well as any JARs that your sequencer depends on, should be placed on your application classpath.</para>
- <note>
- <para>A future goal of JBoss DNA is to allow sequencers, connectors, and other extensions to be easily deployed into
- a runtime repository. This process will not only be much simpler, but it will also provide JBoss DNA
- with the information necessary to update configurations and create the appropriate class loaders for each extension.
- Having separate class loaders for each extension helps prevent the pollution of the common classpath,
- facilitates an isolated runtime environment to eliminate any dependency conflicts, and may potentially
- enable hot redeployment of newer extension versions.
- </para>
- </note>
- </sect1>
-</chapter>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -24,14 +24,17 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter 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="downloading_and_running">
<title>Running the example applications</title>
<para>
This chapter provides instructions for downloading and running a sample application that demonstrates how JBoss DNA works
with a JCR repository to automatically sequence changing content to extract useful information. So read on to get the simple
- application running, and then in the <link linkend="using_dna">next chapter</link>
- we'll dive into the source code for the example and show how to use JBoss DNA in your own applications. </para>
+ application running.
+ </para>
<para>JBoss DNA uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including
the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus
everything that library needs. This means that it's very easy to build the examples - or even create a maven project that
@@ -244,165 +247,10 @@
</itemizedlist>
</para>
</sect1>
- <sect1 id="running_sequencer_example">
- <title>Running the sequencing example</title>
- <para>The sequencing example consists of a client application that sets up an in-memory JCR repository and that allows a user to
- upload files into that repository. The client also sets up the DNA services with two sequencers so that if any of the
- uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will automatically extract the image's metadata (e.g., image
- format, physical size, pixel density, etc.) and store that in the repository. Alternatively, if the uploaded file
- is an MP3 audio file, DNA will extract some of the ID3 metadata (e.g., the author, title, album, year and comment)
- and store that in the repository.</para>
- <para>
- To run the client application, go to the <code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code>
- directory and type <code>./run.sh</code>. You should see the command-line client and its menus in your terminal:
- <figure id="xample-sequencer-cli-client">
- <title>Example client</title>
- <graphic align="center" scale="100" fileref="example-sequencer-client.png"/>
- </figure>
- From this menu, you can upload a file into the repository, search for media in the repository, print sequencing statistics,
- or quit the application.</para>
- <para>
- The first step is to upload one of the example images. If you type 'u' and press return, you'll be prompted to supply the
- path to the file you want to upload. Since the application is running from within the
- <code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code> directory, you can specify any of the files
- in that directory without specifying the path:
- <figure id="example-sequencer-upload">
- <title>Uploading an image using the example client</title>
- <graphic align="center" scale="100" fileref="example-sequencer-upload.png"/>
- </figure>
- You can specify any fully-qualified or relative path. The application will notify you if it cannot find the file you
- specified. The example client configures JBoss DNA to sequence MP3 audio files, Java source files, or image files with one of
- the following extensions (technically, nodes that have names ending in the following):
- <code>jpg</code>, <code>jpeg</code>, <code>gif</code>, <code>bmp</code>, <code>pcx</code>, <code>png</code>,
- <code>iff</code>, <code>ras</code>, <code>pbm</code>, <code>pgm</code>, <code>ppm</code>, and <code>psd</code>.
- Files with other extensions in the repository path will be ignored. For your convenience, the example provides several
- files that will be sequenced (<code>caution.png</code>, <code>caution.jpg</code>, <code>caution.gif</code>, and
- <code>sample1.mp3</code>) and one image that will not be sequenced (<code>caution.pict</code>). Feel free to try other files.
- </para>
- <para>
- After you have specified the file you want to upload, the example application asks you where in the repository you'd like to
- place the file. (If you want to use the suggested location, just press <code>return</code>.) The client application
- uses the JCR API to upload the file to that location in the repository, creating any nodes (of type <code>nt:folder</code>)
- for any directories that don't exist, and creating a node (of type <code>nt:file</code>) for the file. And, per the JCR specification,
- the application creates a <code>jcr:content</code> node (of type <code>nt:resource</code>) under the file node.
- The file contents are placed on this <code>jcr:content</code> node in the <code>jcr:data</code> property. For example, if you specify
- <code>/a/b/caution.png</code>, the following structure will be created in the repository:</para>
- <programlisting><![CDATA[
-/a (nt:folder)
- /b (nt:folder)
- /caution.png (nt:file)
- /jcr:content (nt:resource)
- @jcr:data = {contents of the file}
- @jcr:mimeType = {mime type of the file}
- @jcr:lastModified = {now}
-]]></programlisting>
- <para>Other kinds of files are treated in a similar way.</para>
- <para>When the client uploads the file using the JCR API, DNA gets notified of the changes, consults the sequencers to see whether
- any of them are interested in the new or updated content, and if so runs those sequencers. The image sequencer processes image
- files for metadata, and any metadata found is stored under the <code>/images</code> branch of the repository. The MP3 sequencer
- processes MP3 audio files for metadata, and any metadata found is stored under the <code>/mp3s</code>
- branch of the repository. And metadata about Java classes are stored under the <code>/java</code> area of the repository.
- All of this happens asynchronously, so any DNA activity doesn't impede or slow down the client activities.
- </para>
- <para>So, after the file is uploaded, you can search the repository for the image metadata using the "s" menu option:
- <figure id="example-sequencer-search">
- <title>Searching for media using the example client</title>
- <graphic align="center" scale="100" fileref="example-sequencer-search.png"/>
- </figure>
- Here are the search results after the <code>sample1.mp3</code> audio file has been uploaded (to the <code>/a/b/sample1.mp3</code> location):
- <figure id="example-sequencer-search-with-mp3">
- <title>Searching for media using the example client</title>
- <graphic align="center" scale="100" fileref="example-sequencer-search-with-mp3.png"/>
- </figure>
- You can also display the sequencing statistics using the "d" menu option:
- <figure id="example-sequencer-statistics">
- <title>Sequencing statistics using the example client</title>
- <graphic align="center" scale="100" fileref="example-sequencer-statistics.png"/>
- </figure>
- These stats show how many nodes were sequenced, and how many nodes were skipped because they didn't apply to the sequencer's
- criteria.
- </para>
- <note>
- <para>There will probably be more nodes skipped than sequenced, since there are more <code>nt:folder</code> and <code>nt:resource</code>
- nodes than there are <code>nt:file</code> nodes with acceptable names.</para>
- </note>
- <para>You can repeat this process with other files. Any file that isn't an image or MP3 files (as recognized by the sequencing configurations
- that we'll describe later) will not be sequenced.</para>
+ <sect1 id="downloading_and_running_whats_next">
+ <title>What's next</title>
+ <para>In this chapter you downloaded, installed, and built the two example applications. In the next two chapters, we'll
+ run these examples and walk through the code.
+ </para>
</sect1>
- <sect1 id="running_repository_example">
- <title>Running the repository example</title>
- <para>The repository example consists of a client application that sets up two DNA repositories (named "Cars" and "Airplanes") and
- a federated repository ("Vehicles") that dynamically federates the information from the other two repositories.
- The client application allows you to interactively navigate each of these repositories just as you would navigate the
- directory structure on a file system.</para>
- <para>This collection of repositories is shown in the following figure:
- <figure id="example-repositories">
- <title>Repositories used in the example client</title>
- <graphic align="center" scale="100" fileref="example-repositories.png"/>
- </figure>
- Most of the repositories are in-memory repositories (using the In-Memory repository connector), but the federated "Vehicles" repository
- content is federated from the other repositories and cached into the "Cache" repository. This is shown in the following figure:
- <figure id="example-federated-repository">
- <title>Vehicles repository content is federated from the Cars, Airplanes and Configuration repositories</title>
- <graphic align="center" scale="100" fileref="example-federated-repository.png"/>
- </figure>
- </para>
- <para>
- To run the client application, go to the <code>examples/repository/target/dna-example-repositories-basic.dir/</code>
- directory and type <code>./run.sh</code>. You should see the command-line client and its menus in your terminal:
- <figure id="example-repositories-client">
- <title>Example Client</title>
- <graphic align="center" scale="100" fileref="example-repositories-client.png"/>
- </figure>
- From this menu, you can see the list of repositories, select one, and navigate through that repository in a manner similar
- to a *nix command-line shell (although the client itself uses the JCR API to interact with the repositories).
- Here are some of the commands you can use:</para>
- <table frame='all'>
- <title>Repository client commands to navigate a repository</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <thead>
- <row><entry>Command</entry><entry>Description</entry></row>
- </thead>
- <tbody>
- <row><entry>pwd</entry><entry>Print the path of the current node (e.g., the "working directory")</entry></row>
- <row><entry>ls [<emphasis>path</emphasis>]</entry><entry>List the children and properties of the node at the supplied path,
- where "<emphasis>path</emphasis>" can be any relative path or absolute path. If "<emphasis>path</emphasis>" is not supplied,
- the current working node's path is used.</entry></row>
- <row><entry>cd <emphasis>path</emphasis></entry><entry>Change to the specified node, where "<emphasis>path</emphasis>"
- can be any relative path or absolute path. For example, "<code>cd alpha</code>" changes the current node to be a child named
- "<code>alpha</code>"; "<code>cd ..</code>" changes the current node to the parent node; "<code>cd /a/b</code>" changes
- the current node to be the "<code>/a/b</code>" node.</entry></row>
- <row><entry>exit</entry><entry>Exit this repository and return the list of repositories.</entry></row>
- </tbody>
- </tgroup>
- </table>
- <para>If you were to select the "Cars" repository and use some of the commands, you should see something similar to:
- <figure id="example-repositories-navigating">
- <title>Navigating the Cars repository</title>
- <graphic align="center" scale="100" fileref="example-repositories-navigating.png"/>
- </figure>
- </para>
- <para>You can also choose to navigate the "Vehicles" repository, which projects the "Cars" repository content under the
- <code>/Vehicles/Cars</code> node, the "Airplanes" content under the <code>/Vehicles/Airplanes</code> branch,
- and the "Configuration" content under <code>/dna:system</code>.
- </para>
- <para>Try using the client to walk the different repositories. And while this is a contrived application, it does demonstrate
- the use of JBoss DNA to federate repositories and provide access through JCR.</para>
- </sect1>
- <sect1 id="downloading_and_running_review">
- <title>Summarizing what we just did</title>
- <para>In this chapter you downloaded, installed, and built the two example applicationss. With the sequencer client, you could upload files into a
- JCR repository, while JBoss DNA automatically sequenced the image, MP3, or Java source files you uploaded, extracted the metadata from the
- files, and stored that metadata inside the repository. The repository client allowed you to walk through multiple repositories,
- including one whose content was federated from multiple other repositories.</para>
- <para>These example applications were very simplistic. In fact, running through the examples probably only took you a few minutes.
- So while these applications won't win any awards, they hopefully showed you the basics of what JBoss DNA can do.</para>
- <para>In the next two chapters, we'll venture into the code to get an understanding of how JBoss DNA actually works.
- The <link linkend="using_dna_for_sequencing">next chapter</link> reviews the sequencer application and talks about
- how you can use DNA sequencers in your own applications. Then in the <link linkend="using_dna_repositories">following chapter</link>
- we'll venture into the repositories example code to show how you can use DNA repositories, including federated repositories,
- in your own applications.</para>
- </sect1>
</chapter>
Deleted: trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -1,45 +0,0 @@
-<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="future">
- <title>Looking to the future</title>
- <para>
- What's next for JBoss DNA? Well, the sequencing system is just the beginning. With this release, the sequencing system
- is stable enough so that more <link linkend="sequencers">sequencers</link> can be developed and used within your own applications.
- We've also established the foundation for JBoss DNA repositories, including a number of <link linkend="repository-connectors">connectors</link>.
- We'll continue to expand our library of sequencers and connectors, as well as expand our support of JCR.
- Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific
- views of information in the repository. These components are farther out on our roadmap, and at this time have not been
- targeted to a particular release.
- </para>
- <para>
- If you're interested in getting involved with the JBoss DNA project, consider picking up one of the sequencers on our
- <ulink url="http://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira.plugin.system.project:roadmap-panel">roadmap</ulink>.
- Or, check out <ulink url="http://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=true&mode=hide&pid=12310520&sorter/order=DESC&sorter/field=priority&resolution=-1&component=12311436">JIRA</ulink>
- for the list of sequencers we've thought of. If you think of one that's not there, please add it to JIRA!
- </para>
-</chapter>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -24,7 +24,10 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE chapter 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="introduction">
<title>Introduction</title>
<para>There are a lot of ways for applications to store information persistently so that it can be accessed at a
@@ -85,26 +88,48 @@
and is being revised under <ulink url="http://www.jcp.org/en/jsr/detail?id=283">JSR-283</ulink>.
</para>
<para>
- The <emphasis>JBoss DNA project</emphasis>
- is building unified metadata repository system that is compliant with JCR. Nearly all of these capabilities are to be hidden
- below the JCR API and involve automated processing of the information in the repository. Thus, JBoss DNA can add value to
- existing repository implementations. For example, JCR repositories offer the ability to upload files into the repository and
- have the file content indexed for search purposes. JBoss DNA also defines a library for "sequencing" content - to extract
- meaningful information from that content and store it in the repository, where it can then be searched, accessed, and
- analyzed using the JCR API.
- </para>
- <para> JBoss DNA has other features as well. You can create federated repositories that dynamically merge the information
- from multiple databases, services, applications, and other JCR repositories. JBoss DNA also will allow you to
- create customized views based upon the type of data and the role of the user that is accessing the data. And yet another goal is
- to create a REST-ful API to allow the JCR content to be accessed easily by other applications written in other languages.
- </para>
- <para>
- The <link linkend="understanding_dna">next chapter</link> in this book goes into more detail about JBoss DNA and its architecture,
- the different components, what's available now, and what's coming in future releases.
- <link linkend="downloading_and_running">Chapter 3</link> then provides instructions for downloading and running the sequencer
- examples for the current release. <link linkend="using_dna">Chapter 4</link> walks through how to use JBoss DNA sequencers
- in your applications, while <link linkend="custom_sequencers">Chapter 5</link> shows how to use JBoss DNA repositories.
- <link linkend="custom_sequencers">Chapter 6</link> goes over how to create custom sequencers, and finally,
- <link linkend="future">Chapter 7</link> wraps things up with a discussion about the future of JBoss DNA.
- </para>
+ The JCR API provides a number of information services that are needed by many applications,
+ including: read and write access to information; the ability to structure information in a hierarchical and flexible manner that can adapt
+ and evolve over time; ability to work with unstructured content; ability to (transparently) handle large strings;
+ notifications of changes in the information; search and query; versioning of information; access control; integrity constraints;
+ participation within distributed transactions; explicit locking of content; and of course persistence.
+ </para>
+ <sect1 id="what_is_jboss_dna">
+ <title>JBoss DNA</title>
+ <para>
+ What makes JCR interesting, however, is that a JCR implementation provides all these features and capabilities regardless
+ of where or how that information is persisted or stored. <emphasis>This is in fact the main purpose of JBoss DNA:
+ provide a JCR implementation that provides access to content stored in many different kinds of systems.</emphasis>
+ A JBoss DNA repository isn't yet another silo of information, but rather it's a JCR view of the information you already have
+ in your environment: files systems, databases, other repositories, services, applications, etc. JBoss DNA can
+ help you understand the systems and information you already have.
+ </para>
+ <para>
+ Of course when you start providing a unified view of all this information, you start recognizing the need to store more
+ information, including metadata about and relationships between the existing content. JBoss DNA lets you do this, too.
+ And JBoss DNA even tries to help you discover more about the information you already have, especially the
+ information wrapped up in the kinds of files often found in enterprise systems: service definitions, policy files,
+ images, media, documents, presentations, application components, reusable libraries, configuration files,
+ application installations, databases schemas, management scripts, and so on. As files are loaded into the repository,
+ JBoss DNA can <emphasis>sequence</emphasis> these files to extract from their content meaningful information that
+ can be stored in the repository, where it can then be searched, accessed, and analyzed using the JCR API.
+ </para>
+ </sect1>
+ <sect1 id="introduction_whats_next">
+ <title>What's next</title>
+ <para>
+ As we'll see in the <link linkend="use_cases">next chapter</link>, the ability of JBoss DNA to
+ federate, integrate, and sequence information make JBoss DNA a powerful asset and tool.
+ Then <link linkend="using_dna">Chapter 3</link> will show that once a JBoss DNA repository is set up, application see
+ JBoss DNA just as another JCR <code>javax.jcr.Repository</code> instance and uses the standard JCR API to obtain a <code>javax.jcr.Session</code>
+ and work with the content.
+ </para>
+ <para>
+ <link linkend="downloading_and_running">Chapter 4</link> walks you through downloading
+ and building the JBoss DNA examples, while <link linkend="sequencer_example">Chapter 5</link>
+ and <link linkend="repository_example">Chapter 6</link> will run these very simple examples and walking through code.
+ <link linkend="conclusion">Chapter 7</link> wraps things up with a discussion about the future of JBoss DNA
+ and what you can do next to start using JBoss DNA in your own applications.
+ </para>
+ </sect1>
</chapter>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -24,7 +24,10 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!DOCTYPE legalnotice 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;
+]>
<legalnotice id="Legal_Notice">
<title>Legal Notice</title>
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -24,7 +24,10 @@
~ 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">
+<!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;
+]>
<preface id="preface" revision="1">
<title>What this book covers</title>
<para>The goal of this book is to help you learn about JBoss DNA and how you can use it in your own applications to get the
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,483 @@
+<?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 chapter 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="repository_example">
+ <title>The Repository Example</title>
+ <para>
+ <link linkend="downloading_and_running">Chapter 4</link> walked through the process of downloading and building the examples,
+ while the <link linkend="sequencer_example">previous chapter</link> showed how to run the sequencer example and walked
+ through the code. In this chapter, we'll run the repository example and walk through that example code to see what
+ it's doing.
+ </para>
+ <sect1 id="running_repository_example">
+ <title>Running the repository example</title>
+ <para>The repository example consists of a client application that sets up two DNA repositories (named "Cars" and "Airplanes") and
+ a federated repository ("Vehicles") that dynamically federates the information from the other two repositories.
+ The client application allows you to interactively navigate each of these repositories just as you would navigate the
+ directory structure on a file system.</para>
+ <para>This collection of repositories is shown in the following figure:
+ <figure id="example-repositories">
+ <title>Repositories used in the example client</title>
+ <graphic align="center" scale="100" fileref="example-repositories.png"/>
+ </figure>
+ Most of the repositories are in-memory repositories (using the In-Memory repository connector), but the federated "Vehicles" repository
+ content is federated from the other repositories and cached into the "Cache" repository. This is shown in the following figure:
+ <figure id="example-federated-repository">
+ <title>Vehicles repository content is federated from the Cars, Airplanes and Configuration repositories</title>
+ <graphic align="center" scale="100" fileref="example-federated-repository.png"/>
+ </figure>
+ </para>
+ <para>
+ To run the client application, go to the <code>examples/repository/target/dna-example-repositories-basic.dir/</code>
+ directory and type <code>./run.sh</code>. You should see the command-line client and its menus in your terminal:
+ <figure id="example-repositories-client">
+ <title>Example Client</title>
+ <graphic align="center" scale="100" fileref="example-repositories-client.png"/>
+ </figure>
+ From this menu, you can see the list of repositories, select one, and navigate through that repository in a manner similar
+ to a *nix command-line shell (although the client itself uses the JCR API to interact with the repositories).
+ Here are some of the commands you can use:</para>
+ <table frame='all'>
+ <title>Repository client commands to navigate a repository</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row><entry>Command</entry><entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row><entry>pwd</entry><entry>Print the path of the current node (e.g., the "working directory")</entry></row>
+ <row><entry>ls [<emphasis>path</emphasis>]</entry><entry>List the children and properties of the node at the supplied path,
+ where "<emphasis>path</emphasis>" can be any relative path or absolute path. If "<emphasis>path</emphasis>" is not supplied,
+ the current working node's path is used.</entry></row>
+ <row><entry>cd <emphasis>path</emphasis></entry><entry>Change to the specified node, where "<emphasis>path</emphasis>"
+ can be any relative path or absolute path. For example, "<code>cd alpha</code>" changes the current node to be a child named
+ "<code>alpha</code>"; "<code>cd ..</code>" changes the current node to the parent node; "<code>cd /a/b</code>" changes
+ the current node to be the "<code>/a/b</code>" node.</entry></row>
+ <row><entry>exit</entry><entry>Exit this repository and return the list of repositories.</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>If you were to select the "Cars" repository and use some of the commands, you should see something similar to:
+ <figure id="example-repositories-navigating">
+ <title>Navigating the Cars repository</title>
+ <graphic align="center" scale="100" fileref="example-repositories-navigating.png"/>
+ </figure>
+ </para>
+ <para>You can also choose to navigate the "Vehicles" repository, which projects the "Cars" repository content under the
+ <code>/Vehicles/Cars</code> node, the "Airplanes" content under the <code>/Vehicles/Airplanes</code> branch,
+ and the "Configuration" content under <code>/dna:system</code>.
+ </para>
+ <para>Try using the client to walk the different repositories. And while this is a contrived application, it does demonstrate
+ the use of JBoss DNA to federate repositories and provide access through JCR.</para>
+ </sect1>
+ <sect1 id="connectors">
+ <title>JBoss DNA connectors</title>
+ <para>As mentioned in the <link linkend="introduction">Introduction</link>, one of the capabilities of JBoss DNA is to provide access through
+ <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JCR</ulink> to different kinds of repositories and storage systems.
+ Your applications work with the JCR API, but through JBoss DNA you're able to accesses the content from where the information
+ exists - not just a single purpose-built repository. This is fundamentally what makes JBoss DNA different.</para>
+ <para>How does JBoss DNA do this? At the heart of JBoss DNA and it's JCR implementation is a simple connector
+ system that is designed around creating and accessing graphs. The JBoss DNA JCR implementation actually just sits on
+ top of a single repository source, which it uses to access of the repositories content.
+ <figure id="dnajcr-and-connector">
+ <title>JBoss DNA's JCR implementation delegates to a repository source</title>
+ <graphic align="center" scale="100" fileref="dnajcr-and-connector.png"/>
+ </figure>
+ That single repository source could be an in-memory repository, a JBoss Cache instance, or a federated repository.
+ <figure id="dna-connectors-0.2">
+ <title>JBoss DNA can put JCR on top of multiple kinds of systems</title>
+ <graphic align="center" scale="100" fileref="dna-connectors-0.2.png"/>
+ </figure>
+ And the JBoss DNA project has plans to create other connectors, too. For instance, we're going to build a connector
+ to other JCR repositories. And another to a file system, so that the files and directories on an area of the file system
+ can be accessed through JCR. Of course, if we don't have a connector to suit your needs, you can write your own.
+ <figure id="dna-connectors-future">
+ <title>Future JBoss DNA connectors</title>
+ <graphic align="center" scale="100" fileref="dna-connectors-future.png"/>
+ </figure>
+ </para>
+ <note>
+ <para>You might be thinking that these connectors are interesting, but what do they really provide? Is it really useful
+ to use JCR to access a relational database rather than JDBC? Or, why access the files on a file system when there
+ are already mechanisms to do that?</para>
+ <para>Maybe putting JCR on top of a single system (like a JDBC database) isn't that interesting. What
+ <emphasis>is</emphasis> interesting, though, is accessing the information in multiple systems <emphasis>as if all that information were
+ in a single JCR repository</emphasis>. That's what the federated repository source is all about. The JBoss DNA connector
+ system just makes it possible to interact with all these systems in the same way.</para>
+ <para>Think of it this way: with JBoss DNA, you can use JCR to get to the schemas of multiple relational databases <emphasis>and</emphasis> the schemas
+ defined by DDL files in your SVN repository <emphasis>and</emphasis> the schemas defined by logical models stored on your file system.
+ </para>
+ </note>
+ <para>Before we go further, let's define some terminology regarding connectors.</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A <emphasis role="strong">connector</emphasis> is the runnable code packaged in one or more JAR files that
+ contains implementations of several interfaces (described below). A Java developer <emphasis>writes</emphasis>
+ a connector to a type of source, such as a particular database management system, LDAP directory, source code
+ management system, etc. It is then packaged into one or more JAR files (including dependent JARs) and deployed
+ for use in applications that use JBoss DNA repositories.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The description of a particular source system (e.g., the "Customer" database, or the company LDAP system)
+ is called a <emphasis role="strong">repository source</emphasis>. JBoss DNA defines a &RepositorySource; interface
+ that defines methods describing the behavior and supported features and a method for establishing connections.
+ A connector will have a class that implements this interface and that has JavaBean properties for
+ all of the connector-specific properties required to fully describe an instance of the system. Use of JavaBean
+ properties is not required, but it is highly recommended, as it enables reflective configuration and administration.
+ Applications that use JBoss DNA create an instance of the connector's &RepositorySource; implementation and set
+ the properties for the external source that the application wants to access with that connector.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A repository source instance is then used to establish <emphasis role="strong">connections</emphasis> to
+ that source. A connector provides an implementation of the &RepositoryConnection; interface, which
+ defines methods for interacting with the external system. In particular, the <code>execute(...)</code> method
+ takes an &ExecutionContext; instance and a &Request; object. The &ExectuionContext; object defines the
+ environment in which the processing is occurring, including information about the JAAS &Subject; and &LoginContext;.
+ The &Request; object describes the requested operations on the content, with different concrete subclasses
+ representing each type of activity. Examples of commands include (but not limited to) getting a node, moving a node, creating a node,
+ changing a node, and deleting a node. And, if the repository source is able to participate in JTA/JTS distributed transactions, then the
+ &RepositoryConnection; must implement the <code>getXaResource()</code> method by returning
+ a valid <code>javax.transaction.xa.XAResource</code> object that can be used by the transaction monitor.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>As an example, consider that we want JBoss DNA to give us access through JCR to the schema information contained in a
+ relational databases. We first have to develop a connector that allows us to interact with relational databases using JDBC.
+ That connector would contain a <code>JdbcRepositorySource</code> Java class that implements &RepositorySource;,
+ and that has all of the various JavaBean properties for setting the name of the driver class, URL, username, password,
+ and other properties. (Or we might have a JavaBean property that defines the JNDI name where we can find a JDBC
+ <code>DataSource</code> instance pointing to our JDBC database.)
+ </para>
+ <para>So with this very high-level summary, let's dive a little deeper and look at the repository example.</para>
+ </sect1>
+ <sect1 id="example_repository_application_review">
+ <title>Reviewing the example repository application</title>
+ <para>Recall that the example repository application consists of a client application that sets up a repository service and the
+ repositories defined in a configuration repository, allowing the user to pick a repository and interactively navigate
+ the selected repository. Several repositories are set up, including several in-memory repositories and one federated repository
+ that dynamically federates the content from the other repositories.</para>
+ <para>
+ The example is comprised of 2 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
+ <programlisting><![CDATA[
+ org/jboss/example/dna/repositories/ConsoleInput.java
+ /RepositoryClient.java
+ /UserInterface.java
+ ]]></programlisting>
+ <para><code>RepositoryClient</code> is the class that contains the main application. It uses an instance of the
+ <code>UserInterface</code> interface to methods that will be called at runtime to obtain information about the
+ files that are imported into the in-memory repositories and the JAAS <code>CallbackHandler</code> implementation
+ that will be used by JAAS to prompt the user for authentication information. Finally, the <code>ConsoleInput</code>
+ is an implementation of this that creates a text user interface, allowing the user to operate the client from the command-line.
+ We can easily create a graphical implementation of <code>UserInterface</code> at a later date, or we can also create a mock
+ implementation for testing purposes that simulates a user entering data. This allows us to check the behavior of the client
+ automatically using conventional JUnit test cases, as demonstrated by the code in the <code>src/test/java</code> directory:</para>
+ <programlisting><![CDATA[
+ org/jboss/example/dna/sequencers/RepositoryClientTest.java
+ /RepositoryClientUsingJcrTest.java
+ ]]></programlisting>
+ <para>If we look at the <code>RepositoryClient</code> code, there are a handful of methods that encapsulate the various activities.</para>
+ <note>
+ <para>Some of the code samples included in this book have had some of the error handling and comments removed so that
+ the code is more readable and concise.</para>
+ </note>
+ <para>The <code>main(String[] argv)</code> method is of course the method that is executed when the application is run. This code
+ creates the JBoss DNA configuration by loading it from a file.
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+// Set up the JAAS provider (IDTrust) and a policy file (which defines the "dna-jcr" login config name)
+IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
+try {
+ idtrustConfig.config("security/jaas.conf.xml");
+} catch (Exception ex) {
+ throw new IllegalStateException(ex);
+}
+
+// Now configure the repository client component ...
+RepositoryClient client = new RepositoryClient();
+for (String arg : args) {
+ arg = arg.trim();
+ if (arg.equals("--api=jcr")) client.setApi(Api.JCR);
+ if (arg.equals("--api=dna")) client.setApi(Api.DNA);
+ if (arg.equals("--jaas")) client.setJaasContextName(JAAS_LOGIN_CONTEXT_NAME);
+ if (arg.startsWith("--jaas=") && arg.length() > 7) client.setJaasContextName(arg.substring(7).trim());
+}
+// And have it use a ConsoleInput user interface ...
+client.setUserInterface(new ConsoleInput(client, args));
+ ]]></programlisting>
+ <para>
+ The first block sets up the JAAS provider to be the IDTrust library and a policy file that defines the "dna-jcr" JAAS configuration.
+ </para>
+ <para>
+ The second block of code instantiates the <code>RepositoryClient</code> and passes in some options determined from the command-line.
+ It then sets the user interface (which then executes its behavior, which we'll see below).
+ </para>
+ <para>
+ The <code>startRepositories()</code> method builds the <code>JcrEngine</code> component from the configuration, starts the engine,
+ and obtains the JCR <code>javax.jcr.Repository</code> instance that the client will use. Note that the client has not yet
+ obtained a <code>javax.jcr.Session</code> instance, since this will be done each time the client needs to access content from
+ the repository. (This is actually a common practice according to the JCR specification, since Sessions are intended to be
+ very lightweight.)
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+public void startRepositories() throws IOException, SAXException {
+ if (engine != null) return; // already started
+
+ // Load the configuration from a file, as provided by the user interface ...
+ JcrConfiguration configuration = new JcrConfiguration();
+ configuration.loadFrom(userInterface.getRepositoryConfiguration());
+
+ // Load the node types for each JCR repository, via a CND file. These could have been defined
+ // in the configuration file, but this approach is easy and allows us to define the node types
+ // using the CND format in one or multiple files.
+ String locationOfCndFiles = userInterface.getLocationOfCndFiles();
+ configuration.repository("aircraft repository").addNodeTypes(locationOfCndFiles + "/aircraft.cnd");
+ configuration.repository("car repository").addNodeTypes(locationOfCndFiles + "/cars.cnd");
+ configuration.repository("virtual").addNodeTypes(locationOfCndFiles + "/virtual.cnd");
+
+ // Now create the JCR engine ...
+ engine = configuration.build();
+ engine.start();
+
+ // For this example, we're using a couple of in-memory repositories (including one for the configuration repository).
+ // Normally, these would exist already and would simply be accessed. But in this example, we're going to
+ // populate these repositories here by importing from files. First do the configuration repository ...
+ String location = this.userInterface.getLocationOfRepositoryFiles();
+
+ // Now import the content for the two in-memory repositories ...
+ Graph cars = engine.getGraph("Cars");
+ cars.importXmlFrom(location + "/cars.xml").into("/");
+ Graph aircraft = engine.getGraph("Aircraft");
+ aircraft.importXmlFrom(location + "/aircraft.xml").into("/");
+}
+ ]]></programlisting>
+ <para>
+ This method does a number of different things. First, it checks to make sure the repositories are not already running; if so
+ the method just returns. Then, it creates a JBoss DNA <code>JcrConfiguration</code> instance and loads the configuration
+ from a file provided by the user interface. The method then loads the node types for each of the repositories; this could
+ have been done in the configuration, but it would have made the configuration file larger and more difficult to understand.
+ It then creates the <code>JcrEngine</code> from the configuration and starts it. Finally, it obtains the location of the
+ content files from the user interface, and imports them into the "Cars" and "Aircraft" repositories. Again, this is
+ done to keep the example simple.
+ </para>
+ <para>
+ The <code>shutdown()</code> method of the example then logs out and requests the <code>JcrEngine</code> instance shuts down and, since that may take
+ a few moments (if there are any ongoing operations or enqueued activities) awaits for it to complete the shutdown.
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+public void shutdown() throws InterruptedException, LoginException {
+ logout();
+ if (engine == null) return;
+ try {
+ // Tell the engine to shut down, and then wait up to 5 seconds for it to complete...
+ engine.shutdown();
+ engine.awaitTermination(5, TimeUnit.SECONDS);
+ } finally {
+ engine = null;
+ }
+}
+ ]]></programlisting>
+ <para>
+ A few of the other methods in the <code>RepositoryClient</code> class deal with the JAAS <code>LoginContext</code>.
+ When needed, the client will authenticate the user (by asking the user interface for a callback handler that will be called
+ when the authentication information is needed). The resulting authenticated <code>LoginContext</code> is wrapped
+ by a custom <code>javax.jcr.Credentials</code> implementation. As long as the <code>Credentials</code> implementation
+ has a <code>getLoginContext()</code> method that returns a <code>LoginContext</code> object, JBoss DNA's repository
+ implementation will use that context to create the <code>javax.jcr.Session</code>. (Of course, the <code>javax.jcr.SimpleCredentials</code>
+ can also be used to create a Session, and JBoss DNA will then attempt to use JAAS to authenticate the user given by the credentials.)
+ </para>
+ <para>
+ The <code>getNodeInfo(...)</code> method of the example is what is called when the properties and children of a particular node
+ are requested by the user interface. (In the console user interface, this happens when the user navigates the graph structure.)
+ There are really two different behaviors to this method, depending upon whether the JCR API is to be used or whether
+ the JBoss DNA Graph API is to be used. The portion that uses JCR is shown below:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+JcrRepository jcrRepository = engine.getRepository(sourceName);
+Session session = null;
+if (loginContext != null) {
+ // Could also use SimpleCredentials(username,password) too
+ Credentials credentials = new JaasCredentials(loginContext);
+ session = jcrRepository.login(credentials);
+} else {
+ session = jcrRepository.login();
+}
+try {
+ // Make the path relative to the root by removing the leading slash(es) ...
+ pathToNode = pathToNode.replaceAll("^/+", "");
+ // Get the node by path ...
+ Node root = session.getRootNode();
+ Node node = root;
+ if (pathToNode.length() != 0) {
+ if (!pathToNode.endsWith("]")) pathToNode = pathToNode + "[1]";
+ node = pathToNode.equals("") ? root : root.getNode(pathToNode);
+ }
+
+ // Now populate the properties and children ...
+ if (properties != null) {
+ for (PropertyIterator iter = node.getProperties(); iter.hasNext();) {
+ javax.jcr.Property property = iter.nextProperty();
+ Object[] values = null;
+ // Must call either 'getValue()' or 'getValues()' depending upon # of values
+ if (property.getDefinition().isMultiple()) {
+ Value[] jcrValues = property.getValues();
+ values = new String[jcrValues.length];
+ for (int i = 0; i < jcrValues.length; i++) {
+ values[i] = jcrValues[i].getString();
+ }
+ } else {
+ values = new Object[] {property.getValue().getString()};
+ }
+ properties.put(property.getName(), values);
+ }
+ }
+ if (children != null) {
+ // Figure out which children need same-name sibling indexes ...
+ Set<String> sameNameSiblings = new HashSet<String>();
+ for (NodeIterator iter = node.getNodes(); iter.hasNext();) {
+ javax.jcr.Node child = iter.nextNode();
+ if (child.getIndex() > 1) sameNameSiblings.add(child.getName());
+ }
+ for (NodeIterator iter = node.getNodes(); iter.hasNext();) {
+ javax.jcr.Node child = iter.nextNode();
+ String name = child.getName();
+ if (sameNameSiblings.contains(name)) name = name + "[" + child.getIndex() + "]";
+ children.add(name);
+ }
+ }
+} catch (javax.jcr.ItemNotFoundException e) {
+ return false;
+} catch (javax.jcr.PathNotFoundException e) {
+ return false;
+} finally {
+ if (session != null) session.logout();
+}
+ ]]></programlisting>
+ <para>
+ This code is literally just using the standard JCR API. First, it obtains a <code>javax.jcr.Session</code> instance
+ (using the available <code>LoginContext</code>), finds the desired <code>javax.jcr.Node</code>, copies the
+ properties and names of the children into collections supplied by the caller via method parameters, and
+ finally logs out of the session.
+ </para>
+ <para>
+ The JBoss DNA Graph API is actually an internal API used within the different components of JBoss DNA
+ (including the connector and sequencer frameworks), and provides low-level access to the exact same content.
+ Though we do not recommend using this API in your client applications, if you need to write a connector
+ or sequencer, you may need to know how to use the Graph API.
+ Here is the portion of the <code>getNodeInfo(...)</code> method that does the exact same operation as the JCR code
+ shown above:
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+// Use the DNA Graph API to read the properties and children of the node ...
+ExecutionContext context = loginContext != null ? this.context.create(loginContext) : this.context;
+Graph graph = engine.getGraph(context, sourceName);
+graph.useWorkspace("default");
+org.jboss.dna.graph.Node node = graph.getNodeAt(pathToNode);
+
+if (properties != null) {
+ // Now copy the properties into the map provided as a method parameter ...
+ for (Property property : node.getProperties()) {
+ String name = property.getName().getString(context.getNamespaceRegistry());
+ properties.put(name, property.getValuesAsArray());
+ }
+}
+if (children != null) {
+ // And copy the names of the children into the list provided as a method parameter ...
+ for (Location child : node.getChildren()) {
+ String name = child.getPath().getLastSegment().getString(context.getNamespaceRegistry());
+ children.add(name);
+ }
+}
+ ]]></programlisting>
+ <para>
+ Note that this code is significantly shorter than the equivalent code based upon the JCR API.
+ This is in part because the Graph API doesn't have the notion of a stateful session. But some of it also is simply
+ because the Graph API design requires less code to do the same kinds of operations.
+ </para>
+ <para>None of the other methods in the <code>RepositoryClient</code> really do anything with JBoss DNA or JCR
+ <emphasis>per se</emphasis>. Instead, they really facilitate interaction with the user interface.
+ </para>
+ <para>If we look at the <code>ConsoleInput</code> constructor, it starts the repository and a thread
+ for the user interface. At this point, the constructor returns, but the main application continues under the user interface thread.
+ When the user requests to quit, the user interface thread also shuts down the JCR repository.</para>
+ <programlisting role="JAVA"><![CDATA[
+public ConsoleInput( SequencerClient client ) {
+ try {
+ client.startRepositories();
+
+ System.out.println(getMenu());
+ Thread eventThread = new Thread(new Runnable() {
+ private boolean quit = false;
+ public void run() {
+ try {
+ while (!quit) {
+ // Display the prompt and process the requested operation ...
+ }
+ } finally {
+ try {
+ // Terminate ...
+ client.shutdown();
+ } catch (Exception err) {
+ System.out.println("Error shutting down repository: "
+ + err.getLocalizedMessage());
+ err.printStackTrace(System.err);
+ }
+ }
+ }
+ });
+ eventThread.start();
+ } catch (Exception err) {
+ System.out.println("Error: " + err.getLocalizedMessage());
+ err.printStackTrace(System.err);
+ }
+}
+ ]]></programlisting>
+ <para>At this point, we've reviewed all of the interesting code in the example application related to JBoss DNA. However, feel free
+ to play with the application, trying different things.
+ </para>
+ </sect1>
+ <sect1 id="repository_example_whats_next">
+ <title>What's next</title>
+ <para>
+ This chapter walked through running the repository example and looked at the example code. This example allowed you to walk
+ through multiple repositories, including one whose content was federated from multiple other repositories.
+ This was a very simplistic example that only took a few minutes to run.
+ </para>
+ <para>
+ In the <link linkend="conclusion">next chapter</link> we'll wrap up by summarizing what we've learned about JBoss DNA
+ and provide information about where you can find out more about JBoss DNA.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/content/repository_example.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,315 @@
+<?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 chapter 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="sequencer_example">
+ <title>The Sequencer Example</title>
+ <para>
+ The previous chapter walked through the process of downloading and building the examples.
+ This chapter will focus on the sequencer example, showing how to run the example and then walking through the code
+ to describe what it's doing.
+ </para>
+ <sect1 id="running_sequencer_example">
+ <title>Running the sequencing example</title>
+ <para>The sequencing example consists of a client application that sets up an in-memory JCR repository and that allows a user to
+ upload files into that repository. The client also sets up the DNA services with two sequencers so that if any of the
+ uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will automatically extract the image's metadata (e.g., image
+ format, physical size, pixel density, etc.) and store that in the repository. Alternatively, if the uploaded file
+ is an MP3 audio file, DNA will extract some of the ID3 metadata (e.g., the author, title, album, year and comment)
+ and store that in the repository.</para>
+ <para>
+ To run the client application, go to the <code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code>
+ directory and type <code>./run.sh</code>. You should see the command-line client and its menus in your terminal:
+ <figure id="xample-sequencer-cli-client">
+ <title>Example client</title>
+ <graphic align="center" scale="100" fileref="example-sequencer-client.png"/>
+ </figure>
+ From this menu, you can upload a file into the repository, search for media in the repository, print sequencing statistics,
+ or quit the application.</para>
+ <para>
+ The first step is to upload one of the example images. If you type 'u' and press return, you'll be prompted to supply the
+ path to the file you want to upload. Since the application is running from within the
+ <code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code> directory, you can specify any of the files
+ in that directory without specifying the path:
+ <figure id="example-sequencer-upload">
+ <title>Uploading an image using the example client</title>
+ <graphic align="center" scale="100" fileref="example-sequencer-upload.png"/>
+ </figure>
+ You can specify any fully-qualified or relative path. The application will notify you if it cannot find the file you
+ specified. The example client configures JBoss DNA to sequence MP3 audio files, Java source files, or image files with one of
+ the following extensions (technically, nodes that have names ending in the following):
+ <code>jpg</code>, <code>jpeg</code>, <code>gif</code>, <code>bmp</code>, <code>pcx</code>, <code>png</code>,
+ <code>iff</code>, <code>ras</code>, <code>pbm</code>, <code>pgm</code>, <code>ppm</code>, and <code>psd</code>.
+ Files with other extensions in the repository path will be ignored. For your convenience, the example provides several
+ files that will be sequenced (<code>caution.png</code>, <code>caution.jpg</code>, <code>caution.gif</code>, and
+ <code>sample1.mp3</code>) and one image that will not be sequenced (<code>caution.pict</code>). Feel free to try other files.
+ </para>
+ <para>
+ After you have specified the file you want to upload, the example application asks you where in the repository you'd like to
+ place the file. (If you want to use the suggested location, just press <code>return</code>.) The client application
+ uses the JCR API to upload the file to that location in the repository, creating any nodes (of type <code>nt:folder</code>)
+ for any directories that don't exist, and creating a node (of type <code>nt:file</code>) for the file. And, per the JCR specification,
+ the application creates a <code>jcr:content</code> node (of type <code>nt:resource</code>) under the file node.
+ The file contents are placed on this <code>jcr:content</code> node in the <code>jcr:data</code> property. For example, if you specify
+ <code>/a/b/caution.png</code>, the following structure will be created in the repository:</para>
+ <programlisting><![CDATA[
+/a (nt:folder)
+ /b (nt:folder)
+ /caution.png (nt:file)
+ /jcr:content (nt:resource)
+ @jcr:data = {contents of the file}
+ @jcr:mimeType = {mime type of the file}
+ @jcr:lastModified = {now}
+]]></programlisting>
+ <para>Other kinds of files are treated in a similar way.</para>
+ <para>When the client uploads the file using the JCR API, DNA gets notified of the changes, consults the sequencers to see whether
+ any of them are interested in the new or updated content, and if so runs those sequencers. The image sequencer processes image
+ files for metadata, and any metadata found is stored under the <code>/images</code> branch of the repository. The MP3 sequencer
+ processes MP3 audio files for metadata, and any metadata found is stored under the <code>/mp3s</code>
+ branch of the repository. And metadata about Java classes are stored under the <code>/java</code> area of the repository.
+ All of this happens asynchronously, so any DNA activity doesn't impede or slow down the client activities.
+ </para>
+ <para>So, after the file is uploaded, you can search the repository for the image metadata using the "s" menu option:
+ <figure id="example-sequencer-search">
+ <title>Searching for media using the example client</title>
+ <graphic align="center" scale="100" fileref="example-sequencer-search.png"/>
+ </figure>
+ Here are the search results after the <code>sample1.mp3</code> audio file has been uploaded (to the <code>/a/b/sample1.mp3</code> location):
+ <figure id="example-sequencer-search-with-mp3">
+ <title>Searching for media using the example client</title>
+ <graphic align="center" scale="100" fileref="example-sequencer-search-with-mp3.png"/>
+ </figure>
+ You can also display the sequencing statistics using the "d" menu option:
+ <figure id="example-sequencer-statistics">
+ <title>Sequencing statistics using the example client</title>
+ <graphic align="center" scale="100" fileref="example-sequencer-statistics.png"/>
+ </figure>
+ These stats show how many nodes were sequenced, and how many nodes were skipped because they didn't apply to the sequencer's
+ criteria.
+ </para>
+ <note>
+ <para>There will probably be more nodes skipped than sequenced, since there are more <code>nt:folder</code> and <code>nt:resource</code>
+ nodes than there are <code>nt:file</code> nodes with acceptable names.</para>
+ </note>
+ <para>You can repeat this process with other files. Any file that isn't an image or MP3 files (as recognized by the sequencing configurations
+ that we'll describe later) will not be sequenced.</para>
+ </sect1>
+ <sect1 id="example_application_review">
+ <title>Reviewing the example application</title>
+ <para>Recall that the example application consists of a client application that sets up an in-memory JCR repository and
+ that allows a user to upload files into that repository. The client also sets up the DNA services with an image sequencer so
+ that if any of the uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will automatically extract the image's
+ metadata (e.g., image format, physical size, pixel density, etc.) and store that in the repository. Or, if the client uploads
+ MP3 audio files, the title, author, album, year, and comment are extracted from the audio file and stored in the repository.</para>
+ <para>
+ The example is comprised of 5 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
+ <programlisting><![CDATA[
+ org/jboss/example/dna/sequencers/ConsoleInput.java
+ /ContentInfo.java
+ /JavaInfo.java
+ /MediaInfo.java
+ /SequencingClient.java
+ /UserInterface.java
+ ]]></programlisting>
+ <para><code>SequencingClient</code> is the class that contains the main application. <code>ContentInfo</code> is a simple class
+ that encapsulate metadata generated by the sequencers and accessed by this example application, and there are two subclasses:
+ <code>MediaInfo</code> encapsulates metadata about media (image and MP3) files, while <code>JavaInfo</code> is a subclass
+ encapsulating information about a Java class. The client accesses the content from the repository and represent the
+ information using instances of <code>ContentInfo</code> (and its subclasses) and then passing them to the <code>UserInterface</code>.
+ <code>UserInterface</code> is an interface with methods that will be called at runtime to
+ request data from the user. <code>ConsoleInput</code> is an implementation of this that creates a text user interface,
+ allowing the user to operate the client from the command-line. We can easily create a graphical implementation of
+ <code>UserInterface</code> at a later date. We can also create a mock implementation for testing purposes that simulates
+ a user entering data. This allows us to check the behavior of the client automatically using conventional JUnit test cases,
+ as demonstrated by the code in the <code>src/test/java</code> directory:</para>
+ <programlisting><![CDATA[
+ org/jboss/example/dna/sequencers/SequencingClientTest.java
+ /MockUserInterface.java
+ ]]></programlisting>
+ <para>If we look at the <code>SequencingClient</code> code, there are a handful of methods that encapsulate the various activities.</para>
+ <note>
+ <para>Some of the code samples included in this book have had some of the error handling and comments removed so that
+ the code is more readable and concise.</para>
+ </note>
+ <para>The <code>main(String[] argv)</code> method is of course the method that is executed when the application is run. This code
+ creates the JBoss DNA configuration using the programmatic style.
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+// Set up the JAAS provider (IDTrust) and a policy file (which defines the "dna-jcr" login config name)
+IDTrustConfiguration idtrustConfig = new IDTrustConfiguration();
+try {
+ idtrustConfig.config("security/jaas.conf.xml");
+} catch (Exception ex) {
+ throw new IllegalStateException(ex);
+}
+
+// Create the configuration.
+String repositoryId = "content";
+String workspaceName = "default";
+JcrConfiguration config = new JcrConfiguration();
+// Set up the in-memory source where we'll upload the content and where the sequenced output will be stored ...
+config.repositorySource("store")
+ .usingClass(InMemoryRepositorySource.class)
+ .setDescription("The repository for our content")
+ .setProperty("defaultWorkspaceName", workspaceName);
+// Set up the JCR repository to use the source ...
+config.repository(repositoryId)
+ .addNodeTypes("sequencing.cnd")
+ .setSource("store")
+ .setOption(JcrRepository.Option.JAAS_LOGIN_CONFIG_NAME, "dna-jcr");
+// Set up the image sequencer ...
+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");
+// Set up the MP3 sequencer ...
+config.sequencer("MP3 Sequencer")
+ .usingClass("org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer")
+ .loadedFromClasspath()
+ .setDescription("Sequences mp3 files to extract the id3 tags of the audio file")
+ .sequencingFrom("//(*.mp3[*])/jcr:content[@jcr:data]")
+ .andOutputtingTo("/mp3s/$1");
+// Set up the Java source file sequencer ...
+config.sequencer("Java Sequencer")
+ .usingClass("org.jboss.dna.sequencer.java.JavaMetadataSequencer")
+ .loadedFromClasspath()
+ .setDescription("Sequences Java files to extract the AST structure of the Java source code")
+ .sequencingFrom("//(*.java[*])/jcr:content[@jcr:data]")
+ .andOutputtingTo("/java/$1");
+
+// Now start the client and tell it which repository and workspace to use ...
+SequencingClient client = new SequencingClient(config, repositoryId, workspaceName);
+client.setUserInterface(new ConsoleInput(client));
+ ]]></programlisting>
+ <para>
+ The first block sets up the JAAS provider to be the IDTrust library and a policy file that defines the "dna-jcr" JAAS configuration.
+ </para>
+ <para>
+ The second block of code configures the <code>JcrConfiguration</code> and sets up the "store" source, the "content" repository,
+ and three sequencers. Again, this is done via the programmatic style. An alternative would be to load the entire configuration
+ from a configuration file or from an existing configuration repository. (The repository example shown in the
+ <link linkend="repository_example">next chapter</link> shows how to load the configuration from a file.)
+ </para>
+ <para>
+ The third block simply instantiates the <code>SequencingClient</code> class, passing the configuration and the name of the repository
+ and workspace, and finally sets the user interface (which then executes its behavior, which we'll see below).
+ </para>
+ <para>
+ The <code>startRepository()</code> method builds the <code>JcrEngine</code> component from the configuration, starts the engine,
+ and obtains the JCR <code>javax.jcr.Repository</code> instance that the client will use. Note that the client has not yet
+ obtained a <code>javax.jcr.Session</code> instance, since this will be done each time the client needs to access content from
+ the repository. (This is actually a common practice according to the JCR specification, since Sessions are intended to be
+ very lightweight.)
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+public void startRepository() throws Exception {
+ if (this.repository == null) {
+ try {
+ // Start the DNA engine ...
+ this.engine = this.configuration.build();
+ this.engine.start();
+
+ // Now get the JCR repository instance ...
+ this.repository = this.engine.getRepository(repositoryName);
+ } catch (Exception e) {
+ this.repository = null;
+ throw e;
+ }
+ }
+}
+ ]]></programlisting>
+ <para>The <code>shutdownRepository()</code> method requests the <code>JcrEngine</code> instance shuts down and, since that may take
+ a few moments (if there are any ongoing operations or enqueued activities) awaits for it to complete the shutdown.
+ </para>
+ <programlisting role="JAVA"><![CDATA[
+public void shutdownRepository() throws Exception {
+ if (this.repository != null) {
+ try {
+ this.engine.shutdown();
+ this.engine.awaitTermination(4, TimeUnit.SECONDS);
+ } finally {
+ this.repository = null;
+ }
+ }
+}
+ ]]></programlisting>
+ <para>None of the other methods really do anything with JBoss DNA <emphasis>per se</emphasis>. Instead, they merely work with the repository
+ using the JCR API.</para>
+ <para>If we look at the <code>ConsoleInput</code> constructor, it starts the repository and a thread
+ for the user interface. At this point, the constructor returns, but the main application continues under the user interface thread.
+ When the user requests to quit, the user interface thread also shuts down the JCR repository.</para>
+ <programlisting role="JAVA"><![CDATA[
+public ConsoleInput( SequencerClient client ) {
+ try {
+ client.startRepository();
+
+ System.out.println(getMenu());
+ Thread eventThread = new Thread(new Runnable() {
+ private boolean quit = false;
+ public void run() {
+ try {
+ while (!quit) {
+ // Display the prompt and process the requested operation ...
+ }
+ } finally {
+ try {
+ // Terminate ...
+ client.shutdownRepository();
+ } catch (Exception err) {
+ System.out.println("Error shutting down sequencing service and repository: "
+ + err.getLocalizedMessage());
+ err.printStackTrace(System.err);
+ }
+ }
+ }
+ });
+ eventThread.start();
+ } catch (Exception err) {
+ System.out.println("Error: " + err.getLocalizedMessage());
+ err.printStackTrace(System.err);
+ }
+}
+ ]]></programlisting>
+ <para>At this point, we've reviewed all of the interesting code in the example application related to JBoss DNA. However, feel free
+ to play with the application, trying different things.</para>
+ </sect1>
+ <sect1 id="using_dna_whats_next">
+ <title>What's next</title>
+ <para>
+ This chapter walked through running the sequencer example and looked at the example code. With the sequencer client, you could upload files into a
+ JCR repository, while JBoss DNA automatically sequenced the image, MP3, or Java source files you uploaded, extracted the metadata from the
+ files, and stored that metadata inside the repository.
+ </para>
+ <para>
+ In the <link linkend="repository_example">next chapter </link> we'll do the same for the repository example.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/content/sequencer_example.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Deleted: trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -1,576 +0,0 @@
-<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="understanding_dna">
- <title>Understanding JBoss DNA</title>
- <sect1 id="jboss_dna_overview">
- <title>Overview</title>
- <para>JBoss DNA is a repository and set of tools that make it easy to capture, version, analyze, and understand the
- fundamental building blocks of information. As models, service and process definitions, schemas, source code, and other
- artifacts are added to the repository, JBoss DNA "sequences" the makeup of these components and extracts their structure
- and interdependencies. The JBoss DNA web application will allow end users to access, visualize, and edit this information in
- the terminology and structure they are familiar with. Such domain-specific solutions can be easily created with little or
- no programming.</para>
- <para> JBoss DNA supports the Java Content Repository (JCR) standard and is able to provide a single integrated view of
- multiple repositories, external databases, services, and applications, ensuring that JBoss DNA has access to the latest
- and most reliable master data. For instance, DNA could provide in a single view valuable insight into the business
- processes and process-level services impacted by a change to in an intermediary web server operation defined via WSDL.
- Similarly, a user could quickly view and navigate the dependencies between the data source models and transformation
- information stored within a content repository, the code base stored within a version control system, and the database
- schemas used by an application.</para>
- </sect1>
- <sect1 id="architecture">
- <title>Architecture</title>
- <para>The planned architecture for JBoss DNA consists of several major components that will be built on top of standard APIs,
- including JCR, JDBC, JNDI and HTTP. The goal is to allow these components to be assembled as needed and add value on top
- of other DNA components or third-party systems that support these standard APIs. Not all of these components exist
- yet - at the moment we're focusing on completing our JCR-compliant implementation using our connector framework.</para>
- <mediaobject>
- <imageobject role="fo">
- <imagedata align="center" fileref="dna-architecture.png" />
- </imageobject>
- <imageobject role="html">
- <imagedata align="center" fileref="dna-architecture.png" />
- </imageobject>
- </mediaobject>
- <para>
- Let's go over each of these components, starting from the bottom of the diagram:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">DNA Connectors</emphasis>
- are used to communicate with these external sources of information, whether there's one source (like a database) in
- which all of the content is stored, or information is being federated from multiple sources. The connector's
- job is to interact with the external source and map the source's information into the lower-level graph language used by
- JBoss DNA. Connectors also may optionally participate in distributed transactions by exposing an XAResource.
- In summary, then, the connector API isolates all of the other components from how the graph are persisted.
- We've built a number of connectors already, but we're always interested in adding more. Or, you could write your own,
- since we've designed the connector API to be as straightforward as possible.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Federation</emphasis>
- is actually a special repository connector that accesses information from multiple other sources via connectors,
- making all this information look like it is part of a single, unified repository. Because it is a connector,
- it can be used wherever connectors can be used. And because it uses connectors, the federation connector
- makes it possible to integrate a wide variety of external systems, like other JCR
- repositories, databases, applications, and services.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA JCR</emphasis>
- is an implementation of the JCR API that accesses the content from a single connector. Our implementation has come a long
- way, and is nearly Level 1 and Level 2 compliant. Finishing the remaining features, including search
- and query, are major objectives of our next release.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Sequencers</emphasis>
- are pluggable components that automatically process content (typically files) that are uploaded into the repository,
- looking for useful structure and information in that content. When a file is uploaded to the repository, JBoss DNA automatically
- figures out which sequencer(s) should be run, and then runs them. Each sequencer, then, extracts the meaningful information
- from the file's content and places that structure in the repository. Once this information is in
- the repository, it can be viewed, edited, analyzed, searched, and related to other content. DNA defines a Java
- interface that sequencers must implement. DNA sequencers operate upon any JCR-compliant repository.
- We have a number of sequencers, but plan on adding more over time. Like connectors, the Sequencer API makes it very
- simple to write sequencers for your own file types.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Analyses</emphasis>
- are similar to sequencers, except they process the graph structure rather than uploaded files. You can think of them
- as report generators, where they process some area of the repository and generate output. The output doesn't take the
- form of a document or file, but rather more graph content that is then stored in the repository, where it can be accessed
- and searched just like any other content. We're still figuring out how to best make analyzers easy to write and use,
- and have been focused on other aspects of the architecture. But we're planning on using analyzers for dependency,
- similarity, and statistical analyses.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Maven</emphasis>
- is a classloader library compatible with Maven 2 project dependencies. This allows the creation of Java ClassLoader
- instances using Maven 2 style paths, and all dependencies are transitively managed and included. This exists but is
- still immature.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The remaining parts of the architecture haven't yet been started, but they service important purposes for a complete metadata
- repository system.
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">DNA Eclipse Plugins</emphasis>
- enable Eclipse users to access the contents of a JBoss DNA repository. This is a planned component that may be started soon.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA JDBC Driver</emphasis>
- provides a driver implementation, allowing JDBC-aware applications to connect to and use a JBoss DNA repository.
- This is a planned component on our roadmap.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Remote JCR</emphasis>
- is a client-side component for accessing remote JCR repositories.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Web Application</emphasis>
- is used by end users and domain experts to visualize, search, edit, change and tag the repository content. The web
- application uses views to define how different types of information are to be presented and edited in
- domain-specific ways. The goal is that this web application is easily customized and branded for inclusion into
- other solutions and application systems. The DNA Web Application operates upon any JCR-compliant repository,
- although it does rely upon the DNA analysis and templating services.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Publishing Server</emphasis>
- allows content to be downloaded, uploaded, and edited using the Atom Publishing Protocol. With the DNA Publishing
- Server, the content of the repository can easily be created, read, edited, and deleted using the standard HTTP
- operations of POST, GET, PUT, and DELETE (respectively). More and more tools are being created that support working
- with Atom Publishing servers. The DNA Publishing Server operates upon any JCR-compliant repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA WebDAV Server</emphasis>
- allows clients such as Microsoft Windows and Apple OS X to connect to, read, and edit the content in the repository
- using the WebDAV standard. WebDAV is an extension of HTTP, so web browsers are able to access the content
- served by a WebDAV compliant server. The DNA WebDAV Server operates upon any JCR-compliant repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">DNA Views</emphasis>
- are definitions of how types of information are to be presented in a user interface to allow for creation, reading,
- editing, and deletion of information. DNA view definitions consist of data stored in a JCR repository, and as such
- views can be easily added, changed or removed entirely by using the DNA Web Application, requiring no programming.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- Continue reading the rest of this chapter for more detail about the
- <link linkend="sequencers">sequencing framework</link> available in this release, or the <link linkend="federation">federation engine</link>
- and <link linkend="federation_connectors">connectors</link>. Or, skip to the <link linkend="downloading_and_running">examples</link>
- to see how to start using JBoss DNA &versionNumber; today.
- </para>
- </sect1>
- <sect1 id="sequencers">
- <title>Sequencing content</title>
- <para> The current JBoss DNA release contains a sequencing framework that is designed to sequence data (typically files)
- stored in a JCR repository to automatically extract meaningful and useful information. This additional information is then
- saved back into the repository, where it can be accessed and used.</para>
- <para> In other words, you can just upload various kinds of files into a JCR repository, and DNA automatically processes
- those files to extract meaningful structured information. For example, load DDL files into the repository, and let
- sequencers extract the structure and metadata for the database schema. Load Hibernate configuration files into the
- repository, and let sequencers extract the schema and mapping information. Load Java source into the repository, and let
- sequencers extract the class structure, JavaDoc, and annotations. Load a PNG, JPEG, or other image into the repository,
- and let sequencers extract the metadata from the image and save it in the repository. The same with XSDs, WSDL, WS
- policies, UML, MetaMatrix models, etc.</para>
- <para>
- JBoss DNA sequencers sit on top of existing JCR repositories (including federated repositories) - they basically extract
- more useful information from what's already stored in the repository. And they use the existing JCR event and versioning system. Each
- sequencer typically processes a single kind of file format or a single kind of content. </para>
- <para>The following sequencers are included in JBoss DNA:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">Image sequencer</emphasis>
- - A sequencer that processes the binary content of an image file, extracts the metadata for the image, and then
- writes that image metadata to the repository. It gets the file format, image resolution, number of bits per pixel
- (and optionally number of images), comments and physical resolution from JPEG, GIF, BMP, PCX, PNG, IFF, RAS, PBM,
- PGM, PPM, and PSD files. (This sequencer may be improved in the future to also extract EXIF metadata from JPEG
- files; see <ulink url="http://jira.jboss.org/jira/browse/DNA-26">DNA-26</ulink>.)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">MP3 sequencer</emphasis>
- - A sequencer that processes the contents of an MP3 audio file, extracts the metadata for the file, and then
- writes that image metadata to the repository. It gets the title, author, album, year, and comment.
- (This sequencer may be improved in the future to also extract other ID3 metadata from other audio file formats; see
- <ulink url="http://jira.jboss.org/jira/browse/DNA-66">DNA-66</ulink>.)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">ZIP Archive Sequencer</emphasis>
- - Process ZIP archive files to extract (explode) the contents into the repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Java Source File Sequencer</emphasis>
- - Process Java source files to extract the class structure (including annotations) into the repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">XML File Sequencer</emphasis>
- - Process XML files to extract the structure into the repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Microsoft Office File Sequencer</emphasis>
- - Process Microsoft Office documents, spreadsheets, and presentation files to extract their basic structure.
- For example, the sequencer extracts the outline of a document, or the title and outline of a presentation.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">JCR Compact Node Definition (CND) File Sequencer</emphasis>
- - Process the CND files defined by JCR, extracting the various node types with their property definitions and child
- node definitions.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- As the community develops additional sequencers, they will also be included in JBoss DNA. Some of those that have been
- identified as being useful include:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">Data Definition Language (DDL) Sequencer</emphasis>
- - Process various dialects of DDL, including that from Oracle, SQL Server, MySQL, PostgreSQL, and others. May need
- to be split up into a different sequencer for each dialect. This sequencer is being developed as part of a
- Google Summer of Code 2009 project. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-26">DNA-26</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">XML Schema Document (XSD) Sequencer</emphasis>
- - Process XSD files and extract the various elements, attributes, complex types, simple types, groups, and other
- information. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-32">DNA-32</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Web Service Definition Language (WSDL) Sequencer</emphasis>
- - Process WSDL files and extract the services, bindings, ports, operations, parameters, and other information. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-33">DNA-33</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Hibernate File Sequencer</emphasis>
- - Process Hibernate configuration (cfg.xml) and mapping (hbm.xml) files to extract the configuration and mapping
- information. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-61">DNA-61</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">XML Metadata Interchange (XMI) Sequencer</emphasis>
- - Process XMI documents that contain UML models or models using another metamodel, extracting the model structure
- into the repository. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-31">DNA-31</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Java Archive (JAR) Sequencer</emphasis>
- - Process JAR files to extract (explode) the contents into the classes and file resources. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-64">DNA-64</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Java Class File Sequencer</emphasis>
- - Process Java class files (bytecode) to extract the class structure (including annotations) into the repository.
- (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-62">DNA-62</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">PDF Sequencer</emphasis>
- - Process PDF files to extract the document metadata, including table of contents. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-50">DNA-50</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Maven 2 POM Sequencer</emphasis>
- - Process Maven 2 Project Object Model (POM) files to extract the project information, dependencies, plugins, and
- other content. (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-24">DNA-24</ulink>
- )
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">MP3 and MP4 Sequencer</emphasis>
- - Process MP3 and MP4 audio files to extract the name of the song, artist, album, track number, and other metadata.
- (See
- <ulink url="http://jira.jboss.org/jira/browse/DNA-30">DNA-30</ulink>
- )
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The
- <link linkend="using_dna">examples</link>
- in this book go into more detail about how sequencers are managed and used, and
- <link linkend="custom_sequencers">Chapter 5</link>
- goes into detail about how to write custom sequencers.
- </para>
- </sect1>
- <sect1 id="federation">
- <title>JCR and federated repositories</title>
- <para>There is a lot of information stored in many of different places: databases, repositories, SCM systems,
- registries, file systems, services, etc. The purpose of the federation engine is to allow applications to use the JCR API
- to access that information as if it were all stored in a single JCR repository, but to really leave the information where
- it is.</para>
- <para>Why not just copy or move the information into a JCR repository? Moving it is probably pretty difficult, since most
- likely existing applications rely upon that information being where it is. All of those applications
- would break or have to change. And copying the information means that we'd have to continually synchronize the changes.
- This not only is a lot of work, but it often creates issues with knowing which information is accurate.
- </para>
- <para>The JBoss DNA allows lets us leave the information where it is, yet provide access to that information to new applications through
- the JCR API. As the existing applications update the information in the original systems, applications using JBoss DNA also see
- these updates. JCR clients even get the benefit of using JCR observation to be notified of the changes. And if a JBoss DNA repository is
- configured to allow updates, client applications can change the information in the repository and JBoss DNA will propagate
- those changes down to the original source.</para>
- <sect2 id="repository-connectors">
- <title>Connecting to information sources</title>
- <para>
- JBoss DNA uses connectors to interact with different information sources to get at the content
- in those systems. We already have some connectors, including:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">In-Memory Connector</emphasis>
- - Uses a Map instance as a repository. This is a simple connector that works really well for small and transient graphs.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">JBoss Cache Connector</emphasis>
- - Uses a JBoss Cache instance as a repository. JBoss Cache is a powerful cache capable of persisting the information
- and being clustered for concurrent use by multiple processes.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Federation Connector</emphasis>
- - Creates a single repository by accessing and federating the information in multiple other repository sources.
- This is a powerful connector that is discussed in more detail in the <link linkend="federated_repositories">next section</link>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">File System Connector</emphasis>
- - Expose the files and directories on a file system through JCR.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">JPA-based Storage Connector</emphasis>
- - Store and access information in a relational database through JPA. Also useful for persisting information in the federated
- repository not stored elsewhere.
- </para>
- </listitem>
- </itemizedlist>
- <para>We're working on a few other connectors:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">JDBC Metadata Connector</emphasis>
- - Connect to relational databases via JDBC and expose their schema as content in a repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">SVN Connector</emphasis>
- - Interact with Subversion software configuration management (SCM) repositories to expose the managed resources
- through JCR. Consider using the
- <ulink url="http://svnkit.com/">SVNkit</ulink>
- (dual license) library for an API into Subversion.
- </para>
- </listitem>
- </itemizedlist>
- <para>And even more connectors that are planned:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">JCR Repository Connector</emphasis>
- - Connect to and interact with other JCR repositories.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Maven 2 Repository Connector</emphasis>
- - Access and expose the contents of a Maven 2 repository (either on the local file system or via HTTP) through
- JCR.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">UDDI Connector</emphasis>
- - Interact with UDDI registries to integrate their content into a repository.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">CVS Connector</emphasis>
- - Interact with CVS software configuration management (SCM) repositories to expose the managed resources through
- JCR.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Distributed Database Connector</emphasis>
- - Store and access information in a
- <ulink url="http://www.hypertable.org/">Hypertable</ulink>
- or
- <ulink url="http://hadoop.apache.org/hbase/">HBase</ulink>
- distributed databases. Also useful for persisting information in the federated repository not stored elsewhere.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- If the connectors allow the information they contribute to be updated, they must provide an
- <code>XAResource</code>
- implementation that can be used with a Java Transaction Service. Connectors that provide read-only access need not
- provide an implementation.
- </para>
- <para>
- Also, connectors talk to
- <emphasis>sources</emphasis>
- of information, and it's quite likely that the same connector is used to talk to different sources. Each source contains
- the configuration details (e.g., connection information, location, properties, options, etc.) for working with that
- particular source, as well as a reference to the connector that should be used to establish connections to the source.
- And of course, sources can be added or removed without having to stop and restart the federated repository.
- </para>
- </sect2>
- <sect2 id="federated_repositories">
- <title>Federated repositories</title>
- <para> The federation connector works by effectively building up a single graph by querying each source and merging or
- unifying the responses. This information is cached, which improves performance, reduces the number of (potentially
- expensive) remote calls, reduces the load on the sources, and helps mitigate problems with source availability. As
- clients interact with the repository, this cache is consulted first. When the requested portion of the graph (or
- "subgraph") is contained completely in the cache, it is retuned immediately. However, if any part of the requested
- subgraph is not in the cache, each source is consulted for their contributions to that subgraph, and any results are
- cached.</para>
- <para> This basic flow makes it possible for the federated repository to build up a local cache of the integrated graph
- (or at least the portions that are used by clients). In fact, the federated repository caches information in a manner
- that is similar to that of the Domain Name System (DNS). As sources are consulted for their contributions, the source
- also specifies whether it is the authoritative source for this information (some sources that are themselves federated
- may not be the information's authority), whether the information may be modified, the time-to-live (TTL) value (the time
- after which the cached information should be refreshed), and the expiration time (the time after which the cached
- information is no longer valid). In effect, the source has complete control over how the information it contributes is
- cached and used.</para>
- <para>
- The federated repository also needs to incorporate
- <emphasis>negative caching</emphasis>
- , which is storage of the knowledge that something does not exist. Sources can be configured to contribute information
- only below certain paths (e.g.,
- <code>/A/B/C</code>
- ), and the federation engine can take advantage of this by never consulting that source for contributions to information
- on other paths. However, below that path, any negative responses must also be cached (with appropriate TTL and expiry
- parameters) to prevent the exclusion of that source (in case the source has information to contribute at a later time)
- or the frequent checking with the source.
- </para>
- </sect2>
- <sect2 id="federation_queries">
- <title>Searching and querying</title>
- <para> The JBoss DNA federated repository will support queries against the integrated and unified graph. In some
- situations the query can be determined to apply to a single source, but in most situations the query must be planned
- (and possibly rewritten) such that it can be pushed down to all the appropriate sources. Also, the cached results must
- be consulted prior to returning the query results, as the results from one source might have contributions from another
- source.</para>
- <para>Searching the whole federated repository is also important. This allows users to simply supply a handful of
- search terms, and to get results that are ranked based upon how close each result is to the search terms. (Searching is
- very different from querying, which involves specifying the exact semantics of what is to be searched and how the
- information is to be compared.) JBoss DNA will incorporate a search engine (e.g., likely to be Lucene) and will populate
- the engine's indexes using the federated content and the cached information. Notifications of changing information will
- be reflected in the indexes, but some sources may want to explicitly allow or disallow periodic crawling of their
- content.</para>
- </sect2>
- <sect2 id="federation_updates">
- <title>Updating content</title>
- <para>
- The JBoss DNA federated repositories also make it possible for client applications to make changes to the unified graph
- within the context of distributed transactions. According to the JCR API, client applications use the Java Transaction
- API (JTA) to control the boundaries of their transactions. Meanwhile, the federated repository uses a
- <ulink url="http://www.jboss.org/jbosstm/">distributed transaction service</ulink>
- to coordinate the XA resources provided by the connectors.
- </para>
- <para> It is quite possible that clients add properties to nodes in the unified graph, and that this information cannot be
- handled by the same underlying source that contributed to the node. In this case, the federated repository can be
- configured with a fallback source that will be used used to store this "extra" information.</para>
- <para>
- It is a goal that non-XA sources (i.e., sources that use connectors without XA resources) can participate in distributed
- transactions through the use of
- <emphasis>compensating transactions</emphasis>
- . Because the JBoss DNA federation engine implements the JCR observation system, it is capable of recording all of the
- changes made to the distributed graph (and those changes sent to each updatable source). Therefore, if a non-XA source
- is involved in a distributed transaction that must be rolled back, any changes made to non-XA sources can be undone. (Of
- course, this does not make the underlying source transactional: non-transactional sources still may expose the interim
- changes to other clients.)
- </para>
- </sect2>
- <sect2 id="federation_events">
- <title>Observing changes</title>
- <para> The JCR API supports observing a repository to receive notifications of additions, changes and deletions of nodes
- and properties. The JBoss DNA federated repository will support this API through two primary means.</para>
- <para> When the changes are made through the federated repository, the JBoss DNA federation engine is well aware of the
- set of changes that have been (or are being) made to the unified graph. These events are directly propagated to
- listeners.</para>
- <para> Sources have the ability to publish events, making it possible for the JBoss DNA federation engine and clients that
- have registered listeners to be notified of changes in the information managed by that source. These events are first
- processed by the federation engine and possibly altered based upon contributions from other sources. (The federation
- engine also uses these events to update or purge information in the cache, which may add to the event set.) The
- resulting (and possibly altered) event set is then sent to all client listeners.</para>
- </sect2>
- </sect1>
-</chapter>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,157 @@
+<?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 chapter 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="use_cases">
+ <title>JBoss DNA Use Cases</title>
+ <para>There are lots of ways to use JBoss DNA in your own applications, but this chapter attempts to show some representative
+ scenarios that take advantage of JBoss DNA's support for the JCR API as well as the federation, integration, and sequencing
+ capabilities.
+ </para>
+ <sect1 id="service_repository">
+ <title>Service repository</title>
+ <para>
+ In a SOA environment, one important component is a service registry that provides versioned storage of all the artifacts
+ that describe the services, their capabilities/restrictions, and the policies that surround them. Service repositories
+ contain information that define the services and their message models, ownership, availability, security requirements/abilities, auditing,
+ funding, monitoring, provisioning, provenance, usage, discovery mechanism, configuration, documentation, relationships
+ to other services, classification taxonomies, ontologies, and many other important aspects.
+ </para>
+ <para>
+ A JCR repository provides an excellent starting point for a service repository. The ability to store a wide range of
+ content, ranging from structured information to documents, means that a JCR repository can offer the flexibility
+ to manage and organize the information while maintaining the ability to adapt the structure and schema as needs evolve
+ over time.
+ </para>
+ <para>
+ A service repository will contain lots of information represented in different forms, and it's important that the repository
+ make it easy for users to quickly find what they need. Organization of the information (probably in multiple hierarchies and with tags)
+ is important, but more important is the ability for users to use simple searching (or more advanced queries) to return ranked
+ results that match the criteria. For search to be effective, it is important that the repository understand the different
+ kinds of artifacts that are uploaded and the information they contain.
+ </para>
+ <para>
+ JCR repositories are naturally searchable and queryable, but also can be used to integrate a taxonomy (or folksonomic tags)
+ with the content, allowing the same content to be presented in different hierarchical classifications.
+ But JBoss DNA capabilities also offer a great advantage, since any file that is uploaded can be automatically sequenced and processed
+ to extract information that's meaningful and useful but often locked up within the file. For example, when a WSDL file is uploaded,
+ the appropriate sequencer(s) process the file and extract and stores in the repository the structured information describing the types,
+ message structures, operations, port types, bindings, and services found within the WSDL file.
+ When an XML Schema Document is uploaded, JBoss DNA can do the same for the schema's complex and simple types, element and attribute
+ declarations, model groups, namespaces, imports, includes, annotations, etc. And JBoss DNA can do the same for the various policy files,
+ resource declarations, documentation, presentations, ontologies, etc.
+ </para>
+ <para>
+ It is also desirable that the service registry can provide accurate and up-to-date information about where the services are deployed
+ and their current health. The best way to do this would be to access this information directly from the other components of the SOA,
+ such as the Enterprise Service Bus and the management/monitoring system. JBoss DNA connectors might allow the service registry
+ to access an ESB to discover which services are deployed, which are running, and automatically annotate the services in the registry
+ with this dynamic information. In fact, the service registry could cache this information to provide a safe and low-impact mechanism
+ for obtaining this information to other applications without having each application hit the ESB.
+ </para>
+ <para>
+ Integration with a management system can be done in a similar manner. A JBoss DNA connector could access the management system
+ to discover the servers and enable auto-discovery of the services, and "tag" the services deployments with the lifecycle phase
+ (dev, test, production, etc.).
+ </para>
+ <para>
+ By using JBoss DNA, a service repository could manage the wide range of artifacts required in a SOA or web-oriented architecture,
+ yet be able to present a unified view of all service information.
+ </para>
+ </sect1>
+ <sect1 id="data_source_management">
+ <title>Manage data sources and services</title>
+ <para>
+ Many enterprise environments include numerous databases and data services, yet there is often no single place where all
+ these different assets are described or related. A data source/service repository could provide information about the
+ many databases running within the enterprise as well as their documentation, schema history, availability, usage policies,
+ current users of the data (including applications, ETL processes, reporting), geographic deployments and synchronization,
+ and the provenance of the data.
+ </para>
+ <para>
+ Some of this information may actually be defined or controlled within the data sources themselves or within other systems.
+ For example, the DDL scripts used to migrate the database schemas are (hopefully) stored in a version control system,
+ and the databases themselves have the ability to describe their current schemas. Using JBoss DNA, the repository could
+ use a connector to the version control system to expose the scripts, as well as connectors to the databases to expose
+ (and cache) the current schema of the databases. The data repository would then be able to allow users to search over
+ this information without even touching the underlying systems.
+ </para>
+ <para>
+ However, the power of a data repository is really the ability to capture the relationships that otherwise were only captured
+ in people's heads or trapped in documents spread throughout the network. A data repository can capture the policies that
+ dictate how each data source should be used (which are for development purposes, or QA/testing purposes, or which are production,
+ and how are they all related), and it can integrate with management systems to provide information about
+ availability and deployment. As web services are created to provide service-based access to the data in databases,
+ the repository can be used to maintain the relationships between these <emphasis>data services</emphasis> and the underlying sources.
+ Similarly, the repository can track how the databases are used by applications, ETL processes, and reports.
+ </para>
+ </sect1>
+ <sect1 id="configuration_repository">
+ <title>Configuration repository</title>
+ <para>
+ Many applications and libraries have configuration files that allow the users (or developers) to dictate the setup and behavior.
+ Often this involves multiple files in a specific structure on the file system. But invalid or inopportune changes to these files
+ sometimes corrupt the environment, but creating a more robust configuration management system is often way beyond the desired
+ effort.
+ </para>
+ <para>
+ An embedded JBoss DNA repository can provide a more formal and flexible configuration system with little effort. JCR's
+ event system allows the system to be notified when the configuration changes, and versioning can help guarantee the ability
+ to revert back to a previous (valid) configuration. JBoss DNA connectors can be used to integrate the files on the file system
+ into the configuration system, keeping it natural for those wanting to view and change the configuration via the files.
+ JBoss DNA sequencers can even process the configuration files to extract a more structured view of the system.
+ And because JBoss DNA can used with a minimal footprint, it provides the ability to manage and version the configuration
+ with little overhead.
+ </para>
+ <para>
+ JBoss DNA can even be used to centralize the configuration definition for a clustered or distributed system. In this mode,
+ the configuration is managed in a central repository that is remotely accessible by the application. When a process is started,
+ it examines the repository and reads the content containing its configuration. The application can monitor the configuration for
+ changes so that it can modify itself and its components.
+ For larger deployments, a central "enterprise configuration" repository can house the configuration of different kinds of systems,
+ and can even be managed and manipulated through JCR.
+ </para>
+ <para>
+ As we'll see in the <link linkend="using_dna">next chapter</link>, this is actually the way in which JBoss DNA manages
+ its own configuration. In the embedded case, the configuration repository is simply a local (in-memory) repository that
+ is populated by the configuration file (or programmatic API). In a clustered mode, the repository is centralized. But either
+ way, to JBoss DNA the configuration is always defined in a repository.
+ </para>
+ </sect1>
+ <sect1 id="use_case_whats_next">
+ <title>What's next</title>
+ <para>
+ The scenarios described in this chapter are representative of some of the ways in which JBoss DNA can be used, and hopefully
+ give you ideas about how you can leverage JBoss DNA in your application or library.
+ </para>
+ <para>
+ In the <link linkend="using_dna">next chapter</link>, we'll show how you can set up JBoss DNA and use it via the standard JCR API.
+ </para>
+ </sect1>
+</chapter>
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/content/use_cases.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,371 @@
+<?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 chapter 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="using_dna">
+ <title>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: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/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ LF
Deleted: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_for_sequencing.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -1,558 +0,0 @@
-<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="using_dna_for_sequencing">
- <title>Using JBoss DNA for Sequencing</title>
- <para>As we've mentioned before, JBoss DNA is able to work with existing JCR repositories. Your client applications
- make changes to the information in those repositories, and JBoss DNA automatically uses its sequencers to extract
- additional information from the uploaded files.</para>
- <note>
- <para>Configuring JBoss DNA services is a bit more manual than is ideal. As you'll see, JBoss DNA uses dependency
- injection to allow a great deal of flexibility in how it can be configured and customized. But this flexibility
- makes it more difficult for you to use. We understand this, and will soon provide a much easier way to set up
- and manage JBoss DNA. Current plans are to use the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink>
- along with a configuration repository.</para>
- </note>
- <sect1 id="sequencing_service">
- <title>Configuring the Sequencing Service</title>
- <para>The JBoss DNA <emphasis>sequencing service</emphasis> is the component that manages the <emphasis>sequencers</emphasis>,
- reacting to changes in JCR repositories and then running the appropriate sequencers.
- This involves processing the changes on a node, determining which (if any) sequencers should be run on that node,
- and for each sequencer constructing the execution environment, calling the sequencer, and saving the information
- generated by the sequencer.</para>
- <para>To set up the sequencing service, an instance is created, and dependent components are injected into
- the object. This includes among other things:
- <itemizedlist>
- <listitem>
- <para>An <emphasis>execution context</emphasis> that defines the context in which the service runs, including
- a factory for JCR sessions given names of the repository and workspace. This factory must be configured,
- and is how JBoss DNA knows about your JCR repositories and how to connect to them. More on this a bit later.</para>
- </listitem>
- <listitem>
- <para>An <code>java.util.concurrent.ExecutorService</code> used to execute the sequencing activites. If none
- is supplied, a new single-threaded executor is created by calling <code>Executors.newSingleThreadExecutor()</code>.
- (This can easily be changed by subclassing and overriding the <code>SequencerService.createDefaultExecutorService()</code> method.)</para>
- </listitem>
- <listitem>
- <para>Filters for sequencers and events. By default, all sequencers are considered for "node added", "property added"
- and "property changed" events.</para>
- </listitem>
- </itemizedlist>
- </para>
- <para>As mentioned above, the <code>JcrExecutionContext</code> provides access to a <code>SessionFactory</code> that is used
- by JBoss DNA to establish sessions to your JCR repositories. Two implementations are available:
- <itemizedlist>
- <listitem>
- <para>The <code>JndiSessionFactory</code> looks up JCR <code>Repository</code> instances in JNDI using
- names that are supplied when creating sessions. This implementation also has methods to set the
- JCR <code>Credentials</code> for a given workspace name.</para>
- </listitem>
- <listitem>
- <para>The <code>SimpleSessionFactory</code> has methods to register the JCR <code>Repository</code> instances
- with names, as well as methods to set the JCR <code>Credentials</code> for a given workspace name.</para>
- </listitem>
- </itemizedlist>
- You can use the <code>SimpleExecutionContext</code> implementation of <code>ExecutionContext</code> and supply
- a <code>SessionFactory</code> instance, or you can provide your own implementation.</para>
- <para>Here's an example of how to instantiate and configure the SequencingService:</para>
- <programlisting role="JAVA"><![CDATA[
-SimpleSessionFactory sessionFactory = new SimpleSessionFactory();
-sessionFactory.registerRepository("Repository", this.repository);
-Credentials credentials = new SimpleCredentials("jsmith", "secret".toCharArray());
-sessionFactory.registerCredentials("Repository/Workspace1", credentials);
-JcrExecutionContext context = new JcrExecutionContext(sessionFactory,"Repository/Workspace1");
-
-// Create the sequencing service, passing in the execution context ...
-SequencingService sequencingService = new SequencingService();
-sequencingService.setExecutionContext(context);
- ]]></programlisting>
- <para>After the sequencing service is created and configured, it must be started. The SequencingService
- has an <emphasis>administration object</emphasis> (that is an instance of <code>ServiceAdministrator</code>)
- with <code>start()</code>, <code>pause()</code>, and <code>shutdown()</code> methods. The latter method will
- close the queue for sequencing, but will allow sequencing operations already running to complete normally.
- To wait until all sequencing operations have completed, simply call the <code>awaitTermination</code> method
- and pass it the maximum amount of time you want to wait.</para>
- <programlisting role="JAVA"><![CDATA[sequencingService.getAdministrator().start();
-]]></programlisting>
- <para>The sequencing service must also be configured with the sequencers that it will use. This is done using the
- <code>addSequencer(SequencerConfig)</code> method and passing a <code>SequencerConfig</code> instance that
- you create. Here's the code that defines 3 sequencer configurations: 1 that places image metadata into
- "<code><![CDATA[/images/<filename>]]></code>", another that places MP3 metadata into "<code><![CDATA[/mp3s/<filename>]]></code>",
- and a third that places a structure that represents the classes, methods, and attributes found within Java source into
- "<code><![CDATA[/java/<filename>]]></code>".</para>
- <programlisting role="JAVA"><![CDATA[
-String name = "Image Sequencer";
-String desc = "Sequences image files to extract the characteristics of the image";
-String classname = "org.jboss.dna.sequencer.image.ImageMetadataSequencer";
-String[] classpath = null; // Use the current classpath
-String[] pathExpressions = {"//(*.(jpg|jpeg|gif|bmp|pcx|png)[*])/jcr:content[@jcr:data] => /images/$1"};
-SequencerConfig imageSequencerConfig = new SequencerConfig(name, desc, classname,
- classpath, pathExpressions);
-sequencingService.addSequencer(imageSequencerConfig);
-
-name = "MP3 Sequencer";
-desc = "Sequences MP3 files to extract the ID3 tags from the audio file";
-classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer";
-pathExpressions = {"//(*.mp3[*])/jcr:content[@jcr:data] => /mp3s/$1"};
-SequencerConfig mp3SequencerConfig = new SequencerConfig(name, desc, classname,
- classpath, pathExpressions);
-sequencingService.addSequencer(mp3SequencerConfig);
-
-name = "Java Sequencer";
-desc = "Sequences java files to extract the characteristics of the Java source";
-classname = "org.jboss.dna.sequencer.java.JavaMetadataSequencer";
-pathExpressions = {"//(*.java[*])/jcr:content[@jcr:data] => /java/$1"};
-SequencerConfig javaSequencerConfig = new SequencerConfig(name, desc, classname,
- classpath, pathExpressions);
-this.sequencingService.addSequencer(javaSequencerConfig);
- ]]></programlisting>
- <para>Each configuration defines several things, including the name, description, and sequencer implementation class.
- The configuration also defines the classpath information, which can be passed to the <code>ExecutionContext</code> to get
- a Java classloader with which the sequencer class can be loaded. (If no classpath information is provided, as is done
- in the code above, the application class loader is used.) The configuration also specifies the path expressions that
- identify the nodes that should be sequenced with the sequencer and where to store the output generated by the sequencer.
- Path expressions are pretty straightforward but are quite powerful, so before we go any further with the example,
- let's dive into path expressions in more detail.</para>
- <sect2 id="path_expressions">
- <title>Path Expressions</title>
- <para>Path expressions consist of two parts: a selection criteria (or an input path) and an output path:</para>
- <programlisting><![CDATA[ inputPath => outputPath ]]></programlisting>
- <para>The <emphasis>inputPath</emphasis> part defines an expression for the path of a node that is to be sequenced.
- Input paths consist of '<code>/</code>' separated segments, where each segment represents a pattern for a single node's
- name (including the same-name-sibling indexes) and '<code>@</code>' signifies a property name.</para>
- <para>Let's first look at some simple examples:</para>
- <table frame='all'>
- <title>Simple Input Path Examples</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <thead>
- <row>
- <entry>Input Path</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row><entry>/a/b</entry><entry>Match node "<code>b</code>" that is a child of the top level node "<code>a</code>". Neither node
- may have any same-name-sibilings.</entry></row>
- <row><entry>/a/*</entry><entry>Match any child node of the top level node "<code>a</code>".</entry></row>
- <row><entry>/a/*.txt</entry><entry>Match any child node of the top level node "<code>a</code>" that also has a name ending in "<code>.txt</code>".</entry></row>
- <row><entry>/a/*.txt</entry><entry>Match any child node of the top level node "<code>a</code>" that also has a name ending in "<code>.txt</code>".</entry></row>
- <row><entry>/a/b at c</entry><entry>Match the property "<code>c</code>" of node "<code>/a/b</code>".</entry></row>
- <row><entry>/a/b[2]</entry><entry>The second child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row>
- <row><entry>/a/b[2,3,4]</entry><entry>The second, third or fourth child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row>
- <row><entry>/a/b[*]</entry><entry>Any (and every) child named "<code>b</code>" below the top level node "<code>a</code>".</entry></row>
- <row><entry>//a/b</entry><entry>Any node named "<code>b</code>" that exists below a node named "<code>a</code>", regardless
- of where node "<code>a</code>" occurs. Again, neither node may have any same-name-sibilings.</entry></row>
- </tbody>
- </tgroup>
- </table>
- <para>With these simple examples, you can probably discern the most important rules. First, the '<code>*</code>' is a wildcard character
- that matches any character or sequence of characters in a node's name (or index if appearing in between square brackets), and
- can be used in conjunction with other characters (e.g., "<code>*.txt</code>").</para>
- <para>Second, square brackets (i.e., '<code>[</code>' and '<code>]</code>') are used to match a node's same-name-sibiling index.
- You can put a single non-negative number or a comma-separated list of non-negative numbers. Use '0' to match a node that has no
- same-name-sibilings, or any positive number to match the specific same-name-sibling.</para>
- <para>Third, combining two delimiters (e.g., "<code>//</code>") matches any sequence of nodes, regardless of what their names are
- or how many nodes. Often used with other patterns to identify nodes at any level matching other patterns.
- Three or more sequential slash characters are treated as two.</para>
- <para>Many input paths can be created using just these simple rules. However, input paths can be more complicated. Here are some
- more examples:</para>
- <table frame='all'>
- <title>More Complex Input Path Examples</title>
- <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <thead>
- <row>
- <entry>Input Path</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row><entry>/a/(b|c|d)</entry><entry>Match children of the top level node "<code>a</code>" that are named "<code>a</code>",
- "<code>b</code>" or "<code>c</code>". None of the nodes may have same-name-sibling indexes.</entry></row>
- <row><entry>/a/b[c/d]</entry><entry>Match node "<code>b</code>" child of the top level node "<code>a</code>", when node
- "<code>b</code>" has a child named "<code>c</code>", and "<code>c</code>" has a child named "<code>d</code>".
- Node "<code>b</code>" is the selected node, while nodes "<code>b</code>" and "<code>b</code>" are used as criteria but are not
- selected.</entry></row>
- <row><entry>/a(/(b|c|d|)/e)[f/g/@something]</entry><entry>Match node "<code>/a/b/e</code>", "<code>/a/c/e</code>", "<code>/a/d/e</code>",
- or "<code>/a/e</code>" when they also have a child "<code>f</code>" that itself has a child "<code>g</code>" with property
- "<code>something</code>". None of the nodes may have same-name-sibling indexes.</entry></row>
- </tbody>
- </tgroup>
- </table>
- <para>These examples show a few more advanced rules. Parentheses (i.e., '<code>(</code>' and '<code>)</code>') can be used
- to define a set of options for names, as shown in the first and third rules. Whatever part of the selected node's path
- appears between the parentheses is captured for use within the output path. Thus, the first input path in the previous table
- would match node "<code>/a/b</code>", and "b" would be captured and could be used within the output path using "<code>$1</code>",
- where the number used in the output path identifies the parentheses.</para>
- <para>Square brackets can also be used to specify criteria on a node's properties or children. Whatever appears in between the square
- brackets does not appear in the selected node.</para>
- <para>Let's go back to the previous code fragment and look at the first path expression:</para>
- <programlisting><![CDATA[ //(*.(jpg|jpeg|gif|bmp|pcx|png)[*])/jcr:content[@jcr:data] => /images/$1 ]]></programlisting>
- <para>This matches a node named "<code>jcr:content</code>" with property "<code>jcr:data</code>" but no siblings with the same name,
- and that is a child of a node whose name ends with "<code>.jpg</code>", "<code>.jpeg</code>", "<code>.gif</code>", "<code>.bmp</code>", "<code>.pcx</code>",
- or "<code>.png</code>" that may have any same-name-sibling index. These nodes can appear at any level in the repository.
- Note how the input path capture the filename (the segment containing the file extension), including any same-name-sibling index.
- This filename is then used in the output path, which is where the sequenced content is placed.</para>
- </sect2>
- <sect2 id="path_expressions_in_example">
- <title>Path Expressions Used in the Example</title>
- <para>Now that we've covered path expressions, let's go back to the three sequencer configuration in the example.
- Here they are again, with a description of what each path means:</para>
- <table frame='all'>
- <title>Path Expressions for the 3 Sequencers</title>
- <tgroup cols='3' align='left' colsep='1' rowsep='1'>
- <colspec colname='c1' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <colspec colname='c2' colwidth="1*"/>
- <thead>
- <row>
- <entry>Input Path</entry>
- <entry>Output Path</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><![CDATA[//(*.(jpg|jpeg|gif|bmp|pcx|png)[*])/jcr:content[@jcr:data]]]></entry>
- <entry><![CDATA[/images/$1]]></entry>
- <entry>Any node with a name ending in "<code>.jpg</code>", "<code>.jpeg</code>", "<code>.gif</code>", "<code>.bmp</code>",
- "<code>.pcx</code>", or "<code>.png</code>", whether or not it has a same-name-sibling index, but that has a child named
- "<code>jcr:content</code>" with "<code>jcr:data</code>" property. The node name representing the filename (including any
- same-name-sibling index) is captured, and used to place the output in "<code><![CDATA[/images/<filename>]]></code>".</entry>
- </row>
- <row>
- <entry><![CDATA[//(*.mp3[*])/jcr:content[@jcr:data]]]></entry>
- <entry><![CDATA[/mp3s/$1]]></entry>
- <entry>Any node with a name ending in "<code>.mp3</code>", whether or not it has a same-name-sibling index, but that has a child named
- "<code>jcr:content</code>" with "<code>jcr:data</code>" property. The node name representing the filename (including any
- same-name-sibling index) is captured, and used to place the output in "<code><![CDATA[/mp3s/<filename>]]></code>".</entry>
- </row>
- <row>
- <entry><![CDATA[//(*.java[*])/jcr:content[@jcr:data]]]></entry>
- <entry><![CDATA[/java/$1]]></entry>
- <entry>Any node with a name ending in "<code>.java</code>", whether or not it has a same-name-sibling index, but that has a child named
- "<code>jcr:content</code>" with "<code>jcr:data</code>" property. The node name representing the filename (including any
- same-name-sibling index) is captured, and used to place the output in "<code><![CDATA[/java/<filename>]]></code>".</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>After these sequencer configurations are defined and added to the <code>SequencingService</code>,
- the service is now ready to start reacting to changes in the repository and automatically looking for nodes to sequence.
- But we first need to wire the service into the repository to receive those change events.
- This is accomplished using the <code>ObservationService</code>
- described in the <link linkend="observation_service">next section</link>.</para>
- </sect2>
- </sect1>
- <sect1 id="observation_service">
- <title>Configuring the Observation Service</title>
- <para>The JBoss DNA <code>ObservationService</code> is responsible for listening to one or more JCR repositories
- and multiplexing the events to its listeners. Unlike JCR events, this framework embeds in the events the
- name of the repository and workspace that can be passed to a <code>SessionFactory</code> to obtain a session
- to the repository in which the change occurred. This simple design makes it very easy for JBoss DNA to
- concurrently work with multiple JCR repositories.</para>
- <para>Configuring an observation service is pretty easy, especially if you reuse the same <code>SessionFactory</code>
- supplied to the sequencing service. Here's an example:</para>
- <programlisting role="JAVA"><![CDATA[
- this.observationService = new ObservationService(sessionFactory);
- this.observationService.getAdministrator().start();
- ]]></programlisting>
- <note>
- <para>Both <code>ObservationService</code> and <code>SequencingService</code> implement
- <code>AdministeredService</code>, which has a <code>ServiceAdministrator</code> used to start, pause, and shutdown the
- service. In other words, the lifecycle of the services are managed in the same way.</para>
- </note>
- <para>After the observation service is started, listeners can be added. The <code>SequencingService</code> implements the required
- interface, and so it may be registered directly:</para>
- <programlisting role="JAVA"><![CDATA[
- observationService.addListener(sequencingService);
- ]]></programlisting>
- <para>Finally, the observation service must be wired to monitor one of your JCR repositories. This is done with
- one of the <code>monitor(...)</code> methods:</para>
- <programlisting role="JAVA"><![CDATA[
- int eventTypes = Event.NODE_ADDED | Event.PROPERTY_ADDED | Event.PROPERTY_CHANGED;
- observationService.monitor("Main Repository/Workspace1", eventTypes);
- ]]></programlisting>
- <para>At this point, the observation service is listening to a JCR repository and forwarding the appropriate events
- to the sequencing service, which will asynchronously process the changes and sequence the information added to or changed in the repository.
- </para>
- </sect1>
- <sect1 id="shutting_down">
- <title>Shutting down JBoss DNA services</title>
- <para>The JBoss DNA services are utilizing resources and threads that must be released before your application is ready to shut down.
- The safe way to do this is to simply obtain the <code>ServiceAdministrator</code> for each service (via the <code>getServiceAdministrator()</code> method)
- and call <code>shutdown()</code>. As previously mentioned, the shutdown method will simply prevent new work from being processed
- and will not wait for existing work to be completed. If you want to wait until the service completes all its work, you must wait
- until the service terminates. Here's an example that shows how this is done:</para>
- <programlisting role="JAVA"><![CDATA[
-// Shut down the service and wait until it's all shut down ...
-sequencingService.getAdministrator().shutdown();
-sequencingService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS);
-
-// Shut down the observation service ...
-observationService.getAdministrator().shutdown();
-observationService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS);
- ]]></programlisting>
- <para>At this point, we've covered how to configure and use the JBoss DNA services in your application.
- The next chapter goes back to the <link linkend="downloading_and_running">sample application</link> to show how all
- these pieces fit together.</para>
- </sect1>
- <sect1 id="example_application_review">
- <title>Reviewing the example application</title>
- <para>Recall that the example application consists of a client application that sets up an in-memory JCR repository and
- that allows a user to upload files into that repository. The client also sets up the DNA services with an image sequencer so
- that if any of the uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will automatically extract the image's
- metadata (e.g., image format, physical size, pixel density, etc.) and store that in the repository. Or, if the client uploads
- MP3 audio files, the title, author, album, year, and comment are extracted from the audio file and stored in the repository.</para>
- <para>
- The example is comprised of 5 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
- <programlisting><![CDATA[
- org/jboss/example/dna/sequencers/ConsoleInput.java
- /ContentInfo.java
- /JavaInfo.java
- /MediaInfo.java
- /SequencingClient.java
- /UserInterface.java
- ]]></programlisting>
- <para><code>SequencingClient</code> is the class that contains the main application. <code>ContentInfo</code> is a simple class
- that encapsulate metadata generated by the sequencers and accessed by this example application, and there are two subclasses:
- <code>MediaInfo</code> encapsulates metadata about media (image and MP3) files, while <code>JavaInfo</code> is a subclass
- encapsulating information about a Java class. The client accesses the content from the repository and represent the
- information using instances of <code>ContentInfo</code> (and its subclasses) and then passing them to the <code>UserInterface</code>.
- <code>UserInterface</code> is an interface with methods that will be called at runtime to
- request data from the user. <code>ConsoleInput</code> is an implementation of this that creates a text user interface,
- allowing the user to operate the client from the command-line. We can easily create a graphical implementation of
- <code>UserInterface</code> at a later date. We can also create a mock implementation for testing purposes that simulates
- a user entering data. This allows us to check the behavior of the client automatically using conventional JUnit test cases,
- as demonstrated by the code in the <code>src/test/java</code> directory:</para>
- <programlisting><![CDATA[
- org/jboss/example/dna/sequencers/SequencingClientTest.java
- /MockUserInterface.java
- ]]></programlisting>
- <para>If we look at the <code>SequencingClient</code> code, there are a handful of methods that encapsulate the various activities.</para>
- <note>
- <para>Some of the code samples included in this book have had some of the error handling and comments removed so that
- the samples are more readable and concise.</para>
- </note>
- <para>The <code>startRepository()</code> method starts up an in-memory Jackrabbit JCR repository. The bulk of this method is simply
- gathering and passing the information required by Jackrabbit. Because Jackrabbit's <code>TransientRepository</code>
- implementation shuts down after the last session is closed, the application maintains a session to ensure that the
- repository remains open throughout the application's lifetime. And finally, the node type needed by the image sequencer is
- registered with Jackrabbit.</para>
- <programlisting role="JAVA"><![CDATA[
-public void startRepository() throws Exception {
- if (this.repository == null) {
- try {
-
- // Load the Jackrabbit configuration ...
- File configFile = new File(this.jackrabbitConfigPath);
- String pathToConfig = configFile.getAbsolutePath();
-
- // Find the directory where the Jackrabbit repository data will be stored ...
- File workingDirectory = new File(this.workingDirectory);
- String workingDirectoryPath = workingDirectory.getAbsolutePath();
-
- // Get the Jackrabbit custom node definition (CND) file ...
- URL cndFile = Thread.currentThread().getContextClassLoader().getResource("jackrabbitNodeTypes.cnd");
-
- // Create the Jackrabbit repository instance and establish a session to keep the repository alive ...
- this.repository = new TransientRepository(pathToConfig, workingDirectoryPath);
- if (this.username != null) {
- Credentials credentials = new SimpleCredentials(this.username, this.password);
- this.keepAliveSession = this.repository.login(credentials, this.workspaceName);
- } else {
- this.keepAliveSession = this.repository.login();
- }
-
- try {
- // Register the node types (only valid the first time) ...
- Workspace workspace = this.keepAliveSession.getWorkspace();
- JackrabbitNodeTypeManager mgr = (JackrabbitNodeTypeManager)workspace.getNodeTypeManager();
- mgr.registerNodeTypes(cndFile.openStream(), JackrabbitNodeTypeManager.TEXT_X_JCR_CND);
- } catch (RepositoryException e) {
- if (!e.getMessage().contains("already exists")) throw e;
- }
-
- } catch (Exception e) {
- this.repository = null;
- this.keepAliveSession = null;
- throw e;
- }
- }
-}
- ]]></programlisting>
- <para>As you can see, this method really has nothing to do with JBoss DNA, other than setting up a JCR repository that JBoss
- DNA will use.</para>
- <para>The <code>shutdownRepository()</code> method shuts down the Jackrabbit transient repository by closing the "keep-alive session".
- Again, this method really does nothing specifically with JBoss DNA, but is needed to manage the JCR repository that JBoss DNA uses.</para>
- <programlisting role="JAVA"><![CDATA[
-public void shutdownRepository() throws Exception {
- if (this.repository != null) {
- try {
- this.keepAliveSession.logout();
- } finally {
- this.repository = null;
- this.keepAliveSession = null;
- }
- }
-}
- ]]></programlisting>
- <para>The <code>startDnaServices()</code> method first starts the JCR repository (if it was not already started), and proceeds
- to create and configure the <code>SequencingService</code> as described <link linkend="sequencing_service">earlier</link>.
- This involes setting up the <code>SessionFactory</code> and <code>ExecutionContext</code>, creating the
- <code>SequencingService</code> instance, and configuring the image sequencer. The method then continues by setting up the
- <code>ObservationService</code> as described <link linkend="observation_service">earlier</link> and starting the service.</para>
- <programlisting role="JAVA"><![CDATA[
-public void startDnaServices() throws Exception {
- if (this.repository == null) this.startRepository();
- if (this.sequencingService == null) {
-
- SimpleSessionFactory sessionFactory = new SimpleSessionFactory();
- sessionFactory.registerRepository(this.repositoryName, this.repository);
- if (this.username != null) {
- Credentials credentials = new SimpleCredentials(this.username, this.password);
- sessionFactory.registerCredentials(this.repositoryName + "/" + this.workspaceName, credentials);
- }
- this.executionContext = new JcrExecutionContext(sessionFactory, repositoryWorkspaceName);
-
- // Create the sequencing service, passing in the execution context ...
- this.sequencingService = new SequencingService();
- this.sequencingService.setExecutionContext(executionContext);
-
- // Configure the sequencers.
- String name = "Image Sequencer";
- String desc = "Sequences image files to extract the characteristics of the image";
- String classname = "org.jboss.dna.sequencer.images.ImageMetadataSequencer";
- String[] classpath = null; // Use the current classpath
- String[] pathExpressions = {"//(*.(jpg|jpeg|gif|bmp|pcx|png|iff|ras|pbm|pgm|ppm|psd))[*]/jcr:content[@jcr:data] => /images/$1"};
- SequencerConfig imageSequencerConfig = new SequencerConfig(name, desc, classname, classpath, pathExpressions);
- this.sequencingService.addSequencer(imageSequencerConfig);
-
- // Set up the MP3 sequencer ...
- name = "Mp3 Sequencer";
- desc = "Sequences mp3 files to extract the id3 tags of the audio file";
- classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer";
- pathExpressions = {"//(*.mp3)[*]/jcr:content[@jcr:data] => /mp3s/$1"};
- SequencerConfig mp3SequencerConfig = new SequencerConfig(name, desc, classname, classpath, pathExpressions);
- this.sequencingService.addSequencer(mp3SequencerConfig);
-
- name = "Java Sequencer";
- desc = "Sequences java files to extract the characteristics of the Java source";
- classname = "org.jboss.dna.sequencer.java.JavaMetadataSequencer";
- pathExpressions = {"//(*.java[*])/jcr:content[@jcr:data] => /java/$1"};
- SequencerConfig javaSequencerConfig = new SequencerConfig(name, desc, classname,classpath, pathExpressions);
- this.sequencingService.addSequencer(javaSequencerConfig);
-
- // Use the DNA observation service to listen to the JCR repository (or multiple ones), and
- // then register the sequencing service as a listener to this observation service...
- this.observationService = new ObservationService(this.executionContext.getSessionFactory());
- this.observationService.getAdministrator().start();
- this.observationService.addListener(this.sequencingService);
- this.observationService.monitor(this.repositoryName + "/" + this.workspaceName, Event.NODE_ADDED | Event.PROPERTY_ADDED | Event.PROPERTY_CHANGED);
- }
- // Start up the sequencing service ...
- this.sequencingService.getAdministrator().start();
-}
- ]]></programlisting>
- <para>The <code>shutdownDnaServices()</code> method is pretty straightforward: it just calls shutdown on each of the services
- and waits until they terminate.</para>
- <programlisting role="JAVA"><![CDATA[
-public void shutdownDnaServices() throws Exception {
- if (this.sequencingService == null) return;
-
- // Shut down the service and wait until it's all shut down ...
- this.sequencingService.getAdministrator().shutdown();
- this.sequencingService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS);
-
- // Shut down the observation service ...
- this.observationService.getAdministrator().shutdown();
- this.observationService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS);
-}
- ]]></programlisting>
- <para>None of the other methods really do anything with JBoss DNA <emphasis>per se</emphasis>. Instead, they merely work with the repository
- using the JCR API.</para>
- <para>The <code>main</code> method of the <code>SequencingClient</code> class creates a <code>SequencingClient</code> instance,
- and passes a new <code>ConsoleInput</code> instance:</para>
- <programlisting role="JAVA"><![CDATA[
-public static void main( String[] args ) throws Exception {
- SequencingClient client = new SequencingClient();
- client.setRepositoryInformation("repo", "default", "jsmith", "secret".toCharArray());
- client.setUserInterface(new ConsoleInput(client));
-}
- ]]></programlisting>
- <para>If we look at the <code>ConsoleInput</code> constructor, it starts the repository, the DNA services, and a thread
- for the user interface. At this point, the constructor returns, but the main application continues under the user interface thread.
- When the user requests to quit, the user interface thread also shuts down the DNA services and JCR repository.</para>
- <programlisting role="JAVA"><![CDATA[
-public ConsoleInput( SequencerClient client ) {
- try {
- client.startRepository();
- client.startDnaServices();
-
- System.out.println(getMenu());
- Thread eventThread = new Thread(new Runnable() {
- private boolean quit = false;
- public void run() {
- try {
- while (!quit) {
- // Display the prompt and process the requested operation ...
- }
- } finally {
- try {
- // Terminate ...
- client.shutdownDnaServices();
- client.shutdownRepository();
- } catch (Exception err) {
- System.out.println("Error shutting down sequencing service and repository: "
- + err.getLocalizedMessage());
- err.printStackTrace(System.err);
- }
- }
- }
- });
- eventThread.start();
- } catch (Exception err) {
- System.out.println("Error: " + err.getLocalizedMessage());
- err.printStackTrace(System.err);
- }
-}
- ]]></programlisting>
- <para>At this point, we've reviewed all of the interesting code in the example application. However, feel free
- to play with the application, trying different things.</para>
- </sect1>
- <sect1 id="using_dna_review">
- <title>Summarizing what we just did</title>
- <para>In this chapter we covered the different JBoss DNA components used for automatically sequencing a variety of
- types of information, and how those components can be used in your application.
- Specifically, we described how the <code>SequencingService</code> and <code>ObservationService</code> can
- be configured and used. And we ended the chapter by reviewing the example application, which not only uses
- JBoss DNA, but also the repository via the JCR API.</para>
- </sect1>
-</chapter>
Deleted: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -1,273 +0,0 @@
-<?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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="using_dna_repositories">
- <title>Using JBoss DNA Repositories</title>
- <para>One of the capabilities of JBoss DNA is to provide access through
- <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JCR</ulink> to different kinds of repositories and storage systems.
- Your applications work with the JCR API, but through JBoss DNA you're able to accesses the content from where the information
- exists - not just a single purpose-built repository. This is fundamentally what makes JBoss DNA different.</para>
- <para>How does JBoss DNA do this? At the heart of JBoss DNA and it's JCR implementation is a simple connector
- system that is designed around creating and accessing graphs. The JBoss DNA JCR implementation actually just sits on
- top of a single repository source, which it uses to access of the repositories content.
- <figure id="dnajcr-and-connector">
- <title>JBoss DNA's JCR implementation delegates to a repository source</title>
- <graphic align="center" scale="100" fileref="dnajcr-and-connector.png"/>
- </figure>
- That single repository source could be an in-memory repository, a JBoss Cache instance, or a federated repository.
- <figure id="dna-connectors-0.2">
- <title>JBoss DNA can put JCR on top of multiple kinds of systems</title>
- <graphic align="center" scale="100" fileref="dna-connectors-0.2.png"/>
- </figure>
- And the JBoss DNA project has plans to create other connectors, too. For instance, we're going to build a connector
- to other JCR repositories. And another to a file system, so that the files and directories on an area of the file system
- can be accessed through JCR. Of course, if we don't have a connector to suit your needs, you can write your own.
- <figure id="dna-connectors-future">
- <title>Future JBoss DNA connectors</title>
- <graphic align="center" scale="100" fileref="dna-connectors-future.png"/>
- </figure>
- </para>
- <note>
- <para>You might be thinking that these connectors are interesting, but what do they really provide? Is it really useful
- to use JCR to access a relational database rather than JDBC? Or, why access the files on a file system when there
- are already mechanisms to do that?</para>
- <para>Maybe putting JCR on top of a single system (like a JDBC database) isn't that interesting. What
- <emphasis>is</emphasis> interesting, though, is accessing the information in multiple systems <emphasis>as if all that information were
- in a single JCR repository</emphasis>. That's what the federated repository source is all about. The JBoss DNA connector
- system just makes it possible to interact with all these systems in the same way.</para>
- <para>Think of it this way: with JBoss DNA, you can use JCR to get to the schemas of multiple relational databases <emphasis>and</emphasis> the schemas
- defined by DDL files in your SVN repository <emphasis>and</emphasis> the schemas defined by logical models stored on your file system.
- </para>
- </note>
- <para>So with this very high-level summary, let's dive a little deeper and look at how to configure and use JBoss DNA and JCR.</para>
- <sect1 id="repository_service">
- <title>Configuring the Repository Service</title>
- <para>The JBoss DNA <emphasis>repository service</emphasis> is the component that manages the <emphasis>repositories</emphasis>
- and connections to them. The service reads its configuration from a <code>RepositorySource</code> instance (i.e., the
- "configuration repository") and automatically sets up the repositories given the <code>RepositorySource</code> instances
- found in the configuration repository.</para>
- <note>
- <para>Configuring JBoss DNA services is more manual and complex than we want. As you'll see, JBoss DNA uses dependency
- injection to allow a great deal of flexibility in how it can be configured and customized. But this flexibility
- makes it more difficult for you to use. We understand this, and will soon provide a much easier way to set up
- and manage JBoss DNA. Current plans are to use the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink>
- along with a configuration repository that makes it very easy to set up and manage JBoss DNA, whether it's used in
- a simple application or a cluster of processes.</para>
- </note>
- <para>To set up the repository service, we need to first set up a few other objects:
- <itemizedlist>
- <listitem>
- <para>An <emphasis>execution contexts</emphasis>. Execution contexts define the context (or environment)
- in which the service runs and in which operations against repositories are performed. <code>ExecutionContext</code>
- instances can be created using JAAS application contexts, meaning that they contain the information about the subject
- that the software represents. Execution contexts also provide access to the all of the factories and utilities
- used throughout the services and components, and it is through this mechanism that you can inject your own behavior.
- For example, if your application already had a notion of namespaces, you could create an execution context that
- uses your own <code>NamespaceRegistry</code> implementation (which would use the namespaces defined in your application).</para>
- </listitem>
- <listitem>
- <para>A <emphasis>repository library</emphasis> that manages the list of <code>RepositorySource</code> instances.
- The library makes sure to inject the environments into each repository source, and it provides for each source
- a configurable pool of connections.</para>
- </listitem>
- <listitem>
- <para>A <emphasis>configuration repository</emphasis> that contains descriptions of all of the repository sources
- as well as any information those sources need. Because this is a regular repository, this could be a simple
- repository with content loaded from an XML file (as in this example). Or it could be a shared
- central repository with information about all of the JBoss DNA processes across your company.</para>
- </listitem>
- </itemizedlist>
- With these components in place, we can then instantiate the <code>RepositoryService</code> and start it (using its
- <code>ServiceAdministrator</code>). During startup, the service reads the configuration repository and loads any
- defined <code>RepositorySource</code> instances into the repository library, using the class loader factory
- (available in the <code>ExecutionContext</code>) to obtain.
- </para>
- <para>Here's sample code that shows how to set up and start the repository service. You can see something similar
- in the example application in the <code>startRepositories()</code> method of the <code>org.jboss.example.dna.repository.RepositoryClient</code> class.</para>
- <programlisting role="JAVA"><![CDATA[
- // Create the execution context that we'll use for the services. If we'd want to use JAAS, we'd
- // create the context by supplying LoginContext, AccessControlContext, or even Subject with
- // CallbackHandlers. But this example doesn't use JAAS in this example.
- ExecutionContext context = new ExecutionContext();
-
- // Create the library for the RepositorySource instances ...
- RepositoryLibrary sources = new RepositoryLibrary(context);
-
- // Load into the source manager the repository source for the configuration repository ...
- InMemoryRepositorySource configSource = new InMemoryRepositorySource();
- configSource.setName("Configuration");
- sources.addSource(configSource);
-
- // Now instantiate the Repository Service ...
- RepositoryService service = new RepositoryService(sources, configSource.getName(), context);
- service.getAdministrator().start();
- ]]></programlisting>
- <para>After startup completes, the repositories are ready to be used. The client application obtains the list of repositories
- and presents them to the user. When the user selects one, the client application starts navigating that repository
- starting at its root node (e.g., the "/" path). As you type a command to list the contents of the current node or to
- "change directories" to a different node, the client application obtains the information for the node using a simple
- procedure:
- <orderedlist>
- <listitem>
- <para>Get a connection to the repository.</para>
- </listitem>
- <listitem>
- <para>Using the connection, find the current node and read its properties and children, putting the information
- into a simple Java plain old Java object (POJO).</para>
- </listitem>
- <listitem>
- <para>Close the connection to the repository (in a finally block to ensure it always happens).</para>
- </listitem>
- </orderedlist>
- </para>
- <sect2 id="using_jcr_with_dna">
- <title>Using JCR to read repository</title>
- <para>If we want to perform these steps using JCR, a JCR <code>Session</code> represents our connection.
- So after we create a <code>JcrRepository</code> instance pointing to our repository library, we can
- then login to obtain a JCR session:</para>
- <programlisting role="JAVA"><![CDATA[
- JcrRepository jcrRepository = new JcrRepository(context, sources);
- Session session = jcrRepository.login(sourceName);
- ]]></programlisting>
- <para>Now, the above code doesn't do any authentication; it essentially trusts the caller has the appropriate privileges.
- Normally, your application will need to authenticate the user, so let's look at how that's done.</para>
- <para>JBoss DNA uses the <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutorials/GeneralAcnOnly.html">Java
- Authentication and Authorization Service (JAAS)</ulink>, making it possible to use any existing JAAS security provider.
- There are numerous JAAS providers, but one of the best open-source implementations is
- <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink>, which can authenticate using LDAP, certificates,
- the operating system, and federated single-sign-on (among others).
- </para>
- <para>
- The JCR API defines a <code>Credentials</code> marker interface, an instance of which can be passed to the
- <code>Session.login(...)</code> method. Rather than provide a concrete implementation of this interface, JBoss DNA
- allows you to pass any implementation of <code>Credentials</code> that also has one of the following methods:
- <itemizedlist>
- <listitem>
- <para><code>getLoginContext()</code> that returns a <code>javax.security.auth.login.LoginContext</code> instance.</para>
- </listitem>
- <listitem>
- <para><code>getAccessControlContext()</code> that returns a <code>java.security.AccessControlContext</code> instance.</para>
- </listitem>
- </itemizedlist>
- This way, your application can obtain the JAAS <code>LoginContext</code> or <code>AccessControlContext</code> however it wants,
- and then merely passes that into DNA through the JCR <code>Credentials</code>. No interfaces or classes specific to JBoss DNA are required.
- </para>
- <para>The following code shows how this is done, using an anonymous inner class for the <code>Credentials</code> implementation.</para>
- <programlisting role="JAVA"><![CDATA[
- CallbackHandler callbackHandler = // as needed by your app, according to JAAS
- final LoginContext loginContext = new LoginContext("MyAppContextName",callbackHandler);
- Credentials credentials = new Credentials() {
- public LoginContext getLoginContext() { return loginContext; }
- };
- JcrRepository jcrRepository = new JcrRepository(context, sources);
- Session session = jcrRepository.login(credentials, sourceName);
- ]]></programlisting>
- <para>Once you have a JCR session, you can then use it to find the node of interest and access the necessary information. All of this
- code will use only the JCR API - there's nothing specific to JBoss DNA's implementation. And remember, when you're finished with
- the session, be sure to logout (usually in a <code>finally</code> block):</para>
- <programlisting role="JAVA"><![CDATA[
- if (session != null) session.logout();
- ]]></programlisting>
- <para>Like many people recommend with JCR, you can create either long-lived or short-lived JCR <code>Session</code>s. The
- JBoss DNA implementation of JCR was designed to efficiently do either.</para>
- </sect2>
- <!--
- <sect2 id="using_dna_repositories_with_dna_api">
- <title>Using JBoss DNA's API to read repository</title>
- <para>Although we recommend using JCR, JBoss DNA has an internal command-based API that completely side-steps JCR and provides
- very simple graph-based operations. For more information, see the <code>RepositoryClient</code> class in the example.</para>
- <note>
- <para>This API is likely to undergo changes in the next few releases, and using it at this time is not suggested.</para>
- </note>
- </sect2>
- -->
- </sect1>
- <sect1 id="shutting_down_repository_service">
- <title>Shutting down the Repository Service</title>
- <para>In the first part of this chapter, we saw how to instantiate, configure, and start the <code>RepositoryService</code>.
- We then saw how to use JCR to access the repository service by creating JCR <code>Session</code>s, and how to log out of those
- sessions when no longer needed.</para>
- <para>In this short section we'll see how to shut down the <code>RepositoryService</code> and <code>RepositoryLibrary</code>
- when you're finished with all of the repositories. It's a simple but important step, since this closes all outstanding
- connections that may be sitting unused in the library's connection pools.</para>
- <para>Shutting down these components is very straightforward: get the <code>ServiceAdministrator</code> on each, and call <code>shutdown()</code>.</para>
- <programlisting role="JAVA"><![CDATA[
- // Shut down the repository service ...
- repositoryService.getAdministrator().shutdown();
-
- // Shut down the manager of the RepositorySource instances, waiting until all connections are closed
- sources.getAdministrator().shutdown();
- sources.getAdministrator().awaitTermination(1, TimeUnit.SECONDS);
- ]]></programlisting>
- <para>The <code>shutdown()</code> method attempts to close all open and unused resources (such as open and unused connections in the pool).
- No more connections can be created, and any connections that are currently in use are not closed but allowed to be used and closed normally.
- When the last connection is used, the service then transitions to a <emphasis>terminated</emphasis> state, which you can wait for using
- the <code>awaitTermination(int,TimeUnit)</code> method.</para>
- <para>If you want to shutdown the services immediately, then you could call <code>shutdownNow()</code>, which blocks while it attempts to immediately
- close all connections - <emphasis>even those currently in use</emphasis>. So, while you generally want to use <code>shutdown()</code>,
- it is good to be aware that this <code>shutdownNow()</code> method does exist.</para>
- </sect1>
- <sect1 id="example_repository_application_review">
- <title>Reviewing the example repository application</title>
- <para>Recall that the example repository application consists of a client application that sets up a repository service and the
- repositories defined in a configuration repository, allowing the user to pick a repository and interactively navigate
- the selected repository. Several repositories are set up, including several in-memory repositories and one federated repository
- that dynamically federates the content from the other repositories.</para>
- <para>
- The example is comprised of 2 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
- <programlisting><![CDATA[
- org/jboss/example/dna/repositories/ConsoleInput.java
- /RepositoryClient.java
- /UserInterface.java
- ]]></programlisting>
- <para><code>RepositoryClient</code> is the class that contains the main application. It uses an instance of the
- <code>UserInterface</code> interface to methods that will be called at runtime to obtain information about the
- files that are imported into the in-memory repositories and the JAAS <code>CallbackHandler</code> implementation
- that will be used by JAAS to prompt the user for authentication information. Finally, the <code>ConsoleInput</code>
- is an implementation of this that creates a text user interface, allowing the user to operate the client from the command-line.
- We can easily create a graphical implementation of <code>UserInterface</code> at a later date, or we can also create a mock
- implementation for testing purposes that simulates a user entering data. This allows us to check the behavior of the client
- automatically using conventional JUnit test cases, as demonstrated by the code in the <code>src/test/java</code> directory:</para>
- <programlisting><![CDATA[
- org/jboss/example/dna/sequencers/RepositoryClientTest.java
- /RepositoryClientUsingJcrTest.java
- ]]></programlisting>
- <para>
- The code we presented earlier in this chapter represent the bulk of the JBoss DNA and JCR-specific code used in the
- <code>RepositoryClient</code>, so we won't cover it in any more detail here. Please refer to the sample client code
- if you want to see more.
- </para>
- </sect1>
- <sect1 id="using_dna_repositories_review">
- <title>Summarizing what we just did</title>
- <para>In this chapter we covered the different JBoss DNA components used for accessing repositories through JCR, including
- repositories that federate their content from the content of other repositories. Specifically, we described how the
- <code>RepositoryService</code> and <code>JcrRepository</code> can be configured and used.
- </para>
- </sect1>
-</chapter>
-
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/custom.dtd 2009-06-07 22:33:45 UTC (rev 989)
@@ -0,0 +1,138 @@
+<!ENTITY versionNumber "0.5">
+<!ENTITY copyrightYears "2008-2009">
+<!ENTITY copyrightHolder "Red Hat, Inc.">
+
+<!-- Frequently used URLs -->
+
+<!ENTITY Home "http://www.jboss.org/dna/">
+<!ENTITY Downloads "&Home;downloads.html">
+<!ENTITY Community "&Home;community.html">
+<!ENTITY DocHome "http://www.jboss.org/file-access/default/members/dna/freezone/">
+<!ENTITY API "&DocHome;docs/&versionNumber;/apidocs/org/jboss/dna/">
+<!ENTITY JIRA "http://jira.jboss.org/jira/browse/DNA">
+<!ENTITY Roadmap "&JIRA;?report=com.atlassian.jira.plugin.system.project:roadmap-panel">
+<!ENTITY Subversion "http://anonsvn.jboss.org/repos/dna/">
+<!ENTITY Fisheye "http://fisheye.jboss.org/browse/DNA/">
+<!ENTITY SecureSubversion "https://svn.jboss.org/repos/dna/">
+<!ENTITY Forums "http://www.jboss.com/index.html?module=bb&op=viewforum&f=272">
+<!ENTITY JSR170 "http://www.jcp.org/en/jsr/detail?id=170">
+<!ENTITY JSR283 "http://www.jcp.org/en/jsr/detail?id=283">
+<!ENTITY JSR203 "http://www.jcp.org/en/jsr/detail?id=203">
+<!ENTITY MailTo "mailto:dna-users at jboss.org">
+<!ENTITY Wikipedia "http://en.wikipedia.org/wiki/">
+<!ENTITY JBossMaven "http://repository.jboss.com/maven2/">
+
+<!ENTITY Java "http://java.sun.com/j2se/1.5.0/docs/api/">
+
+<!ENTITY GettingStarted "<ulink url='&DocHome;docs/&versionNumber;/manuals/gettingstarted/html/index.html'>Getting Started</ulink>">
+<!ENTITY ReferenceGuide "<ulink url='&DocHome;docs/&versionNumber;/manuals/reference/html/index.html'>Getting Started</ulink>">
+
+<!-- Types in JRE -->
+
+<!ENTITY String "<ulink url='&Java;java/lang/String.html'><interface>String</interface></ulink>">
+<!ENTITY File "<ulink url='&Java;java/io/File.html'><classname>File</classname></ulink>">
+<!ENTITY URL "<ulink url='&Java;java/net/URL.html'><classname>URL</classname></ulink>">
+<!ENTITY URI "<ulink url='&Java;java/net/URL.html'><classname>URI</classname></ulink>">
+<!ENTITY InputStream "<ulink url='&Java;java/io/InputStream.html'><interface>InputStream</interface></ulink>">
+<!ENTITY IOException "<ulink url='&Java;java/io/IOException.html'><classname>IOException</classname></ulink>">
+<!ENTITY ClassLoader "<ulink url='&Java;java/lang/ClassLoader.html'><interface>ClassLoader</interface></ulink>">
+<!ENTITY AccessControlContext "<ulink url='&Java;java/security/AccessController.html'><classname>AccessControlContext</classname></ulink>">
+<!ENTITY LoginContext "<ulink url='&Java;javax/security/auth/login/LoginContext.html'><classname>LoginContext</classname></ulink>">
+<!ENTITY Subject "<ulink url='&Java;javax/security/auth/Subject.html'><classname>Subject</classname></ulink>">
+<!ENTITY CallbackHandler "<ulink url='&Java;javax/security/auth/callback/CallbackHandler.html'><interface>CallbackHandler</interface></ulink>">
+<!ENTITY ExecutorService "<ulink url='&Java;java/util/concurrent/ExecutorService.html'><interface>ExecutorService</interface></ulink>">
+<!ENTITY TimeUnit "<ulink url='&Java;java/util/concurrent/TimeUnit.html'><interface>TimeUnit</interface></ulink>">
+<!ENTITY UUID "<ulink url='&Java;java/util/UUID.html'><classname>UUID</classname></ulink>">
+<!ENTITY DataSource "<ulink url='&Java;javax/sql/DataSource.html'><classname>DataSource</classname></ulink>">
+
+
+<!-- Types in JCR API -->
+
+<!ENTITY Repository "<interface>Repository</interface>">
+<!ENTITY Session "<interface>Session</interface>">
+<!ENTITY Credentials "<interface>Credentials</interface>">
+<!ENTITY SimpleCredentials "<interface>SimpleCredentials</interface>">
+
+<!-- Types in dna-common -->
+
+<!ENTITY Logger "<ulink url='&API;common/util/Logger.html'><interface>Logger</interface></ulink>">
+<!ENTITY ClassLoaderFactory "<ulink url='&API;common/component/ClassLoaderFactory.html'><interface>ClassLoaderFactory</interface></ulink>">
+<!ENTITY StandardClassLoaderFactory "<ulink url='&API;common/component/StandardClassLoaderFactory.html'><classname>StandardClassLoaderFactory</classname></ulink>">
+
+<!-- Types in dna-graph -->
+
+<!ENTITY Graph "<ulink url='&API;graph/Graph.html'><classname>Graph</classname></ulink>">
+<!ENTITY GraphBatch "<ulink url='&API;graph/Graph.Batch.html'><classname>Graph.Batch</classname></ulink>">
+<!ENTITY Subgraph "<ulink url='&API;graph/Subgraph.html'><interface>Subgraph</interface></ulink>">
+<!ENTITY Node "<ulink url='&API;graph/Node.html'><interface>Node</interface></ulink>">
+<!ENTITY Workspace "<ulink url='&API;graph/Workspace.html'><interface>Workspace</interface></ulink>">
+<!ENTITY Results "<ulink url='&API;graph/Results.html'><interface>Results</interface></ulink>">
+<!ENTITY Location "<ulink url='&API;graph/Location.html'><classname>Location</classname></ulink>">
+<!ENTITY ExecutionContext "<ulink url='&API;graph/ExecutionContext.html'><classname>ExecutionContext</classname></ulink>">
+<!ENTITY Name "<ulink url='&API;graph/property/Name.html'><interface>Name</interface></ulink>">
+<!ENTITY Path "<ulink url='&API;graph/property/Path.html'><interface>Path</interface></ulink>">
+<!ENTITY PathSegment "<ulink url='&API;graph/property/Path.Segment.html'><interface>Path.Segment</interface></ulink>">
+<!ENTITY Property "<ulink url='&API;graph/property/Property.html'><interface>Property</interface></ulink>">
+<!ENTITY ValueFactories "<ulink url='&API;graph/property/ValueFactories.html'><interface>ValueFactories</interface></ulink>">
+<!ENTITY NamespaceRegistry "<ulink url='&API;graph/property/NamespaceRegistry.html'><interface>NamespaceRegistry</interface></ulink>">
+<!ENTITY PropertyFactory "<ulink url='&API;graph/property/PropertyFactory.html'><interface>PropertyFactory</interface></ulink>">
+<!ENTITY PathNotFoundException "<ulink url='&API;graph/property/PathNotFoundException.html'><classname>PathNotFoundException</classname></ulink>">
+<!ENTITY RepositorySource "<ulink url='&API;graph/connector/RepositorySource.html'><interface>RepositorySource</interface></ulink>">
+<!ENTITY RepositoryConnection "<ulink url='&API;graph/connector/RepositoryConnection.html'><interface>RepositoryConnection</interface></ulink>">
+<!ENTITY RepositoryConnectionFactory "<ulink url='&API;graph/connector/RepositoryConnectionFactory.html'><interface>RepositoryConnectionFactory</interface></ulink>">
+<!ENTITY RepositorySourceListener "<ulink url='&API;graph/connector/RepositorySourceListener.html'><interface>RepositorySourceListener</interface></ulink>">
+<!ENTITY RepositorySourceCapabilities "<ulink url='&API;graph/connector/RepositorySourceCapabilities.html'><classname>RepositorySourceCapabilities</classname></ulink>">
+<!ENTITY InMemoryRepository "<ulink url='&API;graph/connector/inmemory/InMemoryRepository.html'><classname>InMemoryRepository</classname></ulink>">
+<!ENTITY InMemoryRepositorySource "<ulink url='&API;graph/connector/inmemory/InMemoryRepositorySource.html'><classname>InMemoryRepositorySource</classname></ulink>">
+<!ENTITY FederatedRepository "<ulink url='&API;graph/connector/federation/FederatedRepository.html'><classname>FederatedRepository</classname></ulink>">
+<!ENTITY FederatedRepositorySource "<ulink url='&API;graph/connector/federation/FederatedRepositorySource.html'><classname>FederatedRepositorySource</classname></ulink>">
+<!ENTITY Projection "<ulink url='&API;graph/connector/federation/Projection.html'><classname>Projection</classname></ulink>">
+<!ENTITY CachePolicy "<ulink url='&API;graph/cache/CachePolicy.html'><interface>CachePolicy</interface></ulink>">
+<!ENTITY Request "<ulink url='&API;graph/request/Request.html'><classname>Request</classname></ulink>">
+<!ENTITY CompositeRequest "<ulink url='&API;graph/request/CompositeRequest.html'><classname>CompositeRequest</classname></ulink>">
+<!ENTITY ReadNodeRequest "<ulink url='&API;graph/request/ReadNodeRequest.html'><classname>ReadNodeRequest</classname></ulink>">
+<!ENTITY CopyBranchRequest "<ulink url='&API;graph/request/CopyBranchRequest.html'><classname>CopyBranchRequest</classname></ulink>">
+<!ENTITY InvalidRequestException "<ulink url='&API;graph/request/InvalidRequestException.html'><classname>InvalidRequestException</classname></ulink>">
+<!ENTITY InvalidWorkspaceException "<ulink url='&API;graph/request/InvalidWorkspaceException.html'><classname>InvalidWorkspaceException</classname></ulink>">
+<!ENTITY UnsupportedRequestException "<ulink url='&API;graph/request/UnsupportedRequestException.html'><classname>UnsupportedRequestException</classname></ulink>">
+<!ENTITY RequestProcessor "<ulink url='&API;graph/request/processor/RequestProcessor.html'><classname>RequestProcessor</classname></ulink>">
+<!ENTITY StreamSequencer "<ulink url='&API;graph/sequencer/StreamSequencer.html'><interface>StreamSequencer</interface></ulink>">
+<!ENTITY SequencerOutput "<ulink url='&API;graph/sequencer/SequencerOutput.html'><interface>SequencerOutput</interface></ulink>">
+<!ENTITY SequencerContext "<ulink url='&API;graph/sequencer/SequencerContext.html'><interface>SequencerContext</interface></ulink>">
+<!ENTITY MimeTypeDetector "<ulink url='&API;graph/mimetype/MimeTypeDetector.html'><interface>MimeTypeDetector</interface></ulink>">
+<!ENTITY MockSequencerOutput "<ulink url='&API;graph/sequencer/MockSequencerOutput.html'><interface>MockSequencerOutput</interface></ulink>">
+<!ENTITY MockSequencerContext "<ulink url='&API;graph/sequencer/MockSequencerContext.html'><interface>MockSequencerContext</interface></ulink>">
+
+<!-- Types in dna-repository -->
+
+<!ENTITY DnaEngine "<ulink url='&API;repository/DnaEngine.html'><classname>DnaEngine</classname></ulink>">
+<!ENTITY DnaConfiguration "<ulink url='&API;repository/DnaConfiguration.html'><classname>DnaConfiguration</classname></ulink>">
+<!ENTITY RepositoryLibrary "<ulink url='&API;repository/RepositoryLibrary.html'><classname>RepositoryLibrary</classname></ulink>">
+<!ENTITY RepositoryService "<ulink url='&API;repository/RepositoryService.html'><classname>RepositoryService</classname></ulink>">
+<!ENTITY ServiceAdministrator "<ulink url='&API;repository/service/ServiceAdministrator.html'><interface>ServiceAdministrator</interface></ulink>">
+<!ENTITY SequencingService "<ulink url='&API;repository/sequencer/SequencingService.html'><classname>SequencingService</classname></ulink>">
+<!ENTITY SequencerConfig "<ulink url='&API;repository/sequencer/SequencerConfig.html'><classname>SequencerConfig</classname></ulink>">
+<!ENTITY SessionFactory "<ulink url='&API;repository/util/SessionFactory.html'><interface>SessionFactory</interface></ulink>">
+<!ENTITY JndiSessionFactory "<ulink url='&API;repository/util/JndiSessionFactory.html'><classname>JndiSessionFactory</classname></ulink>">
+<!ENTITY SimpleSessionFactory "<ulink url='&API;repository/util/SimpleSessionFactory.html'><classname>SimpleSessionFactory</classname></ulink>">
+<!ENTITY JcrExecutionContext "<ulink url='&API;repository/util/JcrExecutionContext.html'><interface>JcrExecutionContext</interface></ulink>">
+<!ENTITY MimeType "<ulink url='&API;repository/mimetype/MimeType.html'><classname>MimeType</classname></ulink>">
+<!ENTITY MimeTypeDetectorConfig "<ulink url='&API;repository/mimetype/MimeTypeDetectorConfig.html'><interface>MimeTypeDetectorConfig</interface></ulink>">
+
+
+<!-- Types in dna-jcr -->
+
+<!ENTITY JcrEngine "<ulink url='&API;jcr/JcrEngine.html'><classname>JcrEngine</classname></ulink>">
+<!ENTITY JcrConfiguration "<ulink url='&API;jcr/JcrConfiguration.html'><classname>JcrConfiguration</classname></ulink>">
+<!ENTITY JcrRepository "<ulink url='&API;jcr/JcrRepository.html'><classname>JcrRepository</classname></ulink>">
+<!ENTITY JcrSession "<ulink url='&API;jcr/JcrSession.html'><classname>JcrSession</classname></ulink>">
+
+<!-- Types in extensions/ -->
+
+<!ENTITY JBossCacheRepository "<ulink url='&API;connector/jbosscache/JBossCacheRepository.html'><classname>JBossCacheRepository</classname></ulink>">
+<!ENTITY JBossCacheSource "<ulink url='&API;connector/jbosscache/JBossCacheSource.html'><classname>JBossCacheSource</classname></ulink>">
+<!ENTITY ImageMetadataSequencer "<ulink url='&API;sequencer/image/ImageMetadataSequencer.html'><classname>ImageMetadataSequencer</classname></ulink>">
+<!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>">
+
Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -25,9 +25,8 @@
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY versionNumber "0.4">
-<!ENTITY copyrightYear "2008-2009">
-<!ENTITY copyrightHolder "Red Hat, Inc.">
+<!ENTITY % CustomDTD SYSTEM "custom.dtd">
+%CustomDTD;
]>
<book lang="en">
<bookinfo>
@@ -35,7 +34,7 @@
<subtitle>Getting Started Guide</subtitle>
<releaseinfo>&versionNumber;</releaseinfo>
<productnumber>&versionNumber;</productnumber>
- <issuenum>4</issuenum>
+ <issuenum>5</issuenum>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="dna-logo.png" align="center"/>
@@ -53,10 +52,10 @@
</bookinfo>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/preface.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/introduction.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/understanding_dna.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/use_cases.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/using_dna.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/downloading_and_running.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/using_dna_for_sequencing.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/using_dna_repositories.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/custom_sequencers.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/future.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/sequencer_example.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/repository_example.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/conclusion.xml"/>
</book>
Modified: trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml 2009-06-07 15:05:15 UTC (rev 988)
+++ trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml 2009-06-07 22:33:45 UTC (rev 989)
@@ -225,14 +225,20 @@
<para>This profile informs Maven of the two JBoss repositories (<ulink url="http://repository.jboss.org/maven2">snapshots</ulink>
and <ulink url="http://snapshots.jboss.org/maven2">releases</ulink>) that contain all of the JARs for JBoss DNA and all dependent libraries.
</para>
+ <para>While you're adding <code>$MAVEN_HOME/bin</code> to your path, you should also set the <code>$MAVEN_OPTS</code> environment variable
+ to "<code>-Xmx256m</code>". If you don't do this, you'll likely see an <code>java.lang.OutOfMemoryError</code> sometime during a full
+ build.
<note>
<para>
- It is a policy of the project that the <emphasis>source code and JARs</emphasis> for <emphasis>all</emphasis> dependencies
- <emphasis>must</emphasis> be loaded into the JBoss repository. This is so that the project can always be built
- and that all source code is always available.
+ The JBoss Maven repository provides a central location for not only the artifacts produced by the JBoss.org projects (well, at least those
+ that use Maven), but also is where those projects can place the artifacts that they depend on. JBoss DNA has a policy that
+ the <emphasis>source code and JARs</emphasis> for <emphasis>all</emphasis> dependencies <emphasis>must</emphasis> be loaded into the
+ JBoss Maven repository. It may be a little bit more work for the developers, but it does help ensure that developers have easy
+ access to the source and that the project (and dependencies) can always be rebuilt when needed.
</para>
<para>
- For more information about the JBoss Maven repository, see the <ulink url="http://wiki.jboss.org/wiki/Maven">JBoss.org Wiki</ulink>.
+ For more information about the JBoss Maven repository, including instructions for adding source and JAR artifacts,
+ see the <ulink url="http://wiki.jboss.org/wiki/Maven">JBoss.org Wiki</ulink>.
</para>
</note>
<para>
More information about the dna-commits
mailing list