river-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r780266 - /websites/staging/river/trunk/content/river/user-guide-basic-river-services.html
Date Wed, 08 Dec 2010 10:36:29 GMT
Author: buildbot
Date: Wed Dec  8 10:36:28 2010
New Revision: 780266

Log:
Staging update by buildbot

Modified:
    websites/staging/river/trunk/content/river/user-guide-basic-river-services.html

Modified: websites/staging/river/trunk/content/river/user-guide-basic-river-services.html
==============================================================================
--- websites/staging/river/trunk/content/river/user-guide-basic-river-services.html (original)
+++ websites/staging/river/trunk/content/river/user-guide-basic-river-services.html Wed Dec
 8 10:36:28 2010
@@ -57,41 +57,52 @@
           <div class="wiki-content">
 <h1 id="getting_started_with_river">Getting Started With River</h1>
 <p>This document is going to explain how you can use the inbuilt "simple" services
that come with River.  More specifically;</p>
-<h1 id="a_lookup_service_the_reggie_implementation">A Lookup Service (the "reggie"
implementation)</h1>
-<h1 id="a_java_space_the_outrigger_implementation">A Java Space (the "outrigger" implementation)</h1>
-<h1 id="a_transaction_service_the_mahalo_implementation">A Transaction Service (the
"mahalo" implementation)</h1>
+<ul>
+<li>A Lookup Service (the "reggie" implementation)</li>
+<li>A Java Space (the "outrigger" implementation)</li>
+<li>A Transaction Service (the "mahalo" implementation)</li>
+</ul>
 <p>The instructions assume that you're building from source as checked out from the
SVN trunk.  Currently this is necessary because the code snippets below use methods and classes
which, at time of writing, haven't made it into the latest binary release yet.  Having said
that, the code you will need in the binary release isn't to far removed from what you'll see
below, so you can progress with the binary release if you want to and are happy odifying the
code.</p>
 <p>If you are going to use the latest release then you will still need to download
(from the SVN trunk) some of the Windows BAT files mentioned below.  *nix sh scripts of those
same batch files will appear shortly.</p>
 <h2 id="environment_setup">Environment Setup</h2>
-<p>The following instructions all assume that you have checked out River to some directory
which is throughout referred to as {{$RIVER_HOME}}.  Further, you have changed directory into
{{$RIVER_HOME/examples/hello}}.</p>
-<p><em>IMPORTANT:</em> Run all scripts from the {{hello}} directory</p>
-<h1 id="change_directory_to_river_home">Change directory to $RIVER_HOME</h1>
-<h1 id="use_ant_to_build_river_ie_ant_allbuild">Use Ant to build River; I.e. {{ant
all.build}}</h1>
+<p>The following instructions all assume that you have checked out River to some directory
which is throughout referred to as <code>$RIVER_HOME</code>.  Further, you have
changed directory into <code>$RIVER_HOME/examples/hello</code>.</p>
+<blockquote>
+<p><strong>Important</strong>: Run all scripts from the <code>hello</code>
directory</p>
+</blockquote>
+<ul>
+<li>Change directory to $RIVER_HOME</li>
+<li>Use Ant to build River, i.e. <code>ant all.build</code></li>
+</ul>
 <h2 id="running_code_which_uses_river_services">Running Code Which Uses River Services</h2>
 <p>Since River uses dynamic code downloading, we need to grant various permissions
to our JVM to allow that.  In the interest of simplicity, we are going to grant everything
every permission.  In the real world, this would obviously not be recommended.</p>
 <p>To grant these permissions we need to create a policy file:</p>
-<p>{code:title=policy.all|borderStyle=solid}
-grant { 
-    permission java.security.AllPermission; 
-}; 
-{code}</p>
+<div class="codehilite"><pre><span class="n">grant</span> <span
class="p">{</span> 
+    <span class="n">permission</span> <span class="n">java</span><span
class="o">.</span><span class="n">security</span><span class="o">.</span><span
class="n">AllPermission</span><span class="p">;</span> 
+<span class="p">};</span>
+</pre></div>
+
+
 <p>Create the above file and save it somewhere that it can be easily referenced as
