[dna-commits] DNA SVN: r497 - in trunk: docs/gettingstarted and 6 other directories.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Thu Sep 4 13:44:52 EDT 2008
Author: rhauch
Date: 2008-09-04 13:44:52 -0400 (Thu, 04 Sep 2008)
New Revision: 497
Added:
trunk/docs/gettingstarted/src/
trunk/docs/gettingstarted/src/main/
trunk/docs/gettingstarted/src/main/docbook/
trunk/docs/gettingstarted/src/main/docbook/en-US/
trunk/docs/gettingstarted/src/main/docbook/en-US/Getting_Started.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/
trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.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/content/understanding_dna.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna.xml
trunk/docs/gettingstarted/src/main/docbook/en-US/images/
trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-architecture.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-logo.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-cli-client.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search-with-mp3.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search2.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics2.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload.png
trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload2.png
Removed:
trunk/docs/gettingstarted/en/
Modified:
trunk/build/assembly/dist.xml
trunk/docs/gettingstarted/pom.xml
Log:
Restructured the Getting Started document to use the newer JBoss.org styles, including code formatting
Modified: trunk/build/assembly/dist.xml
===================================================================
--- trunk/build/assembly/dist.xml 2008-09-04 14:34:21 UTC (rev 496)
+++ trunk/build/assembly/dist.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -30,7 +30,7 @@
<!--
Gather into the distribution the Getting Started document
-->
- <directory>docs/gettingstarted/target/docbook</directory>
+ <directory>docs/gettingstarted/target/docbook/publish/en-US</directory>
<outputDirectory>manuals/gettingstarted</outputDirectory>
</fileSet>
</fileSets>
Modified: trunk/docs/gettingstarted/pom.xml
===================================================================
--- trunk/docs/gettingstarted/pom.xml 2008-09-04 14:34:21 UTC (rev 496)
+++ trunk/docs/gettingstarted/pom.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -1,17 +1,79 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>org.jboss</groupId>
- <artifactId>documentation</artifactId>
- <version>1.0</version>
- </parent>
-
- <groupId>org.jboss.dna</groupId>
- <artifactId>getting-started-${translation}</artifactId>
- <version>0.2-SNAPSHOT</version>
- <packaging>jdocbook</packaging>
- <name>JBoss DNA Getting Started Document (${translation})</name>
-
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <!--
+ parent> <groupId>org.jboss</groupId> <artifactId>documentation</artifactId> <version>1.0</version> </parent
+ -->
+ <groupId>org.jboss.dna</groupId>
+ <artifactId>getting-started-en</artifactId>
+ <version>0.2-SNAPSHOT</version>
+ <packaging>jdocbook</packaging>
+ <name>JBoss DNA Getting Started manual</name>
+ <description>The JBoss DNA Getting Started manual</description>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.jboss.maven.plugins</groupId>
+ <artifactId>maven-jdocbook-plugin</artifactId>
+ <version>2.1.2</version>
+ <extensions>true</extensions>
+ <dependencies>
+ <!--
+ <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-jdocbook-style</artifactId>
+ <version>1.0.2</version> <type>jdocbook-style</type> </dependency>
+ -->
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-docbook-xslt</artifactId>
+ <version>1.1.0.Beta1</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jbossorg-jdocbook-style</artifactId>
+ <version>1.1.0.Beta1</version>
+ <type>jdocbook-style</type>
+ </dependency>
+ </dependencies>
+ <configuration>
+ <sourceDocumentName>Getting_Started.xml</sourceDocumentName>
+ <imageResource>
+ <directory>${basedir}/src/main/docbook/en-US/images</directory>
+ <includes>
+ <include>*.png</include>
+ </includes>
+ </imageResource>
+ <!-- cssResource>
+ <directory>${basedir}/src/main/docbook/css</directory>
+ </cssResource-->
+ <targetDirectory>${basedir}/target/docbook/en-US</targetDirectory>
+ <formats>
+ <format>
+ <formatName>html</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ <!--
+ <format>
+ <formatName>html_single</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/xhtml-single.xsl</stylesheetResource>
+ <finalName>index.html</finalName>
+ </format>
+ -->
+ <format>
+ <formatName>pdf</formatName>
+ <stylesheetResource>classpath:/xslt/org/jboss/pdf.xsl</stylesheetResource>
+ <finalName>userguide_en.pdf</finalName>
+ </format>
+ </formats>
+ <options>
+ <xincludeSupported>true</xincludeSupported>
+ <xmlTransformerType>saxon</xmlTransformerType>
+ <!-- needed for uri-resolvers; can be ommitted if using 'current' uri scheme -->
+ <!-- could also locate the docbook dependency and inspect its version... -->
+ <docbookVersion>1.72.0</docbookVersion>
+ </options>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
</project>
\ No newline at end of file
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/Getting_Started.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/Getting_Started.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/Getting_Started.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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 book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY versionNumber "0.3">
+<!ENTITY copyrightYear "2008">
+<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>JBoss DNA</title>
+ <subtitle>Getting Started Guide</subtitle>
+ <releaseinfo>&versionNumber;</releaseinfo>
+ <productnumber>&versionNumber;</productnumber>
+ <issuenum>1</issuenum>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="dna-logo.png" align="center"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="dna-logo.png" depth="3cm"/>
+ </imageobject>
+ </mediaobject>
+ <copyright>
+ <year>©rightYear;</year>
+ <holder>©rightHolder;</holder>
+ </copyright>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/author_group.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/legal_notice.xml"/>
+ </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/downloading_and_running.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/custom_sequencers.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="content/future.xml"/>
+</book>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/author_group.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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 authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<authorgroup>
+ <corpauthor>Randall M. Hauch</corpauthor>
+ <corpauthor>John Verhaeg</corpauthor>
+ <corpauthor>Stefano Maestri</corpauthor>
+ <corpauthor>Serge Emmanuel Pagop</corpauthor>
+</authorgroup>
\ No newline at end of file
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/custom_sequencers.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,403 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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 two sequencers: one that extracts metadata from a variety of image file formats,
+ and another that extracts some of the ID3 metadata from MP3 audio files. 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.1</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.dna</groupId>
+ <artifactId>dna-spi</artifactId>
+ <version>0.1</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[
+<dependency>
+ <groupId>org.jboss.dna</groupId>
+ <artifactId>dna-repository</artifactId>
+ <version>0.1</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>
+<!-- Apache Jackrabbit (JCR Implementation) -->
+<dependency>
+ <groupId>org.apache.jackrabbit</groupId>
+ <artifactId>jackrabbit-api</artifactId>
+ <version>1.3.3</version>
+ <scope>test</scope>
+ <!-- Exclude these since they are included in JDK 1.5 -->
+ <exclusions>
+ <exclusion>
+ <groupId>xml-apis</groupId>
+ <artifactId>xml-apis</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>xerces</groupId>
+ <artifactId>xercesImpl</artifactId>
+ </exclusion>
+ </exclusions>
+</dependency>
+<dependency>
+ <groupId>org.apache.jackrabbit</groupId>
+ <artifactId>jackrabbit-core</artifactId>
+ <version>1.3.3</version>
+ <scope>test</scope>
+ <!-- Exclude these since they are included in JDK 1.5 -->
+ <exclusions>
+ <exclusion>
+ <groupId>xml-apis</groupId>
+ <artifactId>xml-apis</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>xerces</groupId>
+ <artifactId>xercesImpl</artifactId>
+ </exclusion>
+ </exclusions>
+</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 progressMonitor the progress monitor that should be kept
+ * updated with the sequencer's progress and that should be
+ * frequently consulted as to whether this operation has been cancelled.
+ */
+ void sequence( InputStream stream, SequencerOutput output, ProgressMonitor progressMonitor );
+ ]]></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>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,
+ ProgressMonitor progressMonitor ) {
+ progressMonitor.beginTask(10, ImageSequencerI18n.sequencerTaskName);
+
+ 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;
+ }
+ progressMonitor.worked(5);
+ if (progressMonitor.isCancelled()) return;
+
+ // 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());
+ }
+
+ progressMonitor.done();
+ }
+}
+ ]]></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>
+ <para>Also note how the progress monitor is used. Reporting progress through the supplied <code>ProgressMonitor</code> is very easy, and it ensures that JBoss DNA
+ can accurately monitor and report the status of sequencing activities to the users. At the beginning of the operation, call
+ <code>beginTask(...)</code> with a meaningful message describing
+ the operation and a total for the amount of work that will be done by this sequencer. Then perform the sequencing work,
+ periodically reporting work by specifying the incremental amount of work with the <code>worked(double)</code> method, or
+ by creating a subtask with the <code>createSubtask(double)</code> method and reporting work against that subtask
+ monitor.
+ </para>
+ <para>Your method should periodically use the ProgressMonitor's <code>isCancelled()</code> method to check whether the operation has been
+ cancelled.. If this method returns true, the implementation should abort all work as
+ soon as possible and close any resources that were acquired or opened.
+ </para>
+ <para>
+ Finally, when your sequencing operation is completed, it should call <code>done()</code> on the progress monitor.
+ </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();
+ProgressMonitor progress = new SimpleProgressMonitor("Test activity");
+InputStream stream = null;
+try {
+ stream = this.getClass().getClassLoader().getResource("caution.gif").openStream();
+ sequencer.sequence(stream,output,progress); // 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();
+ProgressMonitor progress = new SimpleProgressMonitor("Test activity");
+InputStream stream = null;
+try {
+ stream = this.getClass().getClassLoader().getResource("caution.pict").openStream();
+ sequencer.sequence(stream,output,progress); // 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>
Added: 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 (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,282 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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="downloading_and_running">
+ <title>Running the example application</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>
+ <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
+ depends on the JBoss DNA JARs.</para>
+ <note>
+ <para>
+ To use Maven with JBoss DNA, you'll need to have <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK 5 or 6</ulink>
+ and Maven 2.0.7 (or higher).</para>
+ <para>
+ Maven can be downloaded from <ulink url="http://maven.apache.org/">http://maven.apache.org/</ulink>, and is installed by unzipping the
+ <code>maven-2.0.7-bin.zip</code> file to a convenient location on your local disk. Simply add <code>$MAVEN_HOME/bin</code>
+ to your path and add the following profile to your <code>~/.m2/settings.xml</code> file:</para>
+ <programlisting role="XML"><![CDATA[
+<settings>
+ <profiles>
+ <profile>
+ <id>jboss.repository</id>
+ <activation>
+ <property>
+ <name>!jboss.repository.off</name>
+ </property>
+ </activation>
+ <repositories>
+ <repository>
+ <id>snapshots.jboss.org</id>
+ <url>http://snapshots.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </repository>
+ <repository>
+ <id>repository.jboss.org</id>
+ <url>http://repository.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </repository>
+ </repositories>
+ <pluginRepositories>
+ <pluginRepository>
+ <id>repository.jboss.org</id>
+ <url>http://repository.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>false</enabled>
+ </snapshots>
+ </pluginRepository>
+ <pluginRepository>
+ <id>snapshots.jboss.org</id>
+ <url>http://snapshots.jboss.org/maven2</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+ </pluginRepository>
+ </pluginRepositories>
+ </profile>
+ </profiles>
+</settings>
+]]></programlisting>
+ <para>This profile informs Maven of the two JBoss repositories (snapshots and releases) that contain
+ all of the JARs for JBoss DNA and all dependent libraries.</para>
+ </note>
+ <sect1 id="downloading">
+ <title>Downloading and compiling</title>
+ <para>The next step is to <ulink url="http://www.jboss.org/file-access/default/members/dna/downloads/0.1/jboss-dna-0.1-gettingstarted-examples.zip">download</ulink>
+ the example for this Getting Started guide, and extract the contents to a convenient location on your local disk.
+ You'll find the example contains the following files, which are organized according to the standard Maven directory structure:</para>
+ <programlisting><![CDATA[
+examples/pom.xml
+ sequencers/pom.xml
+ /src/main/assembly
+ /config
+ /java
+ /resources
+ /test/java
+ /resources
+]]></programlisting>
+ <para>There are essentially two Maven projects: a <code>sequencers</code> project and a parent project. All of the source
+ for the example is located in the <code>sequencers</code> subdirectory. And you may have noticed that none
+ of the JBoss DNA libraries are there. This is where Maven comes in. The two <code>pom.xml</code> files tell
+ Maven everything it needs to know about what libraries are required and how to build the example.</para>
+ <para>In a terminal, go to the <code>examples</code> directory and run <emphasis role="strong"><code>mvn install</code></emphasis>.
+ This command downloads all of the JARs necessary to compile and build the example, including the JBoss DNA libraries,
+ the libraries they depend on, and any missing Maven components. (These are downloaded from the JBoss repositories
+ only once and saved on your machine. This means that the next time you run Maven, all the libraries will
+ already be available locally, and the build will run much faster.) The command then continues by compiling the example's source
+ code (and unit tests) and running the unit tests. The build is successful if you see the following:</para>
+ <programlisting><![CDATA[
+$ mvn install
+...
+[INFO] ------------------------------------------------------------------------
+[INFO] Reactor Summary:
+[INFO] ------------------------------------------------------------------------
+[INFO] Getting Started examples .............................. SUCCESS [2.106s]
+[INFO] Sequencer Examples .................................... SUCCESS [9.768s]
+[INFO] ------------------------------------------------------------------------
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 12 seconds
+[INFO] Finished at: Wed May 07 12:00:06 CDT 2008
+[INFO] Final Memory: 14M/28M
+[INFO] ------------------------------------------------------------------------
+$ ]]></programlisting>
+ <para>If there are errors, check whether you have the correct version of Maven installed and that you've correctly updated
+ your Maven settings as described above.</para>
+ <para>If you've successfully built the examples, there will be a new <code>examples/sequencers/target/</code> directory that contains
+ all of the generated output, including a <code>dna-example-sequencers-basic.dir/</code> subdirectory that contains the following:
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="strong"><code>run.sh</code></emphasis> is the *nix shell script that will run the example.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>log4j.properties</code></emphasis>
+ is the Log4J configuration file.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>jackrabbitConfig.xml</code></emphasis>
+ is the Jackrabbit configuration file, which is set up to use a transient in-memory repository.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>jackrabbitNodeTypes.cnd</code></emphasis>
+ defines the additional JCR node types used by this example.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>sample1.mp3</code></emphasis>
+ is a sample MP3 audio file you'll use later to upload into the repository.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>caution.gif</code></emphasis>, <emphasis role="strong"><code>caution.png</code></emphasis>, and <emphasis role="strong"><code>caution.jpg</code></emphasis>
+ are images that you'll use later and upload into the repository.
+ </para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="strong"><code>lib</code></emphasis>
+ subdirectory contains the JARs for all of the JBoss DNA artifacts as well as those for other libraries required
+ by JBoss DNA and the example.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>JBoss DNA 0.1 and the examples are currently tested with <ulink url="http://jackrabbit.apache.org/">Apache Jackrabbit</ulink> version 1.3.3.
+ This version is stable and used by a number of other projects and applications. However, you should be able to use a newer
+ version of Jackrabbit, as long as that version uses the same JCR API. For example, version 1.4.2 was released on March 26, 2008 and
+ should be compatible.</para>
+ <para>Just remember, if the version of Jackrabbit you want to use for these examples is not in the Maven repository,
+ you'll have to either add it or add it locally. For more information, see the <ulink url="http://maven.apache.org/">Maven documentation</ulink>.
+ </para>
+ </note>
+ </sect1>
+ <sect1 id="running">
+ <title>Running the example</title>
+ <para>This 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-cli-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 and MP3 audio files and 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. 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="downloading_and_running_review">
+ <title>Summarizing what we just did</title>
+ <para>In this chapter you downloaded and installed the example application and used it to upload files into a
+ JCR repository. JBoss DNA automatically sequenced the image and/or MP3 files you uploaded, extracted the metadata from the
+ files, and stored that metadata inside the repository. The application allowed you to see this metadata
+ and the sequencing statistics.</para>
+ <para>This application was very simplistic. In fact, running through the example probably only took you a minute or two.
+ So while this application won't win any awards, it does show the basics of what JBoss DNA can do.</para>
+ <para>In the <link linkend="using_dna">next chapter</link> we'll venture into the code to get an understanding
+ of how JBoss DNA actually works and how you can use it in your own applications.</para>
+ </sect1>
+</chapter>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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.
+ 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>
+ <para>The next release will focus on creating the <link linkend="federation">federation engine</link> and connectors
+ for several popular and ubiquitous systems. The 0.2 release will likely only federate information in a read-only manner,
+ but updates will soon follow. Also, during the early part of the next release, the JBoss DNA project will switch to use JDK 6.
+ Java 5 is being end-of-lifed, so we want to move to a supported JDK. However, a number of JBoss projects and products continue to
+ require Java 5, so our next release will most likely use JDK 6 with Java 5 compatibility.</para>
+ <para>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. If any of these are of interest to you, please <link linkend="preface">get involved</link>
+ in the community.</para>
+</chapter>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,119 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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="introduction">
+ <title>Introduction</title>
+ <para>There are a lot of choices for how applications can store information persistently so that it can be accessed at a
+ later time and by other processes. The challenge developers face is how to use an approach that most closely matches the
+ needs of their application. This choice becomes more important as developers choose to focus their efforts on
+ application-specific logic, delegating much of the responsibilities for persistence to libraries and frameworks.</para>
+ <para>
+ Perhaps one of the easiest techniques is to simply store information in
+ <emphasis>files</emphasis>
+ . The Java language makes working with files relatively easy, but Java really doesn't provide many bells and whistles. So
+ using files is an easy choice when the information is either not complicated (for example property files), or when users may
+ need to read or change the information outside of the application (for example log files or configuration files). But using
+ files to persist information becomes more difficult as the information becomes more complex, as the volume of it increases,
+ or if it needs to be accessed by multiple processes. For these situations, other techniques often offer better choices.
+ </para>
+ <para>
+ Another technique built into the Java language is
+ <emphasis>Java serialization</emphasis>
+ , which is capable of persisting the state of an object graph so that it can be read back in at a later time. However, Java
+ serialization can quickly become tricky if the classes are changed, and so it's beneficial usually when the information is
+ persisted for a very short period of time. For example, serialization is sometimes used to send an object graph from one
+ process to another.
+ </para>
+ <para>
+ One of the more popular persistence technologies is the
+ <emphasis>relational database</emphasis>
+ . Relational database management systems have been around for decades and are very capable. The Java Database Connectivity
+ (JDBC) API provides a standard interface for connecting to and interacting with relational databases. However, it is a
+ low-level API that requires a lot of code to use correctly, and it still doesn't abstract away the DBMS-specific SQL
+ grammar. Also, working with relational data in an object-oriented language can feel somewhat unnatural, so many developers
+ map this data to classes that fit much more cleanly into their application. The problem is that manually creating this
+ mapping layer requires a lot of repetitive and non-trivial JDBC code.
+ </para>
+ <para>
+ <emphasis>Object-relational mapping</emphasis>
+ libraries automate the creation of this mapping layer and result in far less code that is much more maintainable with
+ performance that is often as good as (if not better than) handwritten JDBC code. The new
+ <ulink url="http://java.sun.com/developer/technicalArticles/J2EE/jpa/">Java Persistence API (JPA)</ulink>
+ provide a standard mechanism for defining the mappings (through annotations) and working with these entity objects. Several
+ commercial and open-source libraries implement JPA, and some even offer additional capabilities and features that go beyond
+ JPA. For example,
+ <ulink url="http://www.hibernate.org">Hibernate</ulink>
+ is one of the most feature-rich JPA implementations and offers object caching, statement caching, extra association
+ mappings, and other features that help to improve performance and usefulness.
+ </para>
+ <para>
+ While relational databases and JPA are solutions that work for many applications, they become more limited in cases when the
+ information structure is highly flexible, is not known
+ <emphasis>a priori</emphasis>
+ , or is subject to frequent change and customization. In these situations,
+ <emphasis>content repositories</emphasis>
+ may offer a better choice for persistence. Content repositories are almost a hybrid between relational databases and file
+ systems, and typically provide other capabilities as well, including versioning, indexing, search, access control,
+ transactions, and observation. Because of this, content repositories are used by content management systems (CMS), document
+ management systems (DMS), and other applications that manage electronic files (e.g., documents, images, multi-media, web
+ content, etc.) and metadata associated with them (e.g., author, date, status, security information, etc.). The
+ <ulink url="http://www.jcp.org/en/jsr/detail?id=170">Content Repository for Java technology API</ulink>
+ provides a standard Java API for working with content repositories. Abbreviated "JCR", this API was developed as part of the
+ Java Community Process under
+ <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JSR-170</ulink>
+ 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 the tools and services that surround content repositories. 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 is building other features as well. One goal of JBoss DNA is to create federated repositories that
+ dynamically merge the information from multiple databases, services, applications, and other JCR repositories. Another is to
+ create customized views based upon the type of data and the role of the user that is accessing the data. And yet another 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 in your applications, while
+ <link linkend="custom_sequencers">Chapter 5</link>
+ goes over how to create custom sequencers. Finally,
+ <link linkend="future">Chapter 6</link>
+ wraps things up with a discussion about the future of JBoss DNA.
+ </para>
+</chapter>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,57 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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 legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<legalnotice id="Legal_Notice">
+ <title>Legal Notice</title>
+ <para>
+ <address>
+ <street>1801 Varsity Drive</street>
+ <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country>
+ <phone>Phone: +1 919 754 3700</phone>
+ <phone>Phone: 888 733 4281</phone>
+ <fax>Fax: +1 919 754 3701</fax>
+ <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
+ </address>
+ </para>
+ <para>
+ Copyright <trademark class="copyright"/> 2007 by Red Hat, Inc. This copyrighted material is made available to
+ anyone wishing to use, modify, copy, or redistribute it subject to the terms and conditions of the
+ GNU <ulink url="http://www.gnu.org/licenses/lgpl-2.1.html">Lesser General Public License</ulink>, as published
+ by the Free Software Foundation.
+ </para>
+ <para>
+ Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other countries.
+ </para>
+ <para>
+ All other trademarks referenced herein are the property of their respective owners.
+ </para>
+ <para>
+ The GPG fingerprint of the security at redhat.com key is:
+ </para>
+ <para>
+ CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
+ </para>
+</legalnotice>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/preface.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program is distributed in the hope that it will be useful,
+ ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ ~ or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+ ~ for more details.
+ ~
+ ~ You should have received a copy of the GNU Lesser General Public License
+ ~ along with this distribution; if not, write to:
+ ~ Free Software Foundation, Inc.
+ ~ 51 Franklin Street, Fifth Floor
+ ~ Boston, MA 02110-1301 USA
+ -->
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<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
+ most out of your JCR repositories.</para>
+ <para>The first part of the book starts out with an introduction to content repositories and an overview of the JCR API,
+ both of which are important aspects of JBoss DNA. This is followed by an overview of the JBoss DNA project, its
+ architecture, and a basic roadmap for what's coming next.</para>
+ <para>The next part of the book covers how to download and build the examples, how to use JBoss DNA with existing
+ repositories, and how to build and use custom sequencers.</para>
+ <para>
+ 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>
+ . If you'd like to get involved on the project, join the
+ <ulink url="http://www.jboss.org/dna/lists.html">mailing lists</ulink>
+ ,
+ <ulink url="http://www.jboss.org/dna/subversion.html">download the code</ulink>
+ and get it building, and visit our
+ <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>
+</preface>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml
===================================================================
--- trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml (rev 0)
+++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,525 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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 allows 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 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.</para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/dna-architecture.png" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/dna-architecture.png" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ As shown in the diagram above, the major components are (starting at the top):
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="strong">DNA Eclipse Plugins</emphasis>
+ enable Eclipse users to access the contents of a JBoss DNA repository.
+ </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.
+ </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. Since WebDAV is an extension of HTTP, web browsers are able to read (but not modify) 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 Sequencers</emphasis>
+ are pluggable components that make it possible for content to be uploaded to the repository and automatically
+ processed to extract meaningful structure and place 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">DNA Analyses</emphasis>
+ are pluggable components that analyze content and the relationships between content to generate reports or to answer
+ queries. DNA will include some standard analyzers, like dependency analysis and similarity analysis, that are
+ commonly needed by many different solutions. DNA analyzers operate 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>
+ <listitem>
+ <para>
+ <emphasis role="strong">DNA Federation</emphasis>
+ is an implementation of the JCR API that builds the content within the repository by accessing and integrating
+ information from multiple sources. DNA Federation allows the integration of external systems, like other JCR
+ repositories, databases, applications, and services.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">DNA Connectors</emphasis>
+ are used to communicate with these external sources of information. In the federation engine, each source is able to
+ contribute node structure and node properties to any part of the federated graph, although typically many connectors
+ will contribute most of their information to isolated subgraphs. The result is that integration from a wide range of
+ systems can be integrated and accessed through the DNA Web Application, DNA Publishing Server, and DNA WebDAV
+ Server. Connectors also may optionally participate in distributed transactions by exposing an XAResource.
+ </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.
+ </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>
+ that will be the focus of the next release. 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 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-26</ulink>
+ .)
+ </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">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">ZIP Archive Sequencer</emphasis>
+ - Process ZIP archive files to extract (explode) the contents into the repository. (See
+ <ulink url="http://jira.jboss.org/jira/browse/DNA-63">DNA-63</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">Java Source File Sequencer</emphasis>
+ - Process Java source files to extract the class structure (including annotations) into the repository. (See
+ <ulink url="http://jira.jboss.org/jira/browse/DNA-51">DNA-51</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">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. (See
+ <ulink url="http://jira.jboss.org/jira/browse/DNA-26">DNA-26</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>Federating content</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 move the information into a JCR repository? Most likely there are existing applications that rely upon
+ that information being where it is. If we were to move it, then all those applications would break. Or they'd have to be
+ changed to use JCR. If the information is being used, the most practical thing is to leave it where it is.</para>
+ <para>
+ Then why not just copy the information into a JCR repository? Actually, there are times when it's perfectly reasonable to
+ make a copy of the data. Perhaps the system managing the existing information cannot handle the additional load of more
+ clients. Or, perhaps the information doesn't change, or it does change and we want snapshots that don't change. But more
+ likely, the data
+ <emphasis>does</emphasis>
+ change. So if applications are to use the most current information and we make copies of the data, we have to keep the
+ copies synchronized with the master. That's generally a lot of work.
+ </para>
+ <para>The JBoss DNA federation engine lets us leave the information where it is, yet lets client applications use the JCR
+ API to access all the information without caring where the information really exists. If the underlying information
+ changes, client applications using JCR observation will be notified of the changes. If a JBoss DNA federated 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="federation_connectors">
+ <title>Connecting to information sources</title>
+ <para>
+ The JBoss DNA federation engine will use connectors to interact with different information sources to get at the content
+ in those systems. Some ideas for connectors include:
+ <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">File System Connector</emphasis>
+ - Expose the files and directories on a file system through JCR.
+ </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">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">UDDI Connector</emphasis>
+ - Interact with UDDI registries to integrate their content into 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>
+ <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">JDBC Storage Connector</emphasis>
+ - Store and access information in a relational database. Also useful for persisting information in the federated
+ repository not stored elsewhere.
+ </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>
+ <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="federation_graph">
+ <title>Building the unified graph</title>
+ <para> The federation engine 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 also 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>
+ <note>
+ <para> It is hoped that the MetaMatrix query engine can be used for this purpose after it is open-sourced. This engine
+ implements sophisticated query planning and optimization techniques for working efficiently with multiple sources.
+ </para>
+ </note>
+ <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/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 2008-09-04 17:44:52 UTC (rev 497)
@@ -0,0 +1,448 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ ~ JBoss, Home of Professional Open Source.
+ ~
+ ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as
+ ~ indicated by the @author tags or express copyright attribution
+ ~ statements applied by the authors. All third-party contributions are
+ ~ distributed under license by Red Hat Middleware LLC.
+ ~
+ ~ This copyrighted material is made available to anyone wishing to use, modify,
+ ~ copy, or redistribute it subject to the terms and conditions of the GNU
+ ~ Lesser General Public License, as published by the Free Software Foundation.
+ ~
+ ~ This program 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">
+ <title>Using JBoss DNA</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 sequencers 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. However, the next release will
+ provide a much easier mechanism for configuring not only the sequencer service but also the upcoming federation engine and
+ JCR implementation.</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 optional <emphasis>factory for class loaders</emphasis> used to load sequencers. If no factory is supplied,
+ the service uses the current thread's context class loader (or if that is null, the class loader that loaded the
+ sequencing service class).</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>ExecutionContext</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("Main Repository", this.repository);
+Credentials credentials = new SimpleCredentials("jsmith", "secret".toCharArray());
+sessionFactory.registerCredentials("Main Repository/Workspace1", credentials);
+ExecutionContext executionContext = new SimpleExecutionContext(sessionFactory);
+
+// Create the sequencing service, passing in the execution context ...
+SequencingService sequencingService = new SequencingService();
+sequencingService.setExecutionContext(executionContext);
+ ]]></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 an example:</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.images.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 of the audio file";
+classname = "org.jboss.dna.sequencer.mp3.Mp3MetadataSequencer";
+String[] mp3PathExpressions = {"//(*.mp3)[*]/jcr:content[@jcr:data] => /mp3s/$1"};
+SequencerConfig mp3SequencerConfig = new SequencerConfig(name, desc, classname,
+ classpath, mp3PathExpressions);
+sequencingService.addSequencer(mp3SequencerConfig);
+ ]]></programlisting>
+ <para>This is pretty self-explanatory, except for the <code>classpath</code> and <code>pathExpression</code> parameters.
+ The classpath parameter defines the classpath that is passed to the class loader factory mentioned above.
+ Our sequencer is on the classpath, so we can simply use <code>null</code> here.</para>
+ <para>The path expression is more complicated. Sequencer path expressions are used by the sequencing service to
+ determine whether a particular changed node should be sequenced. The expressions consist of two parts: a selection
+ criteria and an output expression:</para>
+ <programlisting><![CDATA[ inputPath => outputPath ]]></programlisting>
+ <para>The <emphasis>inputPath</emphasis> part defines an expression for the path that is to change and that should be sequenced.
+ Input paths must match node names (including same-name-sibling indexes), and can use wildcards in the names and/or indexes.
+ Wildcards include:
+ <itemizedlist>
+ <listitem>
+ <para>"<code>//</code>" mean any sequence of nodes, regardless of what their names are</para>
+ </listitem>
+ <listitem>
+ <para>"<code>*</code>" means a node with any name and any same-name-sibling index</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>The <emphasis>inputPath</emphasis> part defines an expression for the path that is to change and that should be sequenced.
+ Input paths must match node names (including same-name-sibling indexes), and can use wildcards in the names and/or indexes.
+ The characters "<code>//</code>" mean any sequence of nodes (regardless of what their names are), and "<code>*</code>"
+ means a node with any
+
+
+
+
+ while
+ the <emphasis>outputPath</emphasis> part defines the location where the content generated by the sequencer should be stored.</para>
+ <para>Here's a simple example:</para>
+ <programlisting><![CDATA[ /a/b/c at title => /d/e/f ]]></programlisting>
+ <para>Here, the <code>/a/b/c at title</code> is the selection criteria that applies when the <code>/a/b/c</code> node has a <code>title</code> property
+ that is added or changed. When the selection criteria matches a change event, the sequencer will be run
+ and any generated output will be inserted into the repository described by the output expression. In this example,
+ the generated output would be placed at the <code>/d/e/f</code> node.</para>
+ <note>
+ <para>Sequencer path expressions can be fairly complex and may use wildcards, specificy same-name sibling indexes,
+ provide optional and choice elements, and may capture parts of the selection criteria for use in the output expression.
+ The path expression used in the image sequencer configuration example above shows a more complex example:</para>
+ <programlisting><![CDATA[ //(*.(jpg|jpeg|gif|bmp|pcx|png))[*]/jcr:content[@jcr:data] => /images/$1 ]]></programlisting>
+ <para>This uses "//" to select any node at any level in the repository whose name ends with "." and one of the extensions (e.g., ".jpg", ".jpeg", etc.)
+ and that has a child node named "jcr:content" that has a "jcr:data" property. It also selects the file name
+ as the first capture group (the first set of parentheses) for use in the output expression.
+ In this example, any sequencer output is placed on a node with that same file name under the "/images" node.</para>
+ <para>Other things are possible, too. For example, the name of the repository/workspace (as used by the <code>SessionFactory</code>)
+ may be specified at the beginning of the select criteria and/or the output expression. This means it's possible to place
+ the sequencer output in a different repository than the node being sequenced.</para>
+ <para>For more detail about sequencer path expressions, see the <code>org.jboss.dna.repository.sequencer.SequencerPathExpression</code>
+ class and the corresponding <code>org.jboss.dna.repository.sequencer.SequencerPathExpressionTest</code> test case.</para>
+ </note>
+ <para>After the service is started, it is ready to start reacting to changes in the repository. But it first
+ must be wired to the repositories using a listener. This is accomplished using the <code>ObservationService</code>
+ described in the <link linkend="observation_service">next section</link>.</para>
+ </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 3 classes and 1 interface, located in the <code>src/main/java</code> directory:</para>
+ <programlisting><![CDATA[
+ org/jboss/example/dna/sequencers/ConsoleInput.java
+ /MediaInfo.java
+ /SequencingClient.java
+ /UserInterface.java
+ ]]></programlisting>
+ <para><code>SequencingClient</code> is the class that contains the main application. <code>MediaInfo</code> is a simple Java object
+ that encapsulates metadata about a media file (as generated by the sequencer), and used by the client to
+ pass information to the <code>UserInterface</code>, which 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>To keep the code shown in this book as readable as possible, some of the comments and error handling have been removed.</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 SimpleExecutionContext(sessionFactory);
+
+ // 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";
+ String[] mp3PathExpressions = {"//(*.mp3)[*]/jcr:content[@jcr:data] => /mp3s/$1"};
+ SequencerConfig mp3SequencerConfig = new SequencerConfig(name, desc, classname, classpath, mp3PathExpressions);
+ this.sequencingService.addSequencer(mp3SequencerConfig);
+
+ // 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 and how they 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>
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-architecture.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-architecture.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-logo.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/dna-logo.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-cli-client.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-cli-client.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search-with-mp3.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search-with-mp3.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search2.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-search2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics2.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-statistics2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload2.png
===================================================================
(Binary files differ)
Property changes on: trunk/docs/gettingstarted/src/main/docbook/en-US/images/example-sequencer-upload2.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the dna-commits
mailing list