From dna-commits at lists.jboss.org Mon Apr 28 15:55:31 2008 Content-Type: multipart/mixed; boundary="===============4484966412137230313==" MIME-Version: 1.0 From: dna-commits at lists.jboss.org To: dna-commits at lists.jboss.org Subject: [dna-commits] DNA SVN: r111 - in trunk/docs/getting_started/en: modules and 1 other directory. Date: Mon, 28 Apr 2008 15:55:31 -0400 Message-ID: --===============4484966412137230313== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/getting_started/en/master.xml 2008-04-25 04:02:32 UTC (rev 1= 10) +++ trunk/docs/getting_started/en/master.xml 2008-04-28 19:55:31 UTC (rev 1= 11) @@ -1,30 +1,60 @@ - - -]> + JBoss DNA Getting Started Guide 0.1 - - - Target Audience - 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. - + + Table of Contents + - Preface + What this book covers + The goal of this book is to help you learn about JBoss DNA and h= ow you can use it in your own applications to get the + most out of your JCR repositories. + 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 p= robably worth reading even if you're already familiar + with these technologies. Besides, it's really not that long. + The If you're already familiar with these technologies, you can= probably skip this section. However, most readers will + probably want to + and then introduces JBoss DNA project and its relationship to J= CR. The second part + + Part I intr oduces JBoss DNAFeature Analysis= and Design + Part 1 + This document introduces the JBoss DNA project. - The build process is simplified and standardized. Just - follow the instructions in this guide to setup your docs - directory and copy a very simple pom.xml file. + + The build process is simplified and standardized. Just follow th= e instructions in this guide to setup your + docs + directory and copy a very simple + pom.xml + file. + - If you have any questions, please feel free to contact Randall Hauch (Project Lead) for m= ore information. + + If you have any questions or comments, please feel free to contact J= Boss DNA's + user mailing list + or use the + user forums + . If you'd like to get involved on the project, join the + mailing lists + , + download the= code + and get it building, and visit our + JIRA issue mana= gement system + . If there's something in particular you're interested in, talk with= the community - there may be others interested in the + same thing. + -&introduction;&howto;&styles; + + + + + + + \ No newline at end of file Added: trunk/docs/getting_started/en/modules/custom_sequencers.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + + + Custom sequencers + + \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/custom_sequencer= s.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) =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + + + Downloading the examples + 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 e= asily 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 a= n assembly of your final application + so that you can package into a distributable form. + + The examples created for this User Guide use Maven2 to achieve exactly= this so it is highly recommended that you + download + these first and take a look at how they work. + + + + To build and run the examples you first need to install and configur= e Maven 2.0.7 available from + http://maven.apache.org/ + + 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: + <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> + This profile informs maven of the two JBoss repositories (sn= apshots and releases) that are needed to download the JBoss Microcontainer = and dependant JARs. + + Once you have configured Maven and downloaded the examples the= n you can go to one of the following subdirectories in the examples/U= ser_Guide directory and enter mvn install to perform a = build: + + + gettingStarted - projects for creating and using a servic= e together with AOP + + + pojoDevelopment - examples of creating and configuring PO= JOs using XML and annotations + + + aopDevelopment - examples of using AOP to add behaviour to= POJOs + + + extending - examples of how we created various extensions= to the microcontainer by creating new dependencies + + + Instructions on how to run the individual examples can be foun= d in the corresponding parts of this guide. + \ No newline at end of file Added: trunk/docs/getting_started/en/modules/future_directions.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + + + Future directions + What's next for JBoss DNA? Well, sequencers are just the beginnin= g. = + Remember our architecture? + There are a lot of components on our roadmap, including federating + = + + \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/future_direction= s.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Modified: trunk/docs/getting_started/en/modules/introduction.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ - - Introduction to DocBook processing - DocBook is an XML format for writing documents. It allows the auth= or to - focus on the content itself during the writing process instead of - worrying about the presentation. - Using standard DocBook tags, we can tag the content according to - its syntatic structure. The DocBook document is then processed usi= ng - XSL stylesheets so that each tagged DocBook element is transformed= to a - corresponding element in the target output format. For example eac= h <para></para> element in DocBook could be transformed into a = <p></p> element in XHTML. - Using different XSL stylesheets, we can generate different - output formats. For example, we can generate both XHTML and PDF ou= tputs from - a single DocBook source. We can also generate multiple versions of= XHTML - (or PDF) files each with a different style if necessary. - In the JBoss DocBook system, we provide XSL stylesheets to build X= HTML, PDF and Eclipse Help output formats from the DocBook source. The buil= d process is - illustrated in . -
- The DocBook build process - - - - - -
- 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. + + + + Introduction + There are a lot of choices for how applications can store informat= ion 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 libr= aries and frameworks. + + Perhaps one of the easiest techniques is to simply store information in + files + . 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 compl= icated (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. + + + Another technique built into the Java language is + Java serialization + , 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, an= d 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. + + + One of the more popular persistence technologies is the + relational database + . 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 interac= ting with relational databases. However, it is a + low-level API that requires a lot of code to use correctly, and it sti= ll 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. + + + Object-relational mapping + libraries automate the creation of this mapping layer and result in fa= r less code that is much more maintainable with often as + good (if not better) performance than handwritten JDBC code. The new + Java Persistence API (JPA) + provide a standard mechanism for defining the mappings (through annota= tions) and working with these entity objects. Several + commercial and open-source libraries implement JPA, and some even offe= r additional capabilities and features that go beyond + JPA. For example, + Hibernate + 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. + + + While relational databases and JPA are solutions that work for many ap= plications, 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, + content repositories + may offer a better choice for persistence. Content repositories are al= most a hybrid between relational databases and file + systems, and typically provide other capabilies as well, including ver= sioning, indexing, search, access control, transactions, + and observation. Because of this, content repositories are used by con= tent 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, securit= y information, etc.). The + Content Repos= itory for Java technology API + provides a standard Java API for working with content repositories. Ab= breviated "JCR", this API was developed as part of the + Java Community Process under + JSR-170 + and is being revised under + JSR-283 + . + + + The + JBoss DNA project + 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 off= er the ability to upload files into the repository and + have the file content index for search purposes. JBoss DNA defines a l= ibrary for also sequencing that content to extract + meaningful information and store it in the repository, where it can th= en be searched, accessed and analyzed using the JCR API. + + JBoss DNA is building other features as well. One goal of JBoss D= NA 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. + + The + next chapter + in this book goes into more detail about JBoss DNA and its architectur= e, the different components, what's available now, and + what's coming in future releases. + Chapter 3 + then provides instructions for downloading and compiling the sequencer= examples for the current release. + Chapter 4 + walks through these examples, while + Chapter 5 + goes over how to create custom sequencers. Finally, + Chapter 6 + wraps things up. + \ No newline at end of file Added: trunk/docs/getting_started/en/modules/jboss_dna.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + + + JBoss DNA + What's next for JBoss DNA? Well, sequencers are just the beginnin= g. = + Remember our architecture? + There are a lot of components on our roadmap, including federating + = + + \ 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- trunk/docs/getting_started/en/modules/styles.xml 2008-04-25 04:02:32 UT= C (rev 110) +++ trunk/docs/getting_started/en/modules/styles.xml 2008-04-28 19:55:31 UT= C (rev 111) @@ -1,35 +0,0 @@ - - Maintaining the JBoss DocBook system - The structure of the - docbook-support - project is - illustrated in . The contents are a= s follows: -
- The docbook-support project - - - - - -
- - - The docs directory contains the DocBook sou= rce for this guide to - serve as a template for other projects. - - - The jbossorg-documentation directory contai= ns the maven plugin source for the parent POM that is referenced by each pr= oject's pom.xml file. The parent POM contains commo= n configuration information so that it does not have to be duplicated acro= ss multiple JBoss.org projects. - - - The jbossorg-docbook-xslt directory contain= s the maven plugin source for the default JBoss.org XSL stylesheets. These = stylesheets produce XHTML, PDF and Eclipse Help output. - - - The jbossorg-jdocbook-style directory conta= ins the maven plugin source for the default JBoss.org CSS and image files. = These provide the JBoss.org community-driven look & feel. - - - The styles and support = directories together with the support.xml file are prov= ided for backwards compatibility with projects that wish to continue using = Ant instead of Maven. The styles directory contains XSL= stylesheets together with CSS files to produce HTML and PDF outputs. The <= literal>support directory contains the DocBook = - libraries and DTDs along with = - the standard XSL stylesheets. The support.xml file contains common Ant tasks to perform the build. - - - \ No newline at end of file Added: trunk/docs/getting_started/en/modules/using_dna.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ + + + + Using JBoss DNA + + \ No newline at end of file Property changes on: trunk/docs/getting_started/en/modules/using_dna.xml ___________________________________________________________________ Name: svn:mime-type + text/plain --===============4484966412137230313==--