a command line argument to some Java you're going to write - such as the working directory
that you will run the code from.</p>
 <p>Further, your programs which will use River services will need the following JVM
arguments.</p>
-<p>{code:title=JVM Arguments|borderStyle=solid}
--Djava.security.policy=path/to/policy.all
--Djava.rmi.server.RMIClassLoaderSpi=net.jini.loader.pref.PreferredClassProvider
-{code}</p>
+<div class="codehilite"><pre><span class="o">-</span><span class="n">Djava</span><span
class="o">.</span><span class="n">security</span><span class="o">.</span><span
class="n">policy</span><span class="o">=</span><span class="n">path</span><span
class="sr">/to/</span><span class="n">policy</span><span class="o">.</span><span
class="n">all</span>
+<span class="o">-</span><span class="n">Djava</span><span class="o">.</span><span
class="n">rmi</span><span class="o">.</span><span class="n">server</span><span
class="o">.</span><span class="n">RMIClassLoaderSpi</span><span class="o">=</span><span
class="n">net</span><span class="o">.</span><span class="n">jini</span><span
class="o">.</span><span class="n">loader</span><span class="o">.</span><span
class="n">pref</span><span class="o">.</span><span class="n">PreferredClassProvider</span>
+</pre></div>
+
+
 <p>Also, before doing anything with any River code you need to set an appropriate security
manager.  This needs to be done only once per program.</p>
-<p>{code:title=Setting the Security Manager|borderStyle=solid}
-System.setSecurityManager(new RMISecurityManager());
-{code}</p>
+<div class="codehilite"><pre><span class="n">System</span><span
class="o">.</span><span class="n">setSecurityManager</span><span class="p">(</span><span
class="k">new</span> <span class="n">RMISecurityManager</span><span
class="p">());</span>
+</pre></div>
+
+
 <h2 id="starting_the_http_server">Starting the HTTP server</h2>
 <h3 id="what__wait_why_do_i_need_to_do_that">What?  Wait, why do I need to do that?</h3>
 <p>When services get marshalled for sending over the wire, the first part of their
stream is the codebase URL.  This URL tells the downloading JVM where to load the supporting
JARs from.  Often (although not always) in the River/Jini world this code base harks back
to some HTTP server.  There is a simple HTPP server packaged inside River which can be used
for this.  That's what we're going to start.</p>
 <p>See <a href="http://download.oracle.com/javase/1.5.0/docs/guide/rmi/codebase.html">3.2
How codebase is used in Java RMI</a> for more details.</p>
 <h3 id="instructions">Instructions</h3>
-<h1 id="change_to_directory_to_river_homeexampleshello">Change to directory to {{$RIVER_HOME/examples/hello/}}</h1>
-<h1 id="execute_the_script_scriptshttpdbat">Execute the script; {{scripts/httpd.bat}}</h1>
+<ul>
+<li>Change to directory to <code>$RIVER_HOME/examples/hello/</code></li>
+<li>Execute the script; <code>scripts/httpd.bat</code></li>
+</ul>
 <h3 id="testing_it">Testing it</h3>
 <p>To test that the HTTP server is running correctly use wget or your web browser on
the following URL</p>
 <ul>
