Author: rhauch Date: 2008-09-26 16:50:59 -0400 (Fri, 26 Sep 2008) New Revision: 553 Modified: 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/understanding_dna.xml trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml trunk/docs/reference/src/main/docbook/en-US/content/future.xml trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml Log: DNA-214 Update documentation to describe the repository, federation, JCR and other 0.2 features https://jira.jboss.org/jira/browse/DNA-214 Finished reviewing and editing the Getting Started and Reference Guide documents. Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/downloading_and_running.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -37,10 +37,10 @@ <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> + and Maven 2.0.9 (or higher).</para> <para> Maven can be downloaded from <ulink url="http://maven.apache.org/">http://maven.apache.org/</...;, 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> + <code>maven-2.0.9-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> @@ -93,7 +93,7 @@ </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/... + <para>The next step is to <ulink url="http://www.jboss.org/file-access/default/members/dna/downloads/... 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[ @@ -113,17 +113,27 @@ /test/java /resources ]]></programlisting> - <para>There are essentially three Maven projects: a <code>sequencers</code> project, a <code>repository</code> project, + <para> + There are essentially three Maven projects: a <code>sequencers</code> project, a <code>repository</code> project, and a parent project. All of the source for the sequencing example is located in the <code>sequencers</code> subdirectory, - while all of the source for the federation example is located in the <code>repository</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>. + while all of the source for the repository example is located in the <code>repository</code> subdirectory. + </para> + <para> + 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: + </para> + <programlisting>$ mvn install</programlisting> + <para> 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> + code (and unit tests) and running the unit tests. The build is successful if you see the following: + </para> <programlisting><![CDATA[ $ mvn install ... Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/future.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -27,12 +27,15 @@ <title>Looking to the future</title> <para>What's next for JBoss DNA? Well, the sequencing system is just the beginning. With this release, the sequencing system is stable enough so that more <link linkend="sequencers">sequencers</link> can be developed and used within your own applications. + We've also established the foundation for JBoss DNA repositories, including a number of <link linkend="repository-connectors">connectors</link>. + We'll continue to expand our library of sequencers and connectors, as well as expand our support of JCR. + Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific + views of information in the repository. These components are farther out on our roadmap, and at this time have not been + targeted to a particular release. + </para> + <para> If you're interested in getting involved with the JBoss DNA project, consider picking up one of the sequencers on our <ulink url="http://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira...;. Or, check out <ulink url="http://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tru... 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>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> Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/introduction.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -25,7 +25,7 @@ <!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 + <para>There are a lot of ways for applications to 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> @@ -36,7 +36,7 @@ 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. + or if it needs to be accessed by multiple processes. For these situations, other techniques often have more benefits. </para> <para> Another technique built into the Java language is @@ -44,12 +44,11 @@ , 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. + process to another. Using serialization for longer-term storage of information is more risky. </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 + One of the more popular and widely-used 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 @@ -63,57 +62,47 @@ <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. + 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. Plus, Hibernate is open-source (with support + offered by <ulink url="http://www.jboss.com">JBoss</ulink>). </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, + While relational databases and JPA are solutions that work well for many applications, they are more limited in cases when the + information structure is highly flexible, the structure is not known <emphasis>a priori</emphasis>, or that structure 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 with the storage capabilities of + relational databases and the flexibility offered by other systems, such as using files. Content repositories also + 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</ul... - and is being revised under - <ulink url="http://www.jcp.org/en/jsr/detail?id=283">JSR-283</ul... - . + 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 tools and services that surround content repositories. Nearly all of these capabilities are to be hidden + 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 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 + <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> <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. + The <link linkend="understanding_dna">next chapter</link> in this book goes into more detail about JBoss DNA and its architecture, + the different components, what's available now, and what's coming in future releases. + <link linkend="downloading_and_running">Chapter 3</link> then provides instructions for downloading and running the sequencer + examples for the current release. <link linkend="using_dna">Chapter 4</link> walks through how to use JBoss DNA sequencers + in your applications, while <link linkend="custom_sequencers">Chapter 5</link> shows how to use JBoss DNA repositories. + <link linkend="custom_sequencers">Chapter 6</link> goes over how to create custom sequencers, and finally, + <link linkend="future">Chapter 7</link> wraps things up with a discussion about the future of JBoss DNA. </para> </chapter> Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/legal_notice.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -37,7 +37,7 @@ </address> </para> <para> - Copyright <trademark class="copyright"/> 2007 by Red Hat, Inc. This copyrighted material is made available to + Copyright <trademark class="copyright"/> 2008 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. Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/understanding_dna.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -129,9 +129,16 @@ </listitem> <listitem> <para> + <emphasis role="strong">DNA Repositories</emphasis> + is an implementation of the JCR API that builds the content within the repository by accessing and integrating + information from one or more sources. + </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 + is a special repository connector that accesses information from multiple sources and makes it accessible + as if it were a single repository. DNA Federation allows the integration of external systems, like other JCR repositories, databases, applications, and services. </para> </listitem> @@ -327,7 +334,7 @@ </para> </sect1> <sect1 id="federation"> - <title>Federating content</title> + <title>JCR and federated repositories</title> <para>There is a lot of information stored in many of different places: databases, repositories, SCM systems, registries, file systems, services, etc. The purpose of the federation engine is to allow applications to use the JCR API to access that information as if it were all stored in a single JCR repository, but to really leave the information where @@ -343,7 +350,7 @@ even get the benefit of using JCR observation to be notified of the changes. And if a JBoss DNA repository is configured to allow updates, client applications can change the information in the repository and JBoss DNA will propagate those changes down to the original source.</para> - <sect2 id="federation_connectors"> + <sect2 id="repository-connectors"> <title>Connecting to information sources</title> <para> JBoss DNA uses connectors to interact with different information sources to get at the content Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/content/using_dna_repositories.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -25,13 +25,13 @@ <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <chapter id="using_dna_repositories"> <title>Using JBoss DNA Repositories</title> - <para>As we've mentioned before, one of the capabilities of JBoss DNA is to provide access through + <para>One of the capabilities of JBoss DNA is to provide access through <ulink url="http://www.jcp.org/en/jsr/detail?id=170">JCR</ulink> to different kinds of repositories and storage systems. - Your applications work with the JCR API, but through JBoss DNA are able to accesses the content from where the information + Your applications work with the JCR API, but through JBoss DNA you're able to accesses the content from where the information exists - not just a single purpose-built repository. This is fundamentally what makes JBoss DNA different.</para> - <para>How does JBoss DNA do this? At the heart of JBoss DNA and it's JCR implementation is a simple graph-based connector - system. Essentially, the JBoss DNA JCR implementation makes use of a single repository source, from which all the - content is accessed. + <para>How does JBoss DNA do this? At the heart of JBoss DNA and it's JCR implementation is a simple connector + system that is designed around creating and accessing graphs. The JBoss DNA JCR implementation actually just sits on + top of a single repository source, which it uses to access of the repositories content. <figure id="dnajcr-and-connector"> <title>JBoss DNA's JCR implementation delegates to a repository source</title> <graphic align="center" scale="100" fileref="dnajcr-and-connector.png"/> @@ -53,10 +53,11 @@ <para>You might be thinking that these connectors are interesting, but what do they really provide? Is it really useful to use JCR to access a relational database rather than JDBC? Or, why access the files on a file system when there are already mechanisms to do that?</para> - <para>While putting JCR on top of a single system (like a JDBC database) probably isn't that interesting, what - <emphasis>is</emphasis> interesting is accessing the information in multiple systems <emphasis>as if all that information were - in a single JCR repository</emphasis>. That's what the federated repository source is all about.</para> - <para>Think of it this way: use JCR to get to the schemas of multiple relational databases <emphasis>and</emphasis> the schemas + <para>Maybe putting JCR on top of a single system (like a JDBC database) isn't that interesting. What + <emphasis>is</emphasis> interesting, though, is accessing the information in multiple systems <emphasis>as if all that information were + in a single JCR repository</emphasis>. That's what the federated repository source is all about. The JBoss DNA connector + system just makes it possible to interact with all these systems in the same way.</para> + <para>Think of it this way: with JBoss DNA, you can use JCR to get to the schemas of multiple relational databases <emphasis>and</emphasis> the schemas defined by DDL files in your SVN repository <emphasis>and</emphasis> the schemas defined by logical models stored on your file system. </para> </note> @@ -68,11 +69,12 @@ "configuration repository") and automatically sets up the repositories given the <code>RepositorySource</code> instances found in the configuration repository.</para> <note> - <para>Configuring JBoss DNA services is a bit more manual than is ideal. As you'll see, JBoss DNA uses dependency + <para>Configuring JBoss DNA services is more manual and complex than we want. As you'll see, JBoss DNA uses dependency injection to allow a great deal of flexibility in how it can be configured and customized. But this flexibility makes it more difficult for you to use. We understand this, and will soon provide a much easier way to set up and manage JBoss DNA. Current plans are to use the <ulink url="http://www.jboss.org/jbossmc">JBoss Microcontainer</ulink> - along with a configuration repository.</para> + along with a configuration repository that makes it very easy to set up and manage JBoss DNA, whether it's used in + a simple application or a cluster of processes.</para> </note> <para>To set up the repository service, we need to first set up a few other objects: <itemizedlist> @@ -155,13 +157,13 @@ <para>Now, the above code doesn't do any authentication; it essentially trusts the caller has the appropriate privileges. Normally, your application will need to authenticate the user, so let's look at how that's done.</para> <para>JBoss DNA uses the <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/tutoria... - Authentication and Authorization Service (JAAS)</ulink>, making it possible to use any existing JAAS security provider.</para> - <note> - <para>There are numerous JAAS providers, but one of the best open-source implementations is - <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink>, which can authenticate using LDAP, certificates, - the operating system, and federated SSO (among others).</para> - </note> - <para>The JCR API defines a <code>Credentials</code> marker interface, an instance of which can be passed to the + Authentication and Authorization Service (JAAS)</ulink>, making it possible to use any existing JAAS security provider. + There are numerous JAAS providers, but one of the best open-source implementations is + <ulink url="http://www.jboss.org/jbosssecurity/">JBoss Security</ulink>, which can authenticate using LDAP, certificates, + the operating system, and federated single-sign-on (among others). + </para> + <para> + The JCR API defines a <code>Credentials</code> marker interface, an instance of which can be passed to the <code>Session.login(...)</code> method. Rather than provide a concrete implementation of this interface, JBoss DNA allows you to pass any implementation of <code>Credentials</code> that also has one of the following methods: <itemizedlist> @@ -194,6 +196,7 @@ <para>Like many people recommend with JCR, you can create either long-lived or short-lived JCR <code>Session</code>s. The JBoss DNA implementation of JCR was designed to efficiently do either.</para> </sect2> + <!-- <sect2 id="using_dna_repositories_with_dna_api"> <title>Using JBoss DNA's API to read repository</title> <para>Although we recommend using JCR, JBoss DNA has an internal command-based API that completely side-steps JCR and provides @@ -202,6 +205,7 @@ <para>This API is likely to undergo changes in the next few releases, and using it at this time is not suggested.</para> </note> </sect2> + --> </sect1> <sect1 id="shutting_down_repository_service"> <title>Shutting down the Repository Service</title> @@ -253,15 +257,18 @@ org/jboss/example/dna/sequencers/RepositoryClientTest.java /RepositoryClientUsingJcrTest.java ]]></programlisting> - <para>The code we presented earlier in this chapter represent the bulk of the JBoss DNA and JCR-specific code used in the - <code>RepositoryClient</code>, so we won't cover it in more detail here. If you want to see that detail, please refer - to the sample client code.</para> + <para> + The code we presented earlier in this chapter represent the bulk of the JBoss DNA and JCR-specific code used in the + <code>RepositoryClient</code>, so we won't cover it in any more detail here. Please refer to the sample client code + if you want to see more. + </para> </sect1> <sect1 id="using_dna_repositories_review"> <title>Summarizing what we just did</title> <para>In this chapter we covered the different JBoss DNA components used for accessing repositories through JCR, including repositories that federate their content from the content of other repositories. Specifically, we described how the - <code>RepositoryService</code> and <code>JcrRepository</code> can be configured and used.</para> + <code>RepositoryService</code> and <code>JcrRepository</code> can be configured and used. + </para> </sect1> </chapter> Modified: trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml =================================================================== --- trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/gettingstarted/src/main/docbook/en-US/master.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -23,7 +23,7 @@ ~ 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 versionNumber "0.2"> <!ENTITY copyrightYear "2008"> <!ENTITY copyrightHolder "Red Hat Middleware, LLC."> ]> Modified: trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/reference/src/main/docbook/en-US/content/development_tools.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -41,11 +41,16 @@ <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). + 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 trying to get JBoss DNA to compile locally, you should make sure you have the JDK 5 installed and are using it. + If you're a contributor, you should make sure that you're using JDK 5 before committing any changes. </para> + <note> + <para> + 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. We periodically try to build JBoss DNA using JDK 6, but it's not our official JDK (yet). + </para> + </note> <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. @@ -54,21 +59,21 @@ 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 + When installing a JDK, 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> + <programlisting>$ java -version</programlisting> <para> - If you don't see the correct version, double-check your installation. + If you don't see the correct version, double-check your JDK 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="&Subversion;trunk/">trunk</ulink> of the Subversion repository + <ulink url="&Subversion;trunk/">trunk</ulink> of the Subversion repository directly (or using <ulink url="&Fisheye;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), @@ -234,7 +239,7 @@ </row> <row> <entry><ulink url="http://hudson.jboss.org/hudson/job/DNA%20nightly%20integration%... 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 + <entry>Build that runs every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to SVN since the previous night.</entry> </row> </tbody> @@ -292,6 +297,7 @@ 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. + Don't forget about the projects under <code>extensions/</code> or <code>docs/</code>. </para> </sect1> <sect1 id="releasing"> @@ -327,21 +333,21 @@ <note> <para> Before running Maven commands to build the releases, increase the memory available to Maven with this command: + <code>$ export MAVEN_OPTS=-Xmx256m</code> </para> - <programlisting>$ export MAVEN_OPTS=-Xmx256m</programlisting> </note> <para> To perform this complete build, issue the following command while in the <code>target/</code> directory: </para> <programlisting>$ mvn -P assembly clean javadoc:javadoc install</programlisting> <para> - This command runs "clean", "javadoc:javadoc", and "install" goals using the "assembly" profile, - which adds the production JavaDocs, the Getting Started document, the Reference Guide document, + This command runs the "clean", "javadoc:javadoc", and "install" goals using the "assembly" profile, + which adds the production of JavaDocs, the Getting Started document, the Reference Guide document, the Getting Started examples, and several ZIP archives. The order of the goals is important, since the "install" goal attempts to include the JavaDoc in the archives. </para> <para> - After completed, verify that the assemblies under <code>target/</code> have actually been created and that + After this build has completed, verify that the assemblies under <code>target/</code> have actually been created and that they contain the correct information. At this point, we know that the actual Maven build process is building everything we want and will complete without errors. We can now proceed with preparing for the release. @@ -350,7 +356,7 @@ <sect2 id="determine-version"> <title>Determine the version to be released</title> <para> - The version being released should match the &JIRA; road map. Make sure that all issues related to the release are closed. + The version being released should match the <ulink url="&JIRA;">JIRA</ulink> road map. Make sure that all issues related to the release are closed. The project lead should be notified and approve that the release is taking place. </para> </sect2> @@ -362,13 +368,13 @@ </para> <programlisting>$ mvn -Passembly release:prepare -DdryRun=true</programlisting> <para> - This may download a lot of Maven plugins if they already haven't been downloaded. It should then it should prompt you for - the release version of each of the projects, the tag name for the release, and the next development version. - The default values are probably acceptable; if not, then check that the "SNAPSHOT" version in each of the POM files is correct. + This may download a lot of Maven plugins if they already haven't been downloaded, but it will eventually prompt you for + the release version of each of the Maven projects, the tag name for the release, and the next development versions + (again for each of the Maven projects). The default values are probably acceptable; if not, then check that the + "<code>&lt;version&gt;</code>" tags in each of the POM files is correct and end with "-SNAPSHOT". </para> <para> - Once you have successfully completed the dry run of the release, you should clean up the files that the release - plugin created in the dry run: + After the dry run completes you should clean up the files that the release plugin created in the dry run: </para> <programlisting>$ mvn -Passembly release:clean</programlisting> </sect2> Modified: trunk/docs/reference/src/main/docbook/en-US/content/future.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/future.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/reference/src/main/docbook/en-US/content/future.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -28,14 +28,19 @@ ]> <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 + <para> + What's next for JBoss DNA? Well, the sequencing system is just the beginning. With this release, the sequencing system is stable enough so that more <link linkend="sequencers">sequencers</link> can be developed and used within your own applications. + We've also established the foundation for JBoss DNA repositories, including a number of <link linkend="repository-connectors">connectors</link>. + We'll continue to expand our library of sequencers and connectors, as well as expand our support of JCR. + Other components on our roadmap include a web user interface, a REST-ful server, and a view system that allows domain-specific + views of information in the repository. These components are farther out on our roadmap, and at this time have not been + targeted to a particular release. + </para> + <para> If you're interested in getting involved with the JBoss DNA project, consider picking up one of the sequencers on our - <ulink url="&JIRA;?report=com.atlassian.jira.plugin.system.project:roadmap-panel">roadmap</ulink>. + <ulink url="http://jira.jboss.org/jira/browse/DNA?report=com.atlassian.jira...;. Or, check out <ulink url="http://jira.jboss.org/jira/secure/IssueNavigator.jspa?reset=tru... - 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>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> + for the list of sequencers we've thought of. If you think of one that's not there, please add it to JIRA! + </para> </chapter> Modified: trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/reference/src/main/docbook/en-US/content/introduction.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -33,12 +33,12 @@ 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 + allowing those systems to continue "owning" the information while ensuring the unified repository stays up-to-date and in sync. JBoss DNA also analyzes the content you put into the repository and turns it into information you can use more effectively. </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 + security, configuration, and testing. So whether your a developer on the project, or you're 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"> @@ -47,10 +47,10 @@ 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. + farther, by also tracking the policies and expectations against which performance can be verified. + In these cases, a repository is an excellent mechanism for managing this complex and highly-varied information. + But a JBoss DNA repository doesn't have to be large and complex: it could just manage configuration information + for an application, or it could just provide a JCR interface on top of a couple of non-JCR systems. </para> </sect1> <sect1 id="what_is_metadata"> @@ -58,19 +58,21 @@ <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, + For example, 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 + There are a couple of important things to understand about metadata. First, the majority of metadata is either found in or 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>. + then we 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. + </para> + <para> + 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 @@ -82,11 +84,11 @@ 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. + like these, the repository should be able to automatically extract the most useful content and place it in + the repository where it can be much more easily used, searched, related, and analyzed. 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. + and it's an important part of a metadata repository. </para> <para> The third important characteristic of metadata is that it rarely stays the same. Different consumers of the @@ -111,7 +113,7 @@ 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. + or if it needs to be accessed by multiple processes. For these situations, other techniques often have more benefits. </para> <para> Another technique built into the Java language is @@ -119,12 +121,11 @@ , 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. + process to another. Using serialization for longer-term storage of information is more risky. </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 + One of the more popular and widely-used 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 @@ -138,33 +139,28 @@ <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. + 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. Plus, Hibernate is open-source (with support + offered by <ulink url="http://www.jboss.com">JBoss</ulink>). </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, + While relational databases and JPA are solutions that work well for many applications, they are more limited in cases when the + information structure is highly flexible, the structure is not known <emphasis>a priori</emphasis>, or that structure 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 with the storage capabilities of + relational databases and the flexibility offered by other systems, such as using files. Content repositories also + 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="&JSR170;">Content Repository for Java technology API</ulink> + <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="&JSR170;">JSR-170</ulink> - and is being revised under - <ulink url="&JSR283;">JSR-283</ulink> - . + 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> + 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 @@ -203,12 +199,12 @@ <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. + Rather than use a single formal development methodology, the JBoss DNA project incorporates those techniques, activities, and + processes that are practical and work for the project. 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: + Nevertheless, we do encourage familiarity with several major techniques, including: <itemizedlist> <listitem> <para> Modified: trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/reference/src/main/docbook/en-US/content/legal_notice.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -39,7 +39,7 @@ </address> </para> <para> - Copyright <trademark class="copyright"/> 2007 by Red Hat, Inc. This copyrighted material is made available to + Copyright <trademark class="copyright"/> &copyrightYear; 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. Modified: trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml =================================================================== --- trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml 2008-09-26 19:32:40 UTC (rev 552) +++ trunk/docs/reference/src/main/docbook/en-US/content/sequencing.xml 2008-09-26 20:50:59 UTC (rev 553) @@ -476,14 +476,14 @@ 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 <emphasis role="strong">dna-sequencer-images</emphasis> 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="&Subversion;trunk/extensions/dna-sequencer-images/">&Subversion;trunk/sequencers/dna-sequencer-images/</ulink> - </para> - </note> + and would like to help create it, please <link linkend="preface">join the community</link>. + </para> + <para>In lieu of a Maven archetype, you may find it easier to start with a small existing sequencer project. + The <emphasis role="strong">dna-sequencer-images</emphasis> project is a small, self-contained sequencer implementation that + has only the minimal dependencies. + See the subversion repository: <ulink url="&Subversion;trunk/extensions/dna-sequencer-images/">&Subversion;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_d... 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[