Author: rhauch
Date: 2008-05-08 23:47:36 -0400 (Thu, 08 May 2008)
New Revision: 135
Modified:
trunk/docs/gettingstarted/en/master.xml
Log:
Changes and additional copy
Modified: trunk/docs/gettingstarted/en/master.xml
===================================================================
--- trunk/docs/gettingstarted/en/master.xml 2008-05-08 22:00:44 UTC (rev 134)
+++ trunk/docs/gettingstarted/en/master.xml 2008-05-09 03:47:36 UTC (rev 135)
@@ -162,10 +162,10 @@
<link linkend="jboss_dna">next chapter</link>
in this book goes into more detail about JBoss DNA and its architecture, the
different components, what's available now, and
what's coming in future releases.
- <link linkend="downloading">Chapter 3</link>
- then provides instructions for downloading and compiling the sequencer examples for
the current release.
+ <link linkend="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 these examples, while
+ 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_directions">Chapter 6</link>
@@ -195,15 +195,14 @@
<para>The architecture for JBoss DNA consists of several major components
that will be built on top of standard APIs,
including JCR, JDBC, JNDI and HTTP. The goal is to allow these components to be
assembled as needed and add value on top
of other DNA components or third-party systems that support the standard
APIs.</para>
- <!-- mediaobject>
- <imageobject>
+ <mediaobject>
+ <imageobject role="fo">
<imagedata align="center"
fileref="images/dna-architecture.png"/>
</imageobject>
- </mediaobject -->
- <figure id="dna-architecture">
- <title>JBoss DNA Architecture</title>
- <graphic align="center" scale="60"
fileref="images/dna-architecture.png" />
- </figure>
+ <imageobject role="html">
+ <imagedata align="center"
fileref="images/dna-architecture.png"/>
+ </imageobject>
+ </mediaobject>
<para>
As shown in the diagram above, the major components are (starting at the top):
<itemizedlist>
@@ -304,8 +303,20 @@
</listitem>
</itemizedlist>
</para>
+ <para>
+ Continue reading the rest of this chapter for more detail about the
+ <link linkend="sequencers">sequencing framework</link>
+ available in this release, or the
+ <link linkend="federation">federation engine</link>
+ and
+ <link linkend="federation_connectors">connectors</link>
+ that will be the focus of the next release. Or, skip to the
+ <link linkend="downloading_and_running">examples</link>
+ to see how to start using JBoss DNA &versionNumber;
+ today.
+ </para>
</sect1>
- <sect1>
+ <sect1 id="sequencers">
<title>Sequencers</title>
<para> The current JBoss DNA release contains a sequencing framework that is
designed to sequence data (typically files)
stored in a JCR repository to automatically extract meaningful and useful
information. This additional information is then
@@ -451,7 +462,7 @@
goes into detail about how to write custom sequencers.
</para>
</sect1>
- <sect1>
+ <sect1 id="federation">
<title>Federation</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
@@ -474,7 +485,7 @@
changes, client applications using JCR observation will be notified of the
changes. If a JBoss DNA federated 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>
+ <sect2 id="federation_connectors">
<title>Connectors</title>
<para>
The JBoss DNA federation engine will use connectors to interact with different
information sources to get at the content
@@ -553,7 +564,7 @@
provide an implementation.
</para>
</sect2>
- <sect2>
+ <sect2 id="federation_sources">
<title>Sources</title>
<para>
Each JBoss DNA federated repository is configured to federate and integrate
information from one or more
@@ -564,7 +575,7 @@
federated repository.
</para>
</sect2>
- <sect2>
+ <sect2 id="federation_graph">
<title>Building the unified graph</title>
<para> The federation engine works by effectively building up a single
graph by querying each source and merging or
unifying the responses. This information is cached, which improves performance,
reduces the number of (potentially
@@ -593,7 +604,7 @@
or the frequent checking with the source.
</para>
</sect2>
- <sect2>
+ <sect2 id="federation_queries">
<title>Queries</title>
<para> The JBoss DNA federated repository will also support queries against
the integrated and unified graph. In some
situations the query can be determined to apply to a single source, but in most
situations the query must be planned
@@ -604,7 +615,7 @@
implements sophisticated query planning and optimization techniques for working
efficiently with multiple sources.
</para>
</sect2>
- <sect2>
+ <sect2 id="federation_updates">
<title>Updates</title>
<para>
The JBoss DNA federated repositories also make it possible for client
applications to make changes to the unified graph
@@ -627,7 +638,7 @@
changes to other clients.)
</para>
</sect2>
- <sect2>
+ <sect2 id="federation_events">
<title>Events</title>
<para> The JCR API supports observing a repository to receive notifications
of additions, changes and deletions of nodes
and properties. The JBoss DNA federated repository will support this API
through two primary means.</para>
@@ -645,27 +656,26 @@
<!--
====================================================================================================
Chapter
====================================================================================================
-->
- <chapter id="downloading">
- <title>Downloading the examples</title>
+ <chapter id="downloading_and_running">
+ <title>Example application</title>
<para>JBoss DNA is built using Maven 2, so it's much easier to following
along with the examples in this document if you
install and configure Maven. Once this is done, you can very easily build the
examples or even create a maven project that
depends on the JBoss DNA JARs. Maven will automatically download the right versions
of the JARs, including those other
libraries on which JBoss DNA depends. Maven also makes it very easy to create an
assembly of your final application so that
you can package into a distributable form.</para>
- <para>
- The examples created for this User Guide use Maven2 to achieve exactly this so it
is highly recommended that you
- <ulink
url="http://www.jboss.org/file-access/default/members/dna/downloads/...
- these first and take a look at how they work.
- </para>
<note>
<para>
- To build and run the examples you first need to install and configure Maven 2.0.7
(or higher), available from
+ To use Maven with JBoss DNA, you'll first need to install
+ <ulink
url="http://java.sun.com/javase/downloads/index_jdk5.jsp">JDK
5</ulink>
+ and Maven 2.0.7 (or higher), which is available from
<ulink
url="http://maven.apache.org/">http://maven.apache.org/</...
+ .
</para>
- <para>Installation is performed by downloading and unzipping the
maven-2.0.7-bin.zip file to a convenient
- location on your local disk. Configuration consists of adding $MAVEN_HOME/bin to
your path and adding the following
- profile to your ~/.m2/settings.xml file:</para>
- <programlisting role="XML"
language="xml"><settings>
+ <para>
+ Maven is installed 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:
+ <programlisting role="XML"
language="xml"><settings>
<profiles>
<profile>
<id>jboss.repository</id>
@@ -709,14 +719,35 @@
</profile>
</profiles>
</settings></programlisting>
- <para>This profile informs Maven of the two JBoss repositories (snapshots
and releases) that are needed to download the JARs for JBoss DNA and all dependent
libraries.</para>
+ This profile informs Maven of the two JBoss repositories (snapshots and releases)
that contain
+ all of the JARs for JBoss DNA and all dependent libraries.</para>
</note>
- <para>After you have configured Maven and extracted the examples to a working
folder, you can go to the <code>examples</code>
- subdirectory and enter <code>mvn install</code> to perform a
build. Maven will automatically download all of the libraries
- that are needed by the build, saving them to your local machine. (This means
the next time you run <code>mvn install</code>,
- all the libraries will be local, and the build will run much faster.)
+ <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/...
+ 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:
+ <programlisting>
+examples/pom.xml
+ sequencers/pom.xml
+ /src/main/assembly
+ /config
+ /java
+ /resources
+ /test/java
+ /resources
+ </programlisting>
</para>
- <para>The build is successful if you see the following:</para>
+ <para>There are essentially two Maven projects: a
<code>sequencers</code> project and a parent project. All of the source
+ for the examples are located in the <code>sequencers</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>.
+ 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:
<programlisting language="bash">$ mvn install
...
[INFO] ------------------------------------------------------------------------
@@ -733,64 +764,8 @@
[INFO] Final Memory: 14M/28M
[INFO] ------------------------------------------------------------------------
$ </programlisting>
- <para>If there are errors, check whether you have the correct version of
Maven installed and that you've correctly updated
+ If there are errors, check whether you have the correct version of Maven installed
and that you've correctly updated
your Maven settings as described above.</para>
- <para>
- The <link linkend="using_dna">next chapter</link> shows
you how to run the examples and walks through the source code to
- show you how to use JBoss DNA.</para>
- </chapter>
-<chapter id="using_dna">
- <title>Using JBoss DNA</title>
- <para>With this release, JBoss DNA is able to monitor existing JCR repositories
and automatically sequence newly upload files and updated content.
- The information produced by the sequencers is saved to the repository, making it
available to any repository client.
- Using JBoss DNA, therefore, consists of setting up the DNA Java components and
connecting them to the JCR repositories.
- This chapter walks you through this process, using the examples downloaded in the
<link linkend="downloading">previous chapter</link>.
- </para>
- <para>You will find all of the necessary files for the example in the
<code>examples/sequencers</code> directory, which follows the
- Maven Standard Directory Layout:
- <programlisting>
-sequencers/pom.xml
- /src/main/assembly
- /config
- /java
- /resources
- /test/java
- /resources
- </programlisting>
- </para>
- <para>This example consists of a client application that sets up an in-memory JCR
repository and that allows a user
- to upload files into that repository. The client also sets up the DNA services with an
image sequencer so that
- if any of the uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will
automatically extract the image's
- metadata (e.g., image format, physical size, pixel density, etc.) and store that in the
repository.
- </para>
- <para>The example is comprised of 3 classes and 1 interface, located in the
<code>src/main/java</code> directory:
- <programlisting>
-org/jboss/example/dna/sequencers/ConsoleInput.java
- /ImageInfo.java
- /SequencingClient.java
- /UserInterface.java
- </programlisting>
- </para>
- <para>
- <code>SequencingClient</code> is the class that contains the main
application. <code>ImageInfo</code> is a simple
- Java object that encapsulates metadata about an image (as generated by the sequencer),
and used by the client to pass
- information to the <code>UserInterface</code>, which is an interface with
methods that will be called at
- runtime to request data from the user. <code>ConsoleInput</code> is an
implementation of this that creates a text user interface,
- allowing the user to operate the client from the command line. We can easily create a
graphical implementation of
- <code>UserInterface</code> at a later date. We can also create a mock
implementation for
- testing purposes that simulates a user entering data. This allows us to check the
behaviour of the client automatically using conventional
- JUnit test cases, as demonstrated by the code in the
<code>src/test/java</code> directory:
- <programlisting>
-org/jboss/example/dna/sequencers/SequencingClientTest.java
- /MockUserInterface.java
- </programlisting>
- </para>
- <sect1 id="running_examples">
- <title>Running the example</title>
- <para>
- As mentioned in the <ulink url="downloading">previous
chapter</ulink>, simply type <code>mvn package</code> from the
<code>example/sequencer</code>
- directory to compile the source code, run the unit tests, build a client JAR and
assemble a distribution containing all of the necessary files.
- </para>
<para>If you successfully built the examples, there will be a
<code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code>
directory that contains the following:
<itemizedlist>
@@ -854,42 +829,94 @@
</para>
</note>
</para>
+ </sect1>
+ <sect1 id="running">
+ <title>Running the example</title>
+ <para>This example consists of a client application that sets up an in-memory
JCR repository and that allows a user to
+ upload files into that repository. The client also sets up the DNA services with an
image sequencer so that if any of the
+ uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will automatically
extract the image's metadata (e.g., image
+ format, physical size, pixel density, etc.) and store that in the
repository.</para>
<para>
- To run the client application, go to the
<code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code>
- directory and type <code>./run.sh</code>. You should see the command
line client and its menus in your terminal:
- <figure id="xample-sequencer-cli-client">
- <title>Example Client</title>
- <graphic align="center" scale="100"
fileref="images/example-sequencer-cli-client.png" />
- </figure>
- From this menu, you can upload a file into the repository, search for images in the
repository, print sequencing statistics, or quit the application.
+ To run the client application, go to the
+ <code>examples/sequencers/target/dna-example-sequencers-basic.dir/
+ </code>
+ directory and type
+ <code>./run.sh</code>
+ . You should see the command line client and its menus in your terminal:
+ <figure id="xample-sequencer-cli-client">
+ <title>Example Client</title>
+ <graphic align="center" scale="100"
fileref="images/example-sequencer-cli-client.png" />
+ </figure>
+ From this menu, you can upload a file into the repository, search for images in the
repository, print sequencing statistics,
+ or quit the application.
</para>
<para>
- The first step is to upload one of the example images. If you type 'u' and
press return, you'll be prompted
- to supply the path to the file you want to upload. Since the application is running
from within the
- <code>examples/sequencers/target/dna-example-sequencers-basic.dir/</code>
directory, you can specify any
- of the files in that directory without specifying the path:
- <figure id="example-sequencer-upload">
- <title>Uploading an image using the Example Client</title>
- <graphic align="center" scale="100"
fileref="images/example-sequencer-upload.png" />
- </figure>
- You can specify any fully-qualified or relative path. The application will notify
you if it cannot
- find the file you specified. The example client configures JBoss DNA to sequence
image files (technically nodes that have names)
- with one of the following
- extensions: <code>jpg</code>, <code>jpeg</code>,
<code>gif</code>, <code>bmp</code>,
- <code>pcx</code>, <code>png</code>,
<code>iff</code>, <code>ras</code>, <code>pbm</code>,
<code>pgm</code>, <code>ppm</code>, and
<code>psd</code>.
- Files with other extensions in the repository path will be ignored. For your
convenience, the example provides
- several files that will be sequenced (<code>caution.png</code>,
<code>caution.jpg</code> and <code>caution.gif</code>)
- and one image that will not be sequenced (<code>caution.pict</code>).
Feel free to try other files.
+ The first step is to upload one of the example images. If you type 'u' and
press return, you'll be prompted to supply the
+ path to the file you want to upload. Since the application is running from within
the
+ <code>examples/sequencers/target/dna-example-sequencers-basic.dir/
+ </code>
+ directory, you can specify any of the files in that directory without specifying
the path:
+ <figure id="example-sequencer-upload">
+ <title>Uploading an image using the Example Client</title>
+ <graphic align="center" scale="100"
fileref="images/example-sequencer-upload.png" />
+ </figure>
+ You can specify any fully-qualified or relative path. The application will notify
you if it cannot find the file you
+ specified. The example client configures JBoss DNA to sequence image files
(technically nodes that have names) with one of
+ the following extensions:
+ <code>jpg</code>
+ ,
+ <code>jpeg</code>
+ ,
+ <code>gif</code>
+ ,
+ <code>bmp</code>
+ ,
+ <code>pcx</code>
+ ,
+ <code>png</code>
+ ,
+ <code>iff</code>
+ ,
+ <code>ras</code>
+ ,
+ <code>pbm</code>
+ ,
+ <code>pgm</code>
+ ,
+ <code>ppm</code>
+ , and
+ <code>psd</code>
+ . Files with other extensions in the repository path will be ignored. For your
convenience, the example provides several
+ files that will be sequenced (
+ <code>caution.png</code>
+ ,
+ <code>caution.jpg</code>
+ and
+ <code>caution.gif</code>
+ ) and one image that will not be sequenced (
+ <code>caution.pict</code>
+ ). Feel free to try other files.
</para>
<para>
- After you specified the file you want to upload, the example application asks you
where in the repository you'd
- like to place the file. (If you want to use the suggested location, just press
<code>return</code>.)
- The client application uses the JCR API to upload the file to that location in the
repository, creating any nodes (of type <code>nt:folder</code>)
- for any directories that don't exist, and creating a node (of type
<code>nt:file</code>) for the file. And,
- per the JCR specification, the application creates a
<code>jcr:content</code> node (of type <code>nt:resource</code>)
- under the file node. The file contents are placed on this
<code>jcr:content</code> node in the <code>jcr:data</code>
property.
- For example, if you specify <code>/a/b/caution.png</code>, the following
structure will be created in the repository:
- <programlisting>
+ After you specified the file you want to upload, the example application asks you
where in the repository you'd like to
+ place the file. (If you want to use the suggested location, just press
+ <code>return</code>
+ .) The client application uses the JCR API to upload the file to that location in
the repository, creating any nodes (of
+ type
+ <code>nt:folder</code>
+ ) for any directories that don't exist, and creating a node (of type
+ <code>nt:file</code>
+ ) for the file. And, per the JCR specification, the application creates a
+ <code>jcr:content</code>
+ node (of type
+ <code>nt:resource</code>
+ ) under the file node. The file contents are placed on this
+ <code>jcr:content</code>
+ node in the
+ <code>jcr:data</code>
+ property. For example, if you specify
+ <code>/a/b/caution.png</code>
+ , the following structure will be created in the repository:<programlisting>
/a (nt:folder)
/b (nt:folder)
/caution.png (nt:file)
@@ -899,14 +926,15 @@
@jcr:lastModified = {now}
</programlisting>
</para>
- <para>
- When the client uploads the file using the JCR API, DNA gets notified of the changes,
consults the sequencers
- to see whether any of them are interested in the new or updated content, and if so
runs the sequencers. The image
- sequencer processes image files for metadata, and any metadata found is stored under
the <code>/images</code>
- branch of the repository. All of this happens asynchronously, so any DNA activity
doesn't impede or slow
- down the client activities.
- </para>
- <para>
+ <para>
+ When the client uploads the file using the JCR API, DNA gets notified of the changes,
consults the sequencers to see whether
+ any of them are interested in the new or updated content, and if so runs the
sequencers. The image sequencer processes image
+ files for metadata, and any metadata found is stored under the
+ <code>/images</code>
+ branch of the repository. All of this happens asynchronously, so any DNA activity
doesn't impede or slow down the client
+ activities.
+ </para>
+ <para>
So, after the file is uploaded, you can search the repository for the image metadata
using the "s" menu option:
<figure id="example-sequencer-search">
<title>Uploading an image using the Example Client</title>
@@ -917,20 +945,71 @@
<title>Uploading an image using the Example Client</title>
<graphic align="center" scale="100"
fileref="images/example-sequencer-statistics.png" />
</figure>
- These stats show how many nodes were sequenced, and how many nodes were skipped
because they didn't apply to the
- sequencer's criteria.</para>
- <note>
- <para>There will probably be more nodes skipped than sequenced, since there are
more <code>nt:folder</code>
- and <code>nt:resource</code> nodes than there are
<code>nt:file</code> nodes with acceptible names.
- </para>
- </note>
+ These stats show how many nodes were sequenced, and how many nodes were skipped
because they didn't apply to the sequencer's
+ criteria.
+ </para>
+ <note>
<para>
- You can repeat this process with other files. Any file that isn't an image (as
recognized by the sequencing configuration
- described later) will not be sequenced.
+ There will probably be more nodes skipped than sequenced, since there are more
+ <code>nt:folder</code>
+ and
+ <code>nt:resource</code>
+ nodes than there are
+ <code>nt:file</code>
+ nodes with acceptible names.
</para>
+ </note>
+ <para>You can repeat this process with other files. Any file that isn't an
image (as recognized by the sequencing configuration
+ that we'll describe later) will not be sequenced.</para>
</sect1>
- <sect1 id="example_java_code">
- <title>Reviewing the Java code</title>
+ </chapter>
+
+
+
+
+
+ <!--
====================================================================================================
+ Chapter
+
====================================================================================================
-->
+<chapter id="using_dna">
+ <title>Using JBoss DNA</title>
+ <para></para>
+
+
+ <para>This example consists of a client application that sets up an in-memory JCR
repository and that allows a user
+ to upload files into that repository. The client also sets up the DNA services with an
image sequencer so that
+ if any of the uploaded files are PNG, JPEG, GIF, BMP or other images, DNA will
automatically extract the image's
+ metadata (e.g., image format, physical size, pixel density, etc.) and store that in the
repository.
+ </para>
+ <para>The example is comprised of 3 classes and 1 interface, located in the
<code>src/main/java</code> directory:
+ <programlisting>
+org/jboss/example/dna/sequencers/ConsoleInput.java
+ /ImageInfo.java
+ /SequencingClient.java
+ /UserInterface.java
+ </programlisting>
+ </para>
+ <para><code>SequencingClient</code> is the class that contains the
main application. <code>ImageInfo</code> is a simple
+ Java object that encapsulates metadata about an image (as generated by the sequencer),
and used by the client to pass
+ information to the <code>UserInterface</code>, which is an interface with
methods that will be called at
+ runtime to request data from the user. <code>ConsoleInput</code> is an
implementation of this that creates a text user interface,
+ allowing the user to operate the client from the command line. We can easily create a
graphical implementation of
+ <code>UserInterface</code> at a later date. We can also create a mock
implementation for
+ testing purposes that simulates a user entering data. This allows us to check the
behaviour of the client automatically using conventional
+ JUnit test cases, as demonstrated by the code in the
<code>src/test/java</code> directory:
+ <programlisting>
+org/jboss/example/dna/sequencers/SequencingClientTest.java
+ /MockUserInterface.java
+ </programlisting>
+ </para>
+
+<!-- Reviewing the code -->
+ <para>The example application you just used demonstrated how JBoss DNA
sequencing responds
+ to the changes in a repository. This example doesn't do much, but the con
</para>
+
+ <para>The example application you just used demonstrated how JBoss DNA
sequencing responds
+ to the changes in a repository. This example was pretty simple, but </para>
+
<para>The example you just ran demonstrated that JBoss DNA does sequence image
files. It does everything
necessary to set up and configure JBoss DNA to use a JCR repository, so reviewing
that code can help understand
what's involved.
@@ -940,15 +1019,43 @@
<code>ConsoleInput</code>, and <code>ImageInfo</code> classes
are there to just make the example easy to run.
The interesting code is in <code>SequencingClient</code>.
</para>
-
<para>
+ The <code>SequencingClient</code> class contains several methods that
work with the JBoss DNA components.
+ One of these is the <code>ObservationService</code> that monitors JCR
workspaces and serves as a broker
+ for events describing sets of changes to those JCR workspaces.
</para>
- </sect1>
+
+ <para>Three of the most important concepts in the JCR API are the
<emphasis>repository</emphasis> (represented
+ by the <code>javax.jcr.Repository</code> interface), the
<emphasis>workspace</emphasis> (represented by the
+ <code>javax.jcr.Workspace</code> interface), and a
<emphasis>session</emphasis> (represented by the
+ <code>javax.jcr.Session</code> interface). A single repository can contain
multiple workspaces, each of which
+ contains a tree of nodes with properties and relationships that form a graph. A client
connects to the repository
+ by providing credentials and the name of the workspace they wish to use. If the
client's credentials are
+ authenticated, the repository returns a session that provides access to all the nodes
in the workspace and
+ methods for adding, changing or deleting nodes.
+ </para>
+ <para>A session in the JCR API is not thread-safe. In other words, it is
designed to be used by a single thread.
+ If multiple threads in an application are to concurrently use a single session, that
application is responsible
+ for ensuring that all access to the session is properly synchronized and controlled.
Separate sessions,
+ on the other hand, may be used concurrently and in isolation, although all committed
changes to the workspace's
+ nodes are immediately visible to all sessions using that workspace.</para>
+ <note>
+ <para>This design follows a very common pattern: establish a connection to a
resource, use that connection,
+ then close the connection. If you need to use the resource again, you must establish a
new connection, use it,
+ and close the connection. The Java Database Connectivity (JDBC) API uses a similar
pattern
+ with it's <code>java.sql.Connection</code> interface.
+ </para>
+ </note>
+ <para>The challenge with this approach in JCR, however, is that the credentials
must be used every time a
+ session is to be created.
+ session</para>
+
+
</chapter>
<chapter id="custom_sequencers">
<title>Custom sequencers</title>