Author: thobbs
Date: Mon Apr 23 13:42:45 2012
New Revision: 1329233
URL: http://svn.apache.org/viewvc?rev=1329233&view=rev
Log:
Corrected some typos and added a bit more detail
Modified:
river/site/trunk/content/helloworld.mdtext
Modified: river/site/trunk/content/helloworld.mdtext
URL:
http://svn.apache.org/viewvc/river/site/trunk/content/helloworld.mdtext?rev=1329233&r1=1329232&r2=1329233&view=diff
==============================================================================
--- river/site/trunk/content/helloworld.mdtext (original)
+++ river/site/trunk/content/helloworld.mdtext Mon Apr 23 13:42:45 2012
@@ -24,7 +24,7 @@ Warning! The following describes how to
## Introduction
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.
-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.
+The configurations themselves can be temperamental 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 <code>ServiceStarter</code>. The other problem
with the config files is ensuring that you can share configuration for certain
services across the djinn. Encapsulating configuration in Java code, which can
be more easily humanly read, verified and shared is possibly a better idea than
having many slightly different copies of configuration files which must then be
kept in step. The following describes how to use the "extra" bits of River to
get around these issues.
## Extra River
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.
@@ -38,29 +38,29 @@ River Extras require the following addit
* Apache Commons Collections 3.2
* Apache Commons Lang 2.6
-From now on, this document will refer to these two exact file system locatino
of these JARs as;
+From now on, this document will refer to these two exact file system location
of these JARs as;
- * <pre>${COMMONS_COLLECTIONS_JAR}</pre>
- * <pre>${COMMONS_LANG_JAR}</pre>
+ * <code>${COMMONS_COLLECTIONS_JAR}</code>
+ * <code>${COMMONS_LANG_JAR}</code>
### Getting the Code and Building River
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.
-<pre>
+<pre><code>
$ 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
-</pre>
+</code></pre>
Optionally, you can also;
-<pre>
+<pre><code>
$ cd ../src-extra-examples
$ ant # This will build the lib/extra-examples.jar
-</pre>
+</code></pre>
-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.
+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
<code>~/projects/river/helloworld</code>.
### Starting the HTTP Server
@@ -81,6 +81,18 @@ Execute this run configuration and leave
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.
+### Running Services
+
+When running River services you will also require the following VM arguments.
+
+<pre><code>
+-Djava.security.policy=<em>${RIVER_HOME}</em>/src-extra/policy.all
+-Djava.rmi.server.RMIClassLoaderSpi=net.jini.loader.pref.PreferredClassProvider
+-DRIVER_HOME=<em>${RIVER_HOME}</em>
+</code></pre>
+
+<b>Important</b>: The policy file specified above is a "grant all" policy
file. You could consider it a "disable security" security policy. As such it
is unsuitable for real-world use.
+
### Common Service Configuration Options
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>;
@@ -103,23 +115,23 @@ Next we need a factory to build our conf
ApplicationConfigurationFactory configFac = new
ApplicationConfigurationFactory(options);
</code>
-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.
+This class extends a 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.
### Starting the Lookup Service
Staying with the same <code>StartServices</code> class from above.
-First we need to config the lookup service and then we can start it. This is
easily done;
+First we need to configure the lookup service and then we can start it. This
is easily done;
-<code>
-LookupServiceConfiguration lusConfig = configFac.lookupServiceConfig();<br/>
-lusConfig.addMemberGroup("extra").addMemberGroup("extra");<br/>
-ServiceStarter.main(lusConfig.riverConfig());<br/>
-</code>
+<pre><code>
+LookupServiceConfiguration lusConfig = configFac.lookupServiceConfig();
+lusConfig.addMemberGroup("extra").addMemberGroup("example");
+ServiceStarter.main(lusConfig.riverConfig());
+</code></pre>
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.
-We now have a started lookup service.
+We now have a started lookup service; (but check your console for errors!)
### Starting the Example Service
@@ -127,14 +139,14 @@ Next we need a configuration for our exa
The configuration is described in our extended
<code>ApplicationConfigurationFactory</code>, thus;
-<code>
-public AbstractEasyConfiguration exampleService(Name name) {<br/>
- ApplicationOptions exampleOptions =
getDefaultOptions();<br/>
- exampleOptions.setImplementationClass(ExampleServiceImpl.class);<br/>
- exampleOptions.addInitialLookupAttribute(name);<br/>
- return new AbstractEasyConfiguration(exampleOptions)
{};<br/>
+<pre><code>
+public AbstractEasyConfiguration exampleService(Name name) {
+ ApplicationOptions exampleOptions =
getDefaultOptions();
+ exampleOptions.setImplementationClass(ExampleServiceImpl.class);
+ exampleOptions.addInitialLookupAttribute(name);
+ return new AbstractEasyConfiguration(exampleOptions)
{};
}
-</code>
+</code></pre>
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.
@@ -148,6 +160,8 @@ ServiceStarter.main(config.riverConfig()
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.
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>
+
+So by defining and sharing our own implementation of the configuration factory
we can be sure that all services started with configurations from that factory
will be configured accordingly. What's more, we no longer have to maintain
series of configuration files which potential contain many duplicate data items.
## Additional Configuration
