river-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r813661 - in /websites/staging/river/trunk/content: ./ helloworld.html
Date Thu, 19 Apr 2012 15:17:47 GMT
Author: buildbot
Date: Thu Apr 19 15:17:47 2012
New Revision: 813661

Staging update by buildbot for river

    websites/staging/river/trunk/content/   (props changed)

Propchange: websites/staging/river/trunk/content/
--- cms:source-revision (original)
+++ cms:source-revision Thu Apr 19 15:17:47 2012
@@ -1 +1 @@

Modified: websites/staging/river/trunk/content/helloworld.html
--- websites/staging/river/trunk/content/helloworld.html (original)
+++ websites/staging/river/trunk/content/helloworld.html Thu Apr 19 15:17:47 2012
@@ -66,7 +66,100 @@
         <td style="overflow: hidden;" valign="top" width="100%">
           <div class="wiki-content">
-<p>Hello World with River</p>
+<h1 id="hello-world-with-river">Hello World With River</h1>
+Warning!  The following describes how to use code which is currently only contained in a
branch of River and has not been formally released yet.</p>
+<h2 id="introduction">Introduction</h2>
+<p>It can be argued that part of the barrier to entry of getting working River services
is the complexity and difficulty with configuring services.  The are many things that users,
new and old, must remember when trying to set up new environments and tweak the configurations
of their services.</p>
+<p>The configurations themselves can be tempermental and difficult for new comers to
get to grips with.  Largely, they are text files with a Java-esque content which is parsed
by the <font face="Courier">ServiceStarter</font>.  The following describes how
to use the "extra" bits of River to get around these issues.</p>
+<h2 id="extra-river">Extra River</h2>
+<p>The classes required in this documentation live outside of the main River distribution,
in fact they are not part of the core of the library neither are they part of the Jini and
JavaSpaces specifications. In a standard River install, they are therefore completely optional.</p>
+<h2 id="getting-started">Getting Started</h2>
+<h3 id="prerequisites">Prerequisites</h3>
+<p>River Extras require the following additional JARs on their runtime classpath.</p>
+<li>Apache Commons Collections 3.2</li>
+<li>Apache Commons Lang 2.6</li>
+<p>From now on, this document will refer to these two exact file system locatino of
these JARs as;</p>
+<h3 id="getting-the-code-and-building-river">Getting the Code and Building River</h3>
+<p>You must first get the River source.  Since this code is still experimental, that
means checking out the code from a trunk.  Ideally, this code will make the next release and
so will come packaged as part of the River (source) distribution.</p>
+$  cd ~/projects/river
+$  svn co http://svn.apache.org/repos/asf/river/jtsk/skunk/easystart helloworld
+$  cd helloworld
+$  ant # This will build the River distribution, including the lib/extra.jar
+<p>Optionally, you can also;
+$  cd ../src-extra-examples
+$  ant # This will build the lib/extra-examples.jar
+<p>From this point on, we shall refer to the installation of River as <code>${RIVER_HOME}</code>.
 In this example, it would refer to directory ~/projects/river/helloworld.</p>
+<h3 id="starting-the-http-server">Starting the HTTP Server</h3>
+<p>Jini/River services of course require a HTTP server.  This is easily started in
such a way as it will serve all the JAR files from the ${RIVER_HOME}/lib directory.</p>
+<p>Open your IDE of choice, fix any build/setup errors and then setup a run configuration
for the HTTP server - I use Eclipse, hence the terminology.</p>
+<p>The main class to run is, <code>org.apache.river.extra.examples.easystart.riverservices.StartHttpServer</code>
and can be found in the <code>${RIVER_HOME}/src-extra-examples</code> source directory.
 It will need the following program arguments; </p>
+<p>Obviously, the first argument is the value of <code>${RIVER_HOME}</code>
and the second is the HTTP port to use.  This is the default port according to River Extras,
if you want to use a different port then this will require changes (in Java code) of the configuration.</p>
+<p>Execute this run configuration and leave it running.  You can verify that it's working
correctly by using your browser or <code>wget</code> to download a sample JAR,
+<p><code>$  wget http://localhost:8080/reggie.jar</code></p>
+<p>The rest of this document describes code that can be found in the <code>src-extra</code>
and <code>src-extra-examples</code> source directories.</p>
+<h3 id="common-service-configuration-options">Common Service Configuration Options</h3>
+<p>We are going to use a <code>ApplicationOptions</code> to describe certain
service configuration options that will be common to all the services we're going to start.
 From, <code>org.apache.river.extra.examples.easystart.StartServices</code>;</p>
+ApplicationOptions options = new ApplicationOptions();<br/>
+options.setHttpOptions("localhost", 8080, true);<br/>
+<p>So you can see we are using the non-default Jini port (4162).  We are also setting
the configuration package name of our services to some constant as defined in <code>ExampleService.PACKAGE</code>.</p>
+<p>We shall describe <code>ExampleService</code> later.</p>
+<p>Next we need a factory to build our configuration objects;</p>
+ApplicationConfigurationFactory configFac = new ApplicationConfigurationFactory(options);
+<p>This class extends a non-example River Extra class, <code>org.apache.river.extra.easystart.config.ConfigurationFactory</code>.
 This base class knows how to create configuration objects for the standard River services
using the djinn specific options as we have described above, the extending class also knows
how to create configuration objects for our additional custom services.</p>
+<h3 id="starting-the-lookup-service">Starting the Lookup Service</h3>
+<p>Staying with the same <code>StartServices</code> class from above.</p>
+<p>First we need to config the lookup service and then we can start it.  This is easily
+LookupServiceConfiguration lusConfig = configFac.lookupServiceConfig();<br/>
+<p>Notice that we have set the lookup service's configuration's member groups to be
the same as the lookup groups as defined in the <code>ApplicationOptions</code>
instance above.</p>
+<p>We now have a started lookup service.</p>
+<h3 id="starting-the-example-service">Starting the Example Service</h3>
+<p>Next we need a configuration for our example service.</p>
+<p>The configuration is described in our extended <code>ApplicationConfigurationFactory</code>,
+public AbstractEasyConfiguration exampleService(Name name) {<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;ApplicationOptions exampleOptions = getDefaultOptions();<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;return new AbstractEasyConfiguration(exampleOptions)
+<p>Now we know how the configuration was done.  You should also be able to see how
easy it will be to extend this concept of ConfigurationFactory to handle all of your own custom
services that make up your own applications.</p>
+<p>We can start the example service in exactly the same way as we did the lookup service
+AbstractEasyConfiguration config = configFac.exampleService(new Name("Jeff"));
+<p>Now we have successfully configured and started our example service, and in all
of this we did not have to bother ourselves with any configuration file.</p>
+<p>It should be pointed out that the services we have started are using the default
policy file which is unsuitable for a live environment, since it is a "grant all" policy file
that can be found in <code>${RIVER_HOME}/src-extra/policy.all</code></p>
+<h2 id="additional-configuration">Additional Configuration</h2>
+<p>You can specify additional configuration data by creating custom <code>org.apache.river.extra.easystart.config.settings.Setting</code>
objects and adding them to the <code>org.apache.river.extra.easystart.config.ApplicationOptions</code>
instance before creating your configuration factory.  In the same package, there are additional
extending classes of <code>Setting</code> that can be used as templates for your
own configuration options.</p>
         <td valign="top">

View raw message