[dna-commits] DNA SVN: r111 - in trunk/docs/getting_started/en: modules and 1 other directory.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Mon Apr 28 15:55:31 EDT 2008
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 at 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 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>
-&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/downloads/userGuide-examples-13112007.zip">download</ulink>
+ 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/</ulink>
+ </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"><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 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 <para></para> element in DocBook could be transformed into a <p></p> 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/">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 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</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 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/">docbook-support</ulink>
- </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'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 & 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
More information about the dna-commits
mailing list