[dna-commits] DNA SVN: r539 - trunk/docs/reference/src/main/docbook/en-US/content.
dna-commits at lists.jboss.org
dna-commits at lists.jboss.org
Mon Sep 22 18:58:15 EDT 2008
Author: rhauch
Date: 2008-09-22 18:58:15 -0400 (Mon, 22 Sep 2008)
New Revision: 539
Modified:
trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml
trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml
Log:
DNA-71 Document development tools and environment
https://jira.jboss.org/jira/browse/DNA-71
Refactored the introduction and added chapter on the development environment to the Reference Guide.
Modified: trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml 2008-09-19 20:26:37 UTC (rev 538)
+++ trunk/docs/reference/src/main/docbook/en-US/content/development_environment.xml 2008-09-22 22:58:15 UTC (rev 539)
@@ -26,6 +26,269 @@
<chapter id="development-environment">
<title>Developer environment and tooling</title>
<para>
- Discuss our use of Maven, Eclipse, coding styles/preferences, SVN, Hudson, etc.
+ The JBoss DNA project uses <link linkend="maven">Maven</link> as its primary build tool, <link linkend="svn">Subversion</link>
+ for its source code repository, <link linkend="jira">JIRA</link> for the issue management and bug tracking system,
+ and <link linkend="hudson">Hudson</link> for the continuous integration system. We do not stipulate a specific integrated
+ development environment (IDE), although most of us use <link linkend="eclipse">Eclipse</link> and rely upon the code formatting
+ and compile preferences to ensure no warnings or errors.
</para>
+ <para>
+ The rest of this chapter talks in more detail about these different tools and how to set them up.
+ </para>
+ <sect1 id="jdk">
+ <title>JDK</title>
+ <para>
+ Currently, JBoss DNA is developed and built using <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK 5</ulink>,
+ so if you're a contributor, you should have that installed and should use it before committing any changes. Note that you
+ should be able to use the <ulink url="http://java.sun.com/javase/downloads/index.jsp">latest JDK</ulink> (which is currently
+ JDK 6).
+ </para>
+ <para>
+ Why do we build using JDK 5 and not 6? The main reason is that if we were to use JDK 6, then JBoss DNA couldn't really be used in any
+ applications or projects that still used JDK 5. Plus, anybody using JDK 6 can still use JBoss DNA.
+ However, considering that the end-of-life for Java 5 is
+ <ulink url="http://java.sun.com/products/archive/eol.policy.html">October 2009</ulink>, we may be switching to
+ Java 6 in the coming months.
+ </para>
+ <para>
+ When installing, simply follow the procedure for your particular platform. On most platforms, this should set the
+ <code>JAVA_HOME</code> environment variable. But if you run into any problems, first check that this environment
+ variable was set to the correct location, and then check that you're running the version you expect by running
+ the following command:
+ </para>
+ <programlisting role="XML"><![CDATA[ java -version ]]></programlisting>
+ <para>
+ If you don't see the correct version, double-check your installation.
+ </para>
+ </sect1>
+ <sect1 id="svn">
+ <title>Subversion</title>
+ <para>JBoss DNA uses Subversion as its source code management system, and specifically the instance at
+ <ulink url="http://www.jboss.org">JBoss.org</ulink>. Although you can view the
+ <ulink url="http://anonsvn.jboss.org/repos/dna/trunk/">trunk</ulink> of the Subversion repository
+ (or using <ulink url="http://fisheye.jboss.org/browse/DNA/trunk">FishEye</ulink>) through your browser,
+ it order to get more than just a few files of the latest version of the source code, you probably want
+ to have an SVN client installed. Several IDE's have SVN support included (or available as plugins),
+ but having the command-line SVN client is recommended. See
+ <ulink url="http://subversion.tigris.org/">http://subversion.tigris.org/</ulink> for downloads and instructions for your
+ particular platform.
+ </para>
+ <para>
+ Here are some useful URLs for the JBoss DNA Subversion:
+ </para>
+ <table frame='all'>
+ <title>SVN URLs for JBoss DNA</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Repository</entry>
+ <entry>URL</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Anonymous Access URL</entry>
+ <entry><ulink url="http://anonsvn.jboss.org/repos/dna/trunk">http://anonsvn.jboss.org/repos/dna/trunk</ulink></entry>
+ </row>
+ <row>
+ <entry>Secure Developer Access URL</entry>
+ <entry><ulink url="https://svn.jboss.org/repos/dna/trunk/">https://svn.jboss.org/repos/dna/trunk/</ulink></entry>
+ </row>
+ <row>
+ <entry>FishEye Code Browser</entry>
+ <entry><ulink url="http://fisheye.jboss.org/browse/DNA/trunk">http://fisheye.jboss.org/browse/DNA/trunk</ulink></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+ <sect1 id="maven">
+ <title>Maven</title>
+ <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>
+ <para>
+ To use Maven with JBoss DNA, you'll need to have <link linkend="jdk">JDK 5 or 6</link> and Maven 2.0.9 (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 (<ulink url="http://repository.jboss.org/maven2">snapshots</ulink>
+ and <ulink url="http://snapshots.jboss.org/maven2">releases</ulink>) that contain all of the JARs for JBoss DNA and all dependent libraries.
+ </para>
+ <note>
+ <para>
+ It is a policy of the project that the <emphasis>source code and JARs</emphasis> for <emphasis>all</emphasis> dependencies
+ <emphasis>must</emphasis> be loaded into the JBoss repository. This is so that the project can always be built
+ and that all source code is always available.
+ </para>
+ <para>
+ For more information about the JBoss Maven repository, see the <ulink url="http://wiki.jboss.org/wiki/Maven">JBoss.org Wiki</ulink>.
+ </para>
+ </note>
+ <para>
+ There are just a few commands that are useful for building JBoss DNA (and it's <link linkend="modules">subprojects</link>).
+ Usually, these are issued while at the top level of the code (usually just below <code>trunk/</code>), although issuing
+ them inside a subproject just applies to that subproject.
+ </para>
+ <table frame='all'>
+ <title>Useful Maven commands</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>mvn clean</code></entry>
+ <entry>Clean up all built artifacts (e.g., the <code>target/</code> directory in each project)</entry>
+ </row>
+ <row>
+ <entry><code>mvn clean install</code></entry>
+ <entry>Clean up all built artifacts, then compile, run the unit tests, and install the resulting JAR artifact(s)
+ into your local Maven repository (e.g, usually <code>~/.m2/repository</code>).
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+ <sect1 id="hudson">
+ <title>Continuous integration with Hudson</title>
+ <para>JBoss DNA's continuous integration is done with several Hudson jobs on <ulink url="http://www.jboss.org">JBoss.org</ulink>.
+ These jobs run periodically and basically run the Maven build process. Any build failures or test failures are reported,
+ as are basic statistics and history for each job.
+ </para>
+ <table frame='all'>
+ <title>Continuous integration jobs</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Job</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20continuous%20on%20JDK1.5/">Continuous on JDK 5</ulink></entry>
+ <entry>Continuous build that runs after changes are committed to SVN. SVN is polled every 15 minutes.</entry>
+ </row>
+ <row>
+ <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20nightly%20integration%20on%20JDK1.5/">Nightly on JDK 5</ulink></entry>
+ <entry>Build that runs every night (about 2 a.m. EDT), regardless of whether changes have been committed to SVN
+ since the previous night.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect1>
+ <sect1 id="eclipse">
+ <title>Eclipse IDE</title>
+ <para>Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making
+ it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects.
+ Many of the JBoss DNA committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making
+ it pretty easy to get an Eclipse workspace running with all of the JBoss DNA projects.
+ </para>
+ <para>We're using the latest released version of Eclipse (3.4, called "Ganymede"),
+ available from <ulink url="http://www.eclipse.org/">Eclipse.org</ulink>. Simply follow the instructions for your platform.
+ </para>
+ <para>
+ After Eclipse is installed, create a new workspace. Before importing the JBoss DNA projects, import (via "File->Import->Preferences")
+ the subset of the Eclipse preferences by importing the <code>eclipse-preferences.epf</code> file (located under <code>trunk</code>).
+ Then, open the Eclipse preferences and open the "Java->Code Style-> Formatter" preference page, and press the "Import" button and
+ choose the <code>eclipse-code-formatter-profile.xml</code> file (located under <code>trunk</code>). This will load the code
+ formatting preferences for the JBoss DNA project.
+ </para>
+ <para>
+ Then install Eclipse plugins for SVN and Maven. (Remember, you will have to restart Eclipse after installing them.)
+ We use the following plugins:
+ </para>
+ <table frame='all'>
+ <title>Continuous integration jobs</title>
+ <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ <colspec colname='c1' colwidth="1*"/>
+ <colspec colname='c2' colwidth="1*"/>
+ <thead>
+ <row>
+ <entry>Eclipse Plugin Site</entry>
+ <entry>Update Site URL</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Subversive SVN Client</entry>
+ <entry>
+ <ulink url="http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/">http://www.polarion.org/projects/subversive/download/eclipse/2.0/update-site/</ulink>
+ <ulink url="http://www.polarion.org/projects/subversive/download/integrations/update-site/">http://www.polarion.org/projects/subversive/download/integrations/update-site/</ulink>
+ </entry>
+ </row>
+ <row>
+ <entry>Maven Integration for Eclipse</entry>
+ <entry><ulink url="http://m2eclipse.sonatype.org/update/">http://m2eclipse.sonatype.org/update/</ulink></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ After you check out the JBoss DNA codebase, you can import the JBoss DNA Maven projects into Eclipse as Eclipse projects.
+ To do this, go to "File->Import->Existing Projects", navigate to the <code>trunk/</code> folder in the import wizard,
+ and then check each of the <link linkend="modules">subprojects</link> that you want to have in your workspace.
+ </para>
+ </sect1>
</chapter>
Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml
===================================================================
--- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-19 20:26:37 UTC (rev 538)
+++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-22 22:58:15 UTC (rev 539)
@@ -25,83 +25,156 @@
<!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 to JBoss DNA</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 JBoss DNA project is building a unified metadata repository system that is <link linkend="jcr_intro">JCR-compliant</link>
+ and capable of federating information from a variety of back-end systems. To client applications, JBoss DNA looks and behaves like a
+ regular JCR repository that they search, navigate, version, and listen for changes. But under the covers, JBoss DNA
+ gets its content by federating multiple back-end systems (like databases, services, other repositories, etc.),
+ allowing those systems to continue "owning" the information but ensuring the unified repository stays up-to-date
+ and in sync.
+ </para>
+ <para>
+ This document goes into detail about JBoss DNA and its capabilities, features, architecture, components, extension points,
+ security, configuration, and testing. So whether your a developer on the project or trying to learn the intricate details of
+ how JBoss DNA works, this document hopefully serves a good reference for developers on the project.
+ </para>
+ <sect1 id="use_cases">
+ <title>Use cases for JBoss DNA</title>
+ <para>
+ JBoss DNA repositories can be used in a variety of applications. One of the most obvious ones
+ is in provisioning and management, where it's critical to understand and keep track of the metadata for models, database, services,
+ components, applications, clusters, machines, and other systems used in an enterprise. Governance takes that a step
+ farther, by tracking with those entities the policies dictating expectations and against which performance can be verified.
+ But, a JBoss DNA repository doesn't have to be large and complex - it could just manage configuration information
+ for an application. Or, provide a JCR interface on top of a couple of non-JCR systems. In truth, there
+ are a lot of ways that you could use JBoss DNA.
+ </para>
+ </sect1>
+ <sect1 id="what_is_metadata">
+ <title>What is metadata?</title>
+ <para>
+ Before we dive into more detail about JBoss DNA and metadata repositories, it's probably useful to explain what we
+ mean by the term "metadata." Simply put, <emphasis>metadata</emphasis> is the information you need to manage something.
+ It's the information needed to configure an operating system, or the description of the information in an LDAP tree,
+ or the topology of your network. It's the configuration of an application server or enterprise service bus.
+ It's the steps involved in validating an application before it can go into production. It's the description of your
+ database schemas, or of your services, or of the messages going in and coming out of a service. JBoss DNA is
+ designed to be a repository for all this (and more).
+ </para>
+ <para>
+ There are a couple of important things to understand about this metadata. First, the majority of this metadata is
+ managed by other systems: databases, applications, file systems, source code management systems, services, and
+ content management systems, and even other repositories. We can't pull the information out and duplicate it, because
+ we then risk having multiple copies that are out-of-sync. But we do want to access it through a homogenous API,
+ since that will make our lives significantly easier. The answer to this apparent dichotomy is
+ <emphasis><link linkend="dna-connector-federation">federation</link></emphasis>.
+ We can connect to these back-end systems to dynamically access the content and project it into a single, unified
+ repository. We can also cache it for faster access, as long as the cache can be invalidated based upon time or event.
+ But we also need to maintain a clear picture of where all the bits come from, so users can be sure they're looking
+ at the right information. And we need to make it as easy as possible to write new connectors, since there are
+ a lot of systems out there that have information we want to federate.
+ </para>
+ <para>
+ The second important characteristic of the metadata is that a lot of it is represented as files, and there are
+ a lot of different file formats. These include source code, configuration files, web pages, database schemas,
+ XML schemas, service definitions, policies, documents, spreadsheets, presentations, images, audio files, workflow
+ definitions, business rules, and on and on. And so even though information is added to the repository through files
+ like these, the repository should be able to automatically extract the most useful content from these files.
+ This process of extracting content and storing it in the repository is what JBoss DNA calls
+ <emphasis><link linkend="sequencing">sequencing</link></emphasis>,
+ and it's an important part of a metadata repository since more information is now available for searching,
+ navigating, relating, and analyzing.
+ </para>
+ <para>
+ The third important characteristic of metadata is that it rarely stays the same. Different consumers of the
+ information need to see different views of it. Metadata about two similar systems is not always the same.
+ The metadata often needs to be tagged or annotated with additional information. And the things being
+ described often change over time, meaning the metadata has to change, too. As a result, the way in which
+ we store and manage the metadata has to be flexible and able to adapt, and the object model
+ we use to interact with the repository must accommodate these needs. The graph-based nature of the JCR API provides this
+ flexibility while also giving us the ability to constrain information when it needs to be constrained.
+ </para>
+ </sect1>
+ <sect1 id="jcr_intro">
+ <title>What is JCR?</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 unified metadata repository system that is compliant with JCR. Nearly all of these capabilities are to be hidden
+ below the JCR API and involve automated processing of the information in the repository. Thus, JBoss DNA can add value to
+ existing repository implementations. For example, JCR repositories offer the ability to upload files into the repository and
+ have the file content indexed for search purposes. JBoss DNA also defines a library for "sequencing" content - to extract
+ meaningful information from that content and store it in the repository, where it can then be searched, accessed, and
+ analyzed using the JCR API.
+ </para>
+ <para> JBoss DNA has other features as well. You can create federated repositories that dynamically merge the information
+ from multiple databases, services, applications, and other JCR repositories. JBoss DNA also will allow you to
+ create customized views based upon the type of data and the role of the user that is accessing the data. And yet another is
+ to create a REST-ful API to allow the JCR content to be accessed easily by other applications written in other languages.
+ </para>
+ </sect1>
<sect1 id="roadmap">
<title>Project roadmap</title>
<para>
@@ -117,10 +190,69 @@
appropriate release where they can be targeted. Any issue that is reviewed and that does not fit in a known release will
be targeted to the
<ulink url="https://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira.plugin.system.project:roadmap-panel">Future Releases</ulink>
- bucket. This should be reviewed periodically and at least at the beginning of each release cycle, with the goal of
- targeting most of the issues to specific releases.
+ bucket.
+ </para>
+ <para>
+ At the start of a release, the project team reviews the roadmap, identifies the goals for the release, and targets (or retargets)
+ the issues appropriately.
</para>
</sect1>
+ <sect1 id="methodology">
+ <title>Development methodology</title>
+ <para>
+ The JBoss DNA project doesn't use a formal methodology, but instead incorporates techniques, activities, and processes from
+ several methodologies. In fact, the committers are given a lot of freedom for how they develop the components and features
+ they work on.
+ </para>
+ <para>
+ Nevertheless, we encourage familiarity with several major techniques, including:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Agile_software_development">Agile software development</ulink></emphasis>
+ includes those software methodologies (e.g., Scrum) that promote development iterations and open collaboration. While the
+ JBoss DNA project doesn't follow these closely, we do emphasize the importance of always having running software
+ and using running software as a measure of progress. The JBoss DNA project also wants to move to more frequent
+ releases (on the order of 4-6 weeks)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Test-driven_development">Test-driven development (TDD)</ulink></emphasis>
+ techniques encourage first writing test cases for new features and functionality, then changing the code to add the
+ new features and functionality, and finally the code is refactored to clean-up and address any duplication or inconsistencies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong"><ulink url="http://behaviour-driven.org/">Behavior-driven development (BDD)</ulink></emphasis>
+ is an evolution of TDD, where developers specify the desired behaviors first (rather than writing "tests").
+ In reality, this BDD adopts the language of the user so that tests are written using words that are meaningful
+ to users. With recent test frameworks (like JUnit 4.4), we're able to write our unit tests to express
+ the desired behavior. For example, a test class for sequencer implementation might have a test method
+ <code>shouldNotThrowAnErrorWhenStreamIsNull()</code>, which is very easy to understand the intent.
+ The result appears to be a larger number of finer-grained test methods, but which are more easily understood
+ and easier to write. In fact, many advocates of BDD argue that one of the biggest challenges of TDD is knowing what
+ tests to write in the beginning, whereas with BDD the shift in focus and terminology make it easier for more
+ developers to enumerate the tests they need.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong"><ulink url="http://en.wikipedia.org/wiki/Lean_software_development">Lean software development</ulink></emphasis>
+ is an adaptation of <ulink url="http://en.wikipedia.org/wiki/Lean_manufacturing">lean manufacturing techniques</ulink>,
+ where emphasis is placed on eliminating waste (e.g., defects, unnecessary complexity, unnecessary code/functionality/features),
+ delivering as fast as passible, deferring irrevocable decisions as much as possible,
+ continuous learning (continuously adapting and improving the process), empowering the team (or community, in our case),
+ and several other guidelines. Lean software development can be thought of as an evolution of agile techniques
+ in the same way that behavior-driven development is an evolution of test-driven development. Lean techniques
+ help the developer to recognize and understand how and why features, bugs, and even their processes impact the development
+ of software - and JBoss DNA.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
<sect1 id="modules">
<title>JBoss DNA modules</title>
<para>
@@ -168,7 +300,7 @@
</itemizedlist>
The following modules are optional extensions that may be used selectively and as needed (and are located in the source
under the
- <code>extensions</code>
+ <code>extensions/</code>
directory):
<itemizedlist>
<listitem>
@@ -256,7 +388,7 @@
</listitem>
</itemizedlist>
There are also documentation modules (located in the source under the
- <code>docs</code>
+ <code>docs/</code>
directory):
<itemizedlist>
<listitem>
More information about the dna-commits
mailing list