3:18 p.m.
Author: jverhaeg(a)redhat.com
Date: 2008-05-14 16:18:07 -0400 (Wed, 14 May 2008)
New Revision: 172
Modified:
trunk/docs/gettingstarted/en/master.xml
Log:
DNA-70: Corrected some grammatical errors and omissions, did a little word-smithing.
Modified: trunk/docs/gettingstarted/en/master.xml
===================================================================
--- trunk/docs/gettingstarted/en/master.xml 2008-05-14 01:52:41 UTC (rev 171)
+++ trunk/docs/gettingstarted/en/master.xml 2008-05-14 20:18:07 UTC (rev 172)
@@ -1043,11 +1043,11 @@
<title>Configuring the Sequencing Service</title>
<para>
The JBoss DNA <emphasis>sequencing service</emphasis> is the component
that manages the <emphasis>sequencers</emphasis>
- and that reacts to changes in JCR repositories and then running the appropriate
sequencers.
- This involves processing the changes on a node, determinine which (if any)
sequencer should be run on that node,
+ , reacting to changes in JCR repositories and then running the appropriate
sequencers.
+ This involves processing the changes on a node, determining which (if any)
sequencers should be run on that node,
and for each sequencer constructing the execution environment, calling the
sequencer, and saving the information
generated by the sequencer.</para>
- <para>To set up the sequencing service, an instance is created and dependent
components are injected into
+ <para>To set up the sequencing service, an instance is created, and dependent
components are injected into
the object. This includes among other things:
<itemizedlist>
<listitem>
@@ -1057,7 +1057,7 @@
</listitem>
<listitem>
<para>An optional <emphasis>factory for class
loaders</emphasis> used to load sequencers. If no factory is supplied,
- the service uses the current thread's context class loader (or if that is
null the class loader that loaded the
+ the service uses the current thread's context class loader (or if that is
null, the class loader that loaded the
sequencing service class).</para>
</listitem>
<listitem>
@@ -1111,7 +1111,7 @@
</para>
<para>The sequencing service must also be configured with the sequencers that
it will use. This is done using the
<code>addSequencer(SequencerConfig)</code> method and passing a
<code>SequencerConfig</code> instance that
- can create. Here's an example:
+ you create. Here's an example:
<programlisting>
String name = "Image Sequencer";
String desc = "Sequences image files to extract the characteristics of the
image";
@@ -1160,7 +1160,7 @@
class and the corresponding
<code>org.jboss.dna.repository.sequencer.SequencerPathExpressionTest</code>
test case.</para>
</note>
<para>After the service is started, it is ready to start reacting to changes
in the repository. But it first
- must be wired to the repositories using listener. This is accomplished using the
<code>ObservationService</code>
+ must be wired to the repositories using a listener. This is accomplished using the
<code>ObservationService</code>
described in the <link linkend="observation_service">next
section</link>.</para>
</sect1>
<sect1 id="observation_service">
@@ -1170,15 +1170,16 @@
name of the repository and workspace that can be passed to a
<code>SessionFactory</code> to obtain a session
to the repository in which the change occurred. This simple design makes it very
easy for JBoss DNA to
concurrently work with multiple JCR repositories.</para>
- <para>Configuring an ObservationService is pretty easy, especially if you reuse
the same <code>SessionFactory</code>
- supplied to the SequencingService. Here's an example:
+ <para>Configuring an observation service is pretty easy, especially if you
reuse the same <code>SessionFactory</code>
+ supplied to the sequencing service. Here's an example:
<programlisting>
this.observationService = new ObservationService(sessionFactory);
this.observationService.getAdministrator().start();</programlisting>
</para>
<note>
- <para>Both the ObservationService implement
<code>AdministeredService</code>, which has a
<code>ServiceAdministrator</code> used to
- start, pause, and shutdown the service. In other words, the lifecycle of the
services are managed in the same way.</para>
+ <para>Both <code>ObservationService</code> and
<code>SequencingService</code> implement
+ <code>AdministeredService</code>, which has a
<code>ServiceAdministrator</code> used to start, pause, and shutdown the
+ service. In other words, the lifecycle of the services are managed in the same
way.</para>
</note>
<para>
After the observation service is started, listeners can be added. The
<code>SequencingService</code> implements the required
@@ -1186,21 +1187,21 @@
<programlisting>
observationService.addListener(sequencingService);</programlisting>
</para>
- <para>Finally, the observation service must be wired to monitor one or your JCR
repositories. This is done with
+ <para>Finally, the observation service must be wired to monitor one of your JCR
repositories. This is done with
one of the <code>monitor(...)</code> methods:
<programlisting>
int eventTypes = Event.NODE_ADDED | Event.PROPERTY_ADDED | Event.PROPERTY_CHANGED;
observationService.monitor("Main Repository/Workspace1",
eventTypes);</programlisting>
</para>
- <para>At this point, the observation service is listening to a JCR repository,
and forwarding the appropriate events
+ <para>At this point, the observation service is listening to a JCR repository
and forwarding the appropriate events
to the sequencing service, which will asynchronously process the changes and sequence
the information added to or changed in the repository.
</para>
</sect1>
<sect1 id="shutting_down">
<title>Shutting down JBoss DNA services</title>
- <para>The JBoss DNA services are utilizing resources and threads that must be
released your application is ready to shut down.
+ <para>The JBoss DNA services are utilizing resources and threads that must be
released before your application is ready to shut down.
The safe way to do this is to simply obtain the
<code>ServiceAdministrator</code> for each service (via the
<code>getServiceAdministrator()</code> method)
- and call <code>shutdown()</code>. As previously mentioned, the shutdown
method will simply prevent new work from being process
+ and call <code>shutdown()</code>. As previously mentioned, the shutdown
method will simply prevent new work from being processed
and will not wait for existing work to be completed. If you want to wait until the
service completes all its work, you must wait
until the service terminates. Here's an example that shows how this is done:
<programlisting>
@@ -1221,7 +1222,7 @@
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. Or, if the client uploads
- MP3 audio files, the title, author, album, year, and comment are extract from the
audio file and stored in the repository.</para>
+ MP3 audio files, the title, author, album, year, and comment are extracted from the
audio file and stored in the repository.</para>
<para>
The example is comprised of 3 classes and 1 interface, located in the
<code>src/main/java</code>
@@ -1241,11 +1242,11 @@
<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
+ 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
+ allows us to check the behavior of the client automatically using conventional
JUnit test cases, as demonstrated by the
code in the
<code>src/test/java</code>
directory:
@@ -1317,7 +1318,7 @@
<para>
The
<code>shutdownRepository()</code>
- method shuts down the Jackrabbit transient repository by closing the "keep
alive session". Again, this method really does
+ method shuts down the Jackrabbit transient repository by closing the
"keep-alive session". Again, this method really does
nothing specifically with JBoss DNA, but is needed to manage the JCR repository
that JBoss DNA uses.
<programlisting>
public void shutdownRepository() throws Exception {
@@ -1334,13 +1335,13 @@
<para>
The
<code>startDnaServices()</code>
- method first starts the JCR repository (if it were not already started), and
proceeds to create and configure the
+ method first starts the JCR repository (if it was not already started), and
proceeds to create and configure the
<code>SequencingService</code>
as described
<link linkend="sequencing_service">earlier</link>
. This involes setting up the
<code>SessionFactory</code>
- ,
+ and
<code>ExecutionContext</code>
, creating the
<code>SequencingService</code>
@@ -1411,7 +1412,7 @@
this.observationService.getAdministrator().awaitTermination(5, TimeUnit.SECONDS);
}</programlisting>
</para>
- <para>None of the other methods really do anything with JBoss DNA per se.
Instead, they merely work with the repository
+ <para>None of the other methods really do anything with JBoss DNA
<emphasis>per se</emphasis>. Instead, they merely work with the repository
using the JCR API.</para>
<para>
The <code>main</code> method of the
<code>SequencingClient</code> class creates a
<code>SequencingClient</code> instance,
@@ -1495,11 +1496,11 @@
the functionality and expected behavior;</para>
</listitem>
<listitem>
- <para>Add the sequencer configuration to the JBoss DNA
<code>SequencingService</code> in your application,
+ <para>Add the sequencer configuration to the JBoss DNA
<code>SequencingService</code> in your application
as described in the <link linkend="using_dna">previous
chapter</link>; and</para>
</listitem>
<listitem>
- <para>Deploy the JAR file with your implementation (as well as any
dependencies) and make them available to JBoss DNA
+ <para>Deploy the JAR file with your implementation (as well as any
dependencies), and make them available to JBoss DNA
in your application.</para>
</listitem>
</itemizedlist>
@@ -1630,7 +1631,7 @@
<sect1 id="custom_sequencer_implementation">
<title>Implementing the StreamSequencer interface</title>
<para>After creating the project and setting up the dependencies, the next step
is to create a Java class that implements
- the <code>org.jboss.dna.spi.sequencers.StreamSequencer</code> interface.
This interface is very straightforward,
+ the <code>org.jboss.dna.spi.sequencers.StreamSequencer</code> interface.
This interface is very straightforward
and involves a single method:
<programlisting>
public interface StreamSequencer {
@@ -1650,7 +1651,7 @@
</para>
<para>The job of a stream sequencer is to process the data in the supplied
stream, and place into the <code>SequencerOutput</code>
any information that is to go into the JCR repository. JBoss DNA figures out when
your sequencer should be called
- (of course using the sequencing configuration you'll add in a bit), and then
makes sure the generated information
+ (of course, using the sequencing configuration you'll add in a bit), and then
makes sure the generated information
is saved in the correct place in the repository.
</para>
<para>The <code>SequencerOutput</code> class is fairly easy to use.
There are basically two methods you need to call.
@@ -1761,7 +1762,7 @@
}</programlisting>
</para>
<para>
- Notice how the image metadata is extracted, and the output graph is generated. A
single node is created with the name <code>image:metadata</code>
+ Notice how the image metadata is extracted and the output graph is generated. A
single node is created with the name <code>image:metadata</code>
and with the <code>image:metadata</code> node type. No mixins are
defined for the node, but several properties are set on the node
using the values obtained from the image metadata. After this method returns, the
constructed graph will be saved to the repository
in all of the places defined by its configuration. (This is why only relative paths
are used in the sequencer.)
@@ -1830,13 +1831,13 @@
}</programlisting>
</para>
<para>These are just two simple tests that show ways of testing a sequencer.
Some tests may get quite involved,
- especially if a lot of output data are produced.
+ especially if a lot of output data is produced.
</para>
<para>It may also be useful to create some integration tests
- that <link linkend="using_dna">configures JBoss DNA</link> to
use the custom sequencer, and to then upload
+ that <link linkend="using_dna">configure JBoss DNA</link> to
use a custom sequencer, and to then upload
content using the JCR API, verifying that the custom sequencer did run. However,
remember that JBoss DNA
runs sequencers asynchronously in the background, and you must sychronize your tests
to ensure that the
- sequencers have a chance to run before checking the results. (One way of doing this
is to wait for a second
+ sequencers have a chance to run before checking the results. (One way of doing this
(although, granted, not always reliable) is to wait for a second
after uploading your content, shutdown the <code>SequencingService</code>
and await its termination,
and then check that the sequencer output has been saved to the JCR repository. For
an example of this technique,
see the <code>SequencingClientTest</code> unit test in the example
application.)
@@ -1851,7 +1852,7 @@
The second step is to make the sequencer implementation available to JBoss DNA. At
this time, the JAR containing
your new sequencer, as well as any JARs that your sequencer depends on, should be
placed on your application classpath.</para>
<note>
- <para>A future goal of JBoss DNA is to allow sequencers, connectors and other
extensions to be easily deployed into
+ <para>A future goal of JBoss DNA is to allow sequencers, connectors, and
other extensions to be easily deployed into
a runtime repository. This process will not only be much simpler, but it will
also provide JBoss DNA
with the information necessary to update configurations and create the
appropriate class loaders for each extension.
Having separate class loaders for each extension helps prevent the pollution of
the common classpath,