@@ -102,65 +113,92 @@ System.setSecurityManager(new RMISecurit
 <p>Typically, in an environment which uses River/Jini services, a Lookup Service will
be used.  This Lookup Service is then used by your code to find River/Jini services.  Lookup
Services always know the current state of the subnet or federated space.</p>
 <p>Broadly speaking (although not 100% accurately) you need a Lookup Service in order
to be able to find other services to use.</p>
 <h2 id="instructions_1">Instructions</h2>
-<h1 id="change_directory_to_river_homeexampleshello">Change directory to $RIVER_HOME/examples/hello</h1>
-<h1 id="execute_the_script_scriptsjrmp-reggiebat">Execute the script {{scripts/jrmp-reggie.bat}}</h1>
+<ul>
+<li>Change directory to <code>$RIVER_HOME/examples/hello</code></li>
+<li>Execute the script <code>scripts/jrmp-reggie.bat</code></li>
+</ul>
 <h3 id="testing_it_1">Testing it</h3>
-<p>There are two ways to find our Lookup Service.  Remember that the interface which
fulfills the role of a Lookup Service is {{ServiceRegistrar}}.</p>
+<p>There are two ways to find our Lookup Service.  Remember that the interface which
fulfills the role of a Lookup Service is <code>ServiceRegistrar</code>.</p>
 <h4 id="unicast">Unicast</h4>
 <p>If we know where our Lookup Service is running, we can use unicast to connect straight
to it.</p>
-<p>{code:title=Unicast|borderStyle=solid}
-LookupLocator ll = new LookupLocator("jini://localhost:4160");
-StreamServiceRegistrar sr = ll.getStreamRegistrar();
-System.out.println("Service Registrar: "+sr.getServiceID());
-{code}</p>
-<p>Assuming you don't get a {{NullPointerException}} and you do get a service ID written
out, then your Lookup Service is running fine.</p>
-<p>The {{LookupLocator}} takes a String representing a "jini URL".  This jini URL is
made up from the Strings "{{jini://}}" a hostname and (optionally) "{{:}}" and a port number.
 4160 is the default port and is specified in the Lookup Service configuration file.  The
scripts in the {{examples/hello}} directory will use the default port unless you have changed
it.  See <a href="http://incubator.apache.org/river/doc/specs/html/discovery-spec.html">DJ.5.5
Address and Port Mappings for TCP and Multicast UDP</a> for more details.</p>
+<div class="codehilite"><pre><span class="n">LookupLocator</span>
<span class="n">ll</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">LookupLocator</span><span class="p">(</span><span
class="s">&quot;jini://localhost:4160&quot;</span><span class="p">);</span>
+<span class="n">StreamServiceRegistrar</span> <span class="n">sr</span>
<span class="o">=</span> <span class="n">ll</span><span class="o">.</span><span
class="n">getStreamRegistrar</span><span class="p">();</span>
+<span class="n">System</span><span class="o">.</span><span class="n">out</span><span
class="o">.</span><span class="n">println</span><span class="p">(</span><span
class="s">&quot;Service Registrar: &quot;</span><span class="o">+</span><span
class="n">sr</span><span class="o">.</span><span class="n">getServiceID</span><span
class="p">());</span>
+</pre></div>
+
+
+<p>Assuming you don't get a <code>NullPointerException</code> and you do
get a service ID written out, then your Lookup Service is running fine.</p>
+<p>The <code>LookupLocator</code> takes a String representing a "jini URL".
 This jini URL is made up from the Strings "<code>jini://</code>" a hostname and
(optionally) "<code>:</code>" and a port number.  4160 is the default port and
is specified in the Lookup Service configuration file.  The scripts in the {{examples/hello}}
directory will use the default port unless you have changed it.  See <a href="http://incubator.apache.org/river/doc/specs/html/discovery-spec.html">DJ.5.5
Address and Port Mappings for TCP and Multicast UDP</a> for more details.</p>
 <h4 id="multicast">Multicast</h4>
 <p>If we know only that "some lookup services are on the subnet somewhere" then we
can use multicast to find them.</p>
-<p>{code:title=Multicast|borderStyle=solid}
-DiscoveryListenerManagement dlm = new LookupDiscovery(LookupDiscovery.ALL_GROUPS);</p>
-<p>LeaseRenewalManager lrm = new LeaseRenewalManager();
-ServiceDiscoveryManager sdm = new ServiceDiscoveryManager(dlm, lrm);</p>
-<p>Thread.sleep(500); //need to wait a little bit for the Lookup Service to generate
the events to the sdm</p>
-<p>ServiceTemplate srTemplate = new ServiceTemplate(null, new Class[] { ServiceRegistrar.class
}, null);</p>
-<p>ServiceItem[] sis = sdm.lookup(srTemplate, 10, null);
-for(ServiceItem si : sis) {
-    System.out.println("Service Registrar: "+si.serviceID);
-}</p>
-<p>dlm.terminate();
-{code}</p>
-<p>This approach is slightly different.  It is relying the {{ServiceDiscoveryManager}}
to listen to the UDP multicast packets announcing the presence of a Lookup Service.  The same
rules apply as for unicast on deciding whether or not your Lookup Service is running.</p>
-<p>This approach can be modified if you know which hosts on the subnet <em>might</em>
be running lookup services.  You can define and pass this list to the {{LookupDiscovery}}
constructor.</p>
+<div class="codehilite"><pre><span class="n">DiscoveryListenerManagement</span>
<span class="n">dlm</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">LookupDiscovery</span><span class="p">(</span><span
class="n">LookupDiscovery</span><span class="o">.</span><span class="n">ALL_GROUPS</span><span
class="p">);</span>
+
+<span class="n">LeaseRenewalManager</span> <span class="n">lrm</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">LeaseRenewalManager</span><span
class="p">();</span>
+<span class="n">ServiceDiscoveryManager</span> <span class="n">sdm</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">ServiceDiscoveryManager</span><span
class="p">(</span><span class="n">dlm</span><span class="p">,</span>
<span class="n">lrm</span><span class="p">);</span>
+
+<span class="n">Thread</span><span class="o">.</span><span class="nb">sleep</span><span
class="p">(</span><span class="mi">500</span><span class="p">);</span>
<span class="sr">//</span><span class="n">need</span> <span class="n">to</span>
<span class="nb">wait</span> <span class="n">a</span> <span class="n">little</span>
<span class="n">bit</span> <span class="k">for</span> <span class="n">the</span>
<span class="n">Lookup</span> <span class="n">Service</span> <span
class="n">to</span> <span class="n">generate</span> <span class="n">the</span>
<span class="n">events</span> <span class="n">to</span> <span class="n">the</span>
<span class="n">sdm</span>
+
+<span class="n">ServiceTemplate</span> <span class="n">srTemplate</span>
<span class="o">=</span> <span class="k">new</span> <span class="n">ServiceTemplate</span><span
class="p">(</span><span class="n">null</span><span class="p">,</span>
<span class="k">new</span> <span class="n">Class</span><span class="o">[]</span>
<span class="p">{</span> <span class="n">ServiceRegistrar</span><span
class="o">.</span><span class="n">class</span> <span class="p">},</span>
<span class="n">null</span><span class="p">);</span>
+
+<span class="n">ServiceItem</span><span class="o">[]</span> <span
class="n">sis</span> <span class="o">=</span> <span class="n">sdm</span><span
class="o">.</span><span class="n">lookup</span><span class="p">(</span><span
class="n">srTemplate</span><span class="p">,</span> <span class="mi">10</span><span
class="p">,</span> <span class="n">null</span><span class="p">);</span>
+<span class="k">for</span><span class="p">(</span><span class="n">ServiceItem</span>
<span class="n">si</span> <span class="p">:</span> <span class="n">sis</span><span
class="p">)</span> <span class="p">{</span>
+    <span class="n">System</span><span class="o">.</span><span
class="n">out</span><span class="o">.</span><span class="n">println</span><span
class="p">(</span><span class="s">&quot;Service Registrar: &quot;</span><span
class="o">+</span><span class="n">si</span><span class="o">.</span><span
class="n">serviceID</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="n">dlm</span><span class="o">.</span><span class="n">terminate</span><span
class="p">();</span>
+</pre></div>
+
+
+<p>This approach is slightly different.  It is relying the <code>ServiceDiscoveryManager</code>
to listen to the UDP multicast packets announcing the presence of a Lookup Service.  The same
rules apply as for unicast on deciding whether or not your Lookup Service is running.</p>
+<p>This approach can be modified if you know which hosts on the subnet <em>might</em>
be running lookup services.  You can define and pass this list to the <code>LookupDiscovery</code>
constructor.</p>
 <h2 id="starting_a_java_space">Starting a Java Space</h2>
 <h3 id="what__wait_why_do_i_need_to_do_that_2">What?  Wait, why do I need to do that?</h3>
 <p>Finding a Lookup Service is only useful if there are some other services on the
network which you want to use, so now we're going to start a Java Space, and find that.  Using
the Java Space is outside the scope of this document, although the "how" is relativily straight
forward.</p>
 <h3 id="instructions_2">Instructions</h3>
-<h1 id="change_directory_to_river_homeexampleshello_1">Change directory to $RIVER_HOME/examples/hello</h1>
-<h1 id="execute_the_script_scriptsjrmp-outrigger-groupbat">Execute the script {{scripts/jrmp-outrigger-group.bat}}</h1>
+<ul>
+<li>Change directory to <code>$RIVER_HOME/examples/hello</code></li>
+<li>Execute the script <code>scripts/jrmp-outrigger-group.bat</code></li>
+</ul>
 <h3 id="testing_it_2">Testing it</h3>
-<p>{code:title=Finding A Javaspace with a ServiceRegistrar](borderStyle=solid}
-ServiceTemplate template = new ServiceTemplate(null, new Class[) { JavaSpace.class }, new
Entry<a href="0.html">0</a>);</p>
-<p>ServiceMatches sms = sr.lookup(template, 10);
-for(ServiceItem si : sms.items) {
-    System.out.println("Found: "+si);
-}
-{code}</p>
-<p>{code:title=Finding A Javaspace with a ServiceDiscoveryManager](borderStyle=solid}
-ServiceItem si = sdm.lookup(template, null);
-System.out.println("Java Space: "+(JavaSpace)si.service);
-{code}</p>
-<p>As before, a lack of {{NullPointerException}} and not having {{null}} printed out
will indicate that you have found a running Java Space.</p>
+<p>To find any kind of service we must first create a template.  This is an instance
of <code>ServiceTemplate</code> which describes the kind of thing we're looking
for.  As the Jini specification says, nulls and empty arrays as wildcard characters for "any
value".  So the following code is a template which will match any service which implements
the <code>JavaSapce</code> interface regardless of the rest of it's characteristics.</p>
+<div class="codehilite"><pre><span class="n">ServiceTemplate</span>
<span class="n">template</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">ServiceTemplate</span><span class="p">(</span><span
class="n">null</span><span class="p">,</span> <span class="k">new</span>
<span class="n">Class</span><span class="p">[)</span> <span class="p">{</span>
<span class="n">JavaSpace</span><span class="o">.</span><span class="n">class</span>
<span class="p">},</span> <span class="k">new</span> <span class="n">Entry</span><span
class="p">[</span><span class="mi">0</span><span class="p">]());</span>
+</pre></div>
+
+
+<p>Using the unicast and a <code>ServiceRegistrar</code> we find the Java
Space like this;</p>
+<div class="codehilite"><pre><span class="n">ServiceMatches</span>
<span class="n">sms</span> <span class="o">=</span> <span class="n">sr</span><span
class="o">.</span><span class="n">lookup</span><span class="p">(</span><span
class="n">template</span><span class="p">,</span> <span class="mi">10</span><span
class="p">);</span>
+<span class="k">if</span><span class="p">(</span><span class="mi">0</span>
<span class="o">&lt;</span> <span class="n">sms</span><span
class="o">.</span><span class="n">items</span><span class="o">.</span><span
class="nb">length</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">JavaSpace</span> <span class="n">space</span>
<span class="o">=</span> <span class="p">(</span><span class="n">JavaSpace</span><span
class="p">)</span> <span class="n">sms</span><span class="o">.</span><span
class="n">items</span><span class="p">[</span><span class="mi">0</span><span
class="p">]</span><span class="o">.</span><span class="n">service</span><span
class="p">;</span>
+    <span class="sr">//</span> <span class="k">do</span> <span
class="n">something</span> <span class="n">with</span> <span class="n">the</span>
<span class="n">space</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+    <span class="n">System</span><span class="o">.</span><span
class="n">out</span><span class="o">.</span><span class="n">println</span><span
class="p">(</span><span class="s">&quot;No Java Space found.&quot;</span><span
class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Using the <code>ServiceDiscoveryManager</code> is similar;</p>
+<div class="codehilite"><pre><span class="n">ServiceItem</span> <span
class="n">si</span> <span class="o">=</span> <span class="n">sdm</span><span
class="o">.</span><span class="n">lookup</span><span class="p">(</span><span
class="n">template</span><span class="p">,</span> <span class="n">null</span><span
class="p">);</span>
+<span class="k">if</span><span class="p">(</span><span class="n">null</span>
<span class="o">!=</span> <span class="n">si</span><span class="p">)</span>
<span class="p">{</span>
+    <span class="n">JavaSpace</span> <span class="n">space</span>
<span class="o">=</span> <span class="p">(</span><span class="n">JavaSpace</span><span
class="p">)</span> <span class="n">sms</span><span class="o">.</span><span
class="n">service</span><span class="p">;</span>
+    <span class="sr">//</span> <span class="k">do</span> <span
class="n">something</span> <span class="n">with</span> <span class="n">the</span>
<span class="n">space</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+    <span class="n">System</span><span class="o">.</span><span
class="n">out</span><span class="o">.</span><span class="n">println</span><span
class="p">(</span><span class="s">&quot;No Java Space found.&quot;</span><span
class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
 <h2 id="starting_a_transaction_service">Starting a Transaction Service</h2>
 <h3 id="what__wait_why_do_i_need_to_do_that_3">What?  Wait, why do I need to do that?</h3>
 <p>Because you'd like to find something that will give you a nice distributed transaction.</p>
 <h3 id="instructions_3">Instructions</h3>
-<h1 id="change_directory_to_river_homeexampleshello_2">Change directory to $RIVER_HOME/examples/hello</h1>
-<h1 id="execute_the_script_scriptsjrmp-mahalo-groupbat">Execute the script {{scripts/jrmp-mahalo-group.bat}}</h1>
+<ul>
+<li>Change directory to <code>$RIVER_HOME/examples/hello</code></li>
+<li>Execute the script <code>scripts/jrmp-mahalo-group.bat</code></li>
+</ul>
 <h3 id="testing_it_3">Testing it</h3>
-<p>Testing it is done in the same way as for the Java Space.  However, the constructor
of the {{ServiceTemplate}} changes.</p>
-<p>{code:title=Transaction Manager ServiceTemplate|borderStyle=solid}
-ServiceTemplate template = new ServiceTemplate(null, new Class[) { TransactionManager.class
}, new Entry<a href="0.html">0</a>);
-{code}</p>
+<p>Testing it is done in the same way as for the Java Space.  However, the constructor
of the <code>ServiceTemplate</code> changes.</p>
+<div class="codehilite"><pre><span class="n">ServiceTemplate</span>
<span class="n">template</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">ServiceTemplate</span><span class="p">(</span><span
class="n">null</span><span class="p">,</span> <span class="k">new</span>
<span class="n">Class</span><span class="p">[)</span> <span class="p">{</span>
<span class="n">TransactionManager</span><span class="o">.</span><span
class="n">class</span> <span class="p">},</span> <span class="k">new</span>
<span class="n">Entry</span><span class="p">[</span><span class="mi">0</span><span
class="p">](</span><span class="mi">0</span><span class="o">.</span><span
class="n">html</span><span class="p">));</span>
+</pre></div>
           </div>
         </td>
         <td valign="top">



Mime
View raw message