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,