Author: rhauch Date: 2008-04-28 15:55:31 -0400 (Mon, 28 Apr 2008) New Revision: 111 Added: trunk/docs/getting_started/en/modules/custom_sequencers.xml trunk/docs/getting_started/en/modules/downloading.xml trunk/docs/getting_started/en/modules/future_directions.xml trunk/docs/getting_started/en/modules/jboss_dna.xml trunk/docs/getting_started/en/modules/using_dna.xml Removed: trunk/docs/getting_started/en/modules/styles.xml Modified: trunk/docs/getting_started/en/master.xml trunk/docs/getting_started/en/modules/introduction.xml Log: Committing interim state of the document, which is still very rough. Modified: trunk/docs/getting_started/en/master.xml =================================================================== --- trunk/docs/getting_started/en/master.xml 2008-04-25 04:02:32 UTC (rev 110) +++ trunk/docs/getting_started/en/master.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -1,30 +1,60 @@ <?xml version='1.0' encoding='ISO-8859-1'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN" "../../../../docbook-support/support/docbook-dtd/docbookx.dtd" [ -<!ENTITY introduction SYSTEM "modules/introduction.xml"> -<!ENTITY styles SYSTEM "modules/styles.xml"> -]> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <book lang="en"> <bookinfo> <title>JBoss DNA</title> <subtitle>Getting Started Guide</subtitle> <releaseinfo>0.1</releaseinfo> </bookinfo> - <toc/> - <preface id="target" revision="1"> - <title>Target Audience</title> - <para>This guide is for anybody who is new to JBoss DNA, and will help you learn the ins and outs of - configuring and using JBoss DNA. </para> - </preface> + <toc> + <title>Table of Contents</title> + </toc> <preface id="preface" revision="1"> - <title>Preface</title> + <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 provides some background on content repositories and the Java Content Repository (JCR) API. + Content repositories are an important aspect of JBoss DNA, so it's probably worth reading even if you're already familiar + with these technologies. Besides, it's really not that long.</para> + <para> The If you're already familiar with these technologies, you can probably skip this section. However, most readers will + probably want to</para> + <para> and then introduces JBoss DNA project and its relationship to JCR. The second part</para> + <para> + <link linkend="part1">Part I intr oduces JBoss DNAFeature Analysis and Design</link> + Part 1 + </para> <para>This document introduces the JBoss DNA project.</para> <itemizedlist> <listitem> - <para>The build process is simplified and standardized. Just - follow the instructions in this guide to setup your <literal>docs</literal> - directory and copy a very simple <literal>pom.xml</literal> file. </para> + <para> + The build process is simplified and standardized. Just follow the instructions in this guide to setup your + <literal>docs</literal> + directory and copy a very simple + <literal>pom.xml</literal> + file. + </para> </listitem> </itemizedlist> - <para> If you have any questions, please feel free to contact <ulink url="mailto:rhauch@jboss.org">Randall Hauch</ulink> (Project Lead) for more information. </para> + <para> + If you have any questions or comments, please feel free to contact JBoss DNA's + <ulink url="mailto:dna-users@jboss.org">user mailing list</ulink> + or use the + <ulink url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... 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> -&introduction;&howto;&styles;</book> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/introduction.xml" xml:base="./" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/jboss_dna.xml" xml:base="./" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/downloading.xml" xml:base="./" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/using_dna.xml" xml:base="./" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/custom_sequencers.xml" xml:base="./" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/future_directions.xml" xml:base="./" /> +</book> \ No newline at end of file Added: trunk/docs/getting_started/en/modules/custom_sequencers.xml =================================================================== --- trunk/docs/getting_started/en/modules/custom_sequencers.xml (rev 0) +++ trunk/docs/getting_started/en/modules/custom_sequencers.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="custom_sequencers"> + <title>Custom sequencers</title> + <para></para> +</chapter> \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/custom_sequencers.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Copied: trunk/docs/getting_started/en/modules/downloading.xml (from rev 106, trunk/docs/getting_started/en/modules/styles.xml) =================================================================== --- trunk/docs/getting_started/en/modules/downloading.xml (rev 0) +++ trunk/docs/getting_started/en/modules/downloading.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="downloading"> + <title>Downloading the examples</title> + <para>JBoss DNA is built using Maven 2, so it's much easier to following along with the examples in this document + if you install and configure Maven. Once this is done, you can very easily build the examples or even create a maven project that + depends on the JBoss DNA JARs. Maven will automatically download the right versions of the JARs, including those other libraries + on which JBoss DNA depends. Maven also makes it very easy to create an assembly of your final application + so that you can package into a distributable form.</para> + <para> + The examples created for this User Guide use Maven2 to achieve exactly this so it is highly recommended that you + <ulink url="http://labs.jboss.com/file-access/default/members/jbossmc/downl... + these first and take a look at how they work. + </para> + <note> + <para> + To build and run the examples you first need to install and configure Maven 2.0.7 available from + <ulink url="http://maven.apache.org/">http://maven.apache.org/</... + </para> + <para>Installation is performed by downloading and unzipping the maven-2.0.7-bin.zip file to a convenient location + on your local disk. Configuration consists of adding $MAVEN_HOME/bin to your path and adding the following profile to your + ~/.m2/settings.xml file:</para> + <programlisting role="XML">&lt;settings&gt; + &lt;profiles&gt; + &lt;profile&gt; + &lt;id&gt;jboss.repository&lt;/id&gt; + &lt;activation&gt; + &lt;property&gt; + &lt;name&gt;!jboss.repository.off&lt;/name&gt; + &lt;/property&gt; + &lt;/activation&gt; + &lt;repositories&gt; + &lt;repository&gt; + &lt;id&gt;snapshots.jboss.org&lt;/id&gt; + &lt;url&gt;http://snapshots.jboss.org/maven2&lt;/url&gt; + &lt;snapshots&gt; + &lt;enabled&gt;true&lt;/enabled&gt; + &lt;/snapshots&gt; + &lt;/repository&gt; + &lt;repository&gt; + &lt;id&gt;repository.jboss.org&lt;/id&gt; + &lt;url&gt;http://repository.jboss.org/maven2&lt;/url&gt; + &lt;snapshots&gt; + &lt;enabled&gt;false&lt;/enabled&gt; + &lt;/snapshots&gt; + &lt;/repository&gt; + &lt;/repositories&gt; + &lt;pluginRepositories&gt; + &lt;pluginRepository&gt; + &lt;id&gt;repository.jboss.org&lt;/id&gt; + &lt;url&gt;http://repository.jboss.org/maven2&lt;/url&gt; + &lt;snapshots&gt; + &lt;enabled&gt;false&lt;/enabled&gt; + &lt;/snapshots&gt; + &lt;/pluginRepository&gt; + &lt;pluginRepository&gt; + &lt;id&gt;snapshots.jboss.org&lt;/id&gt; + &lt;url&gt;http://snapshots.jboss.org/maven2&lt;/url&gt; + &lt;snapshots&gt; + &lt;enabled&gt;true&lt;/enabled&gt; + &lt;/snapshots&gt; + &lt;/pluginRepository&gt; + &lt;/pluginRepositories&gt; + &lt;/profile&gt; + &lt;/profiles&gt; +&lt;/settings&gt;</programlisting> + <para>This profile informs maven of the two JBoss repositories (snapshots and releases) that are needed to download the JBoss Microcontainer and dependant JARs.</para> + </note> + <para>Once you have configured Maven and downloaded the examples then you can go to one of the following subdirectories in the <code>examples/User_Guide</code> directory and enter <code>mvn install</code> to perform a build:</para> + <itemizedlist> + <listitem> + <para>gettingStarted - projects for creating and using a service together with AOP</para> + </listitem> + <listitem> + <para>pojoDevelopment - examples of creating and configuring POJOs using XML and annotations</para> + </listitem> + <listitem> + <para>aopDevelopment - examples of using AOP to add behaviour to POJOs</para> + </listitem> + <listitem> + <para>extending - examples of how we created various extensions to the microcontainer by creating new dependencies</para> + </listitem> + </itemizedlist> + <para>Instructions on how to run the individual examples can be found in the corresponding parts of this guide.</para> +</chapter> \ No newline at end of file Added: trunk/docs/getting_started/en/modules/future_directions.xml =================================================================== --- trunk/docs/getting_started/en/modules/future_directions.xml (rev 0) +++ trunk/docs/getting_started/en/modules/future_directions.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="future_directions"> + <title>Future directions</title> + <para>What's next for JBoss DNA? Well, sequencers are just the beginning. + Remember our <link linkend="jboss_dna">architecture</link>? + There are a lot of components on our roadmap, including federating + + </para> +</chapter> \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/future_directions.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: trunk/docs/getting_started/en/modules/introduction.xml =================================================================== --- trunk/docs/getting_started/en/modules/introduction.xml 2008-04-25 04:02:32 UTC (rev 110) +++ trunk/docs/getting_started/en/modules/introduction.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -1,25 +1,94 @@ -<?xml version='1.0' encoding='UTF-8'?><chapter id="introduction"> - <title>Introduction to DocBook processing</title> - <para>DocBook is an XML format for writing documents. It allows the author to - focus on the content itself during the writing process instead of - worrying about the presentation. </para> - <para>Using standard DocBook tags, we can tag the content according to - its syntatic structure. The DocBook document is then processed using - XSL stylesheets so that each tagged DocBook element is transformed to a - corresponding element in the target output format. For example each &lt;para&gt;&lt;/para&gt; element in DocBook could be transformed into a &lt;p&gt;&lt;/p&gt; element in XHTML. </para> - <para>Using different XSL stylesheets, we can generate different - output formats. For example, we can generate both XHTML and PDF outputs from - a single DocBook source. We can also generate multiple versions of XHTML - (or PDF) files each with a different style if necessary.</para> - <para>In the JBoss DocBook system, we provide XSL stylesheets to build XHTML, PDF and Eclipse Help output formats from the DocBook source. The build process is - illustrated in <xref linkend="build.fig"/>. </para> - <figure id="build.fig"> - <title>The DocBook build process </title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/build.png"/> - </imageobject> - </mediaobject> - </figure> - <para>XHTML is used instead of HTML as it ensures that the content is completely separated from its style using Cascading Style Sheets (CSS) and image files.</para> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/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 to use an approach that most closes matches the needs of + their application. This choice is more important as developers choose to focus their efforts on the 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 are often a better choice. + </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 its 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 often as + good (if not better) performance than handwritten JDBC code. The new + <ulink url="http://java.sun.com/developer/technicalArticles/J2EE/jpa/"... 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 a priori, 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 capabilies 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</ul... + and is being revised under + <ulink url="http://www.jcp.org/en/jsr/detail?id=283">JSR-283</ul... + . + </para> + <para> + The + <emphasis>JBoss DNA project</emphasis> + is building the tooles 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 index for search purposes. JBoss DNA defines a library for also sequencing that content to extract + meaningful information 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="jboss_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">Chapter 3</link> + then provides instructions for downloading and compiling the sequencer examples for the current release. + <link linkend="using_dna">Chapter 4</link> + walks through these examples, while + <link linkend="custom_sequencers.xml">Chapter 5</link> + goes over how to create custom sequencers. Finally, + <link linkend="future_directions">Chapter 6</link> + wraps things up. + </para> </chapter> \ No newline at end of file Added: trunk/docs/getting_started/en/modules/jboss_dna.xml =================================================================== --- trunk/docs/getting_started/en/modules/jboss_dna.xml (rev 0) +++ trunk/docs/getting_started/en/modules/jboss_dna.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="jboss_dna"> + <title>JBoss DNA</title> + <para>What's next for JBoss DNA? Well, sequencers are just the beginning. + Remember our <link linkend="introduction">architecture</link>? + There are a lot of components on our roadmap, including federating + + </para> +</chapter> \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/jboss_dna.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Deleted: trunk/docs/getting_started/en/modules/styles.xml =================================================================== --- trunk/docs/getting_started/en/modules/styles.xml 2008-04-25 04:02:32 UTC (rev 110) +++ trunk/docs/getting_started/en/modules/styles.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -1,35 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?><chapter id="styles"> - <title>Maintaining the JBoss DocBook system</title> - <para>The structure of the <literal> - <ulink url="http://anonsvn.jboss.org/repos/jbossas/trunk/docbook-support/&q... - </literal> project is - illustrated in <xref linkend="docbook.fig"/>. The contents are as follows:</para> - <figure id="docbook.fig"> - <title>The docbook-support project </title> - <mediaobject> - <imageobject> - <imagedata align="center" fileref="images/docbook-dir.png"/> - </imageobject> - </mediaobject> - </figure> - <itemizedlist> - <listitem> - <para>The <literal>docs</literal> directory contains the DocBook source for this guide to - serve as a template for other projects. </para> - </listitem> - <listitem> - <para>The <literal>jbossorg-documentation</literal> directory contains the maven plugin source for the parent POM that is referenced by each project&apos;s <literal>pom.xml</literal> file. The parent POM contains common configuration information so that it does not have to be duplicated across multiple JBoss.org projects.</para> - </listitem> - <listitem> - <para>The <literal>jbossorg-docbook-xslt</literal> directory contains the maven plugin source for the default JBoss.org XSL stylesheets. These stylesheets produce XHTML, PDF and Eclipse Help output.</para> - </listitem> - <listitem> - <para>The <literal>jbossorg-jdocbook-style</literal> directory contains the maven plugin source for the default JBoss.org CSS and image files. These provide the JBoss.org community-driven look &amp; feel.</para> - </listitem> - <listitem> - <para>The <literal>styles</literal> and <literal>support</literal> directories together with the <literal>support.xml</literal> file are provided for backwards compatibility with projects that wish to continue using Ant instead of Maven. The <literal>styles</literal> directory contains XSL stylesheets together with CSS files to produce HTML and PDF outputs. The <literal>support</literal> directory contains the DocBook - libraries and DTDs along with - the standard XSL stylesheets. The <literal>support.xml</literal> file contains common Ant tasks to perform the build.</para> - </listitem> - </itemizedlist> -</chapter> \ No newline at end of file Added: trunk/docs/getting_started/en/modules/using_dna.xml =================================================================== --- trunk/docs/getting_started/en/modules/using_dna.xml (rev 0) +++ trunk/docs/getting_started/en/modules/using_dna.xml 2008-04-28 19:55:31 UTC (rev 111) @@ -0,0 +1,7 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> +<chapter id="using_dna"> + <title>Using JBoss DNA</title> + <para></para> +</chapter> \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/using_dna.xml ___________________________________________________________________ Name: svn:mime-type + text/plain