river-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From gtra...@apache.org
Subject svn commit: r1657985 - in /river/river-examples/river-examples/trunk: ./ src/site/markdown/ src/site/markdown/browser/ src/site/markdown/hello-client/ src/site/markdown/hello-service/ src/site/markdown/infrastructure/ src/site/resources/hello-client/
Date Fri, 06 Feb 2015 22:55:01 GMT
Author: gtrasuk
Date: Fri Feb  6 22:55:01 2015
New Revision: 1657985

URL: http://svn.apache.org/r1657985
Log:
The set of examples is complete, including the client.  To use the project, follow the instructions
starting in README.md.

Added:
    river/river-examples/river-examples/trunk/README.md
    river/river-examples/river-examples/trunk/src/site/markdown/hello-client/
    river/river-examples/river-examples/trunk/src/site/markdown/hello-client/hello-client.md
    river/river-examples/river-examples/trunk/src/site/resources/hello-client/
    river/river-examples/river-examples/trunk/src/site/resources/hello-client/Client-run.png
  (with props)
Modified:
    river/river-examples/river-examples/trunk/pom.xml
    river/river-examples/river-examples/trunk/src/site/markdown/browser/browser.md
    river/river-examples/river-examples/trunk/src/site/markdown/hello-service/hello-service.md
    river/river-examples/river-examples/trunk/src/site/markdown/index.md
    river/river-examples/river-examples/trunk/src/site/markdown/infrastructure/infrastructure.md

Added: river/river-examples/river-examples/trunk/README.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/README.md?rev=1657985&view=auto
==============================================================================
--- river/river-examples/river-examples/trunk/README.md (added)
+++ river/river-examples/river-examples/trunk/README.md Fri Feb  6 22:55:01 2015
@@ -0,0 +1,43 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+Apache River Examples - README
+=====================
+
+This project contains a set of examples that show how to use Apache River.
+
+## Building the examples
+
+The project uses Apache Maven to manage the dependencies and build the examples.
+There is no need to download and build the main River distribution or tools;
+the River artifacts are deployed to Maven Central, so Maven will automatically
+download the binary artifacts as needed for the examples build.
+
+You'll need Apache Maven installed.  See [Apache Maven](http://maven.apache.org).
+
+To build the examples, simply unpack the source distribution of 'river-examples',
+and then,
+
+    cd river-examples
+    mvn install
+    mvn site
+
+Once the site is built, please read the project documentation at 
+[target/site/index.html](target/site/index.html).
+

Modified: river/river-examples/river-examples/trunk/pom.xml
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/pom.xml?rev=1657985&r1=1657984&r2=1657985&view=diff
==============================================================================
--- river/river-examples/river-examples/trunk/pom.xml (original)
+++ river/river-examples/river-examples/trunk/pom.xml Fri Feb  6 22:55:01 2015
@@ -129,5 +129,6 @@
     <module>home</module>
     <module>hello-api</module>
     <module>hello-service</module>
+    <module>hello-client</module>
   </modules>
 </project>
\ No newline at end of file

Modified: river/river-examples/river-examples/trunk/src/site/markdown/browser/browser.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/markdown/browser/browser.md?rev=1657985&r1=1657984&r2=1657985&view=diff
==============================================================================
--- river/river-examples/river-examples/trunk/src/site/markdown/browser/browser.md (original)
+++ river/river-examples/river-examples/trunk/src/site/markdown/browser/browser.md Fri Feb
 6 22:55:01 2015
@@ -63,7 +63,9 @@ object.
 
 * Speaking of the codebase annotation, the bytecode for a proxy has to be downloadable
 from somewhere.  This could certainly be a standard web server like Tomcat, but it 
-does need to be setup.  And the codebase annotation has to point to it.
+does need to be setup.  And the codebase annotation has to point to it. And in general, we
have
+to enable code downloading by setting the system property "java.rmi.server.useCodebaseOnly"
+to "false".
 
 It is (barely) possible to configure a JRE and setup the policy files using command-line
 options to the JDK, but there's an easier way: The ServiceStarter container.
@@ -71,7 +73,7 @@ options to the JDK, but there's an easie
 So the way that we "run" the service browser is to run the ServiceStarter container with

 a setup file that instructs it how to run the browser program that we're really interested
in.
 
-    java -Djava.security.manager -Djava.security.policy=server.policy -jar lib/start.jar
start-browser.config
+    java -Djava.security.manager -Djava.security.policy=server.policy -Djava.rmi.server.useCodebaseOnly=false
-jar lib/start.jar start-browser.config
 
 If all is well, you should see the Service Browser start up, with a window that looks like
this:
 

Added: river/river-examples/river-examples/trunk/src/site/markdown/hello-client/hello-client.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/markdown/hello-client/hello-client.md?rev=1657985&view=auto
==============================================================================
--- river/river-examples/river-examples/trunk/src/site/markdown/hello-client/hello-client.md
(added)
+++ river/river-examples/river-examples/trunk/src/site/markdown/hello-client/hello-client.md
Fri Feb  6 22:55:01 2015
@@ -0,0 +1,146 @@
+# The Hello Client
+
+Finally, we are ready to code a service consumer, also known as a client.
+
+To summarize, so far, we've done the following:
+
+- Started a service browser so we can see what's on the network in our djinn.  
+- Started up a service registrar.  
+- Started up a "hello-world" service.  
+
+By now, the pattern should be coming clear - we run Jini components inside a 
+container that is setup by the "service starter" framework.  This container handles
+the details of setting up the class loaders and the dynamic security policy provider.
+We configure this container with a "start-xyz.config" file.  The component itself
+loads up its configuration from a "xyz.config" file.
+
+So let's finish it off by looking at the client.  The code part is in the module
+"hello-client" inside the examples project.  The main code is in the class
+"org.apache.river.examples.hello.client.App":
+
+    public class App {
+
+        private static final String MODULE=App.class.getPackage().getName();
+
+        public App(final String[] args, LifeCycle lc) {
+            main(args);
+        }
+
+        public static synchronized void main(String[] args) {
+            try {
+                // Get the config
+                Configuration config = ConfigurationProvider.getInstance(args);
+                // From the config, get the ServiceDiscoveryManager
+                ServiceDiscoveryManager sdm=
+                        (ServiceDiscoveryManager) 
+                        config.getEntry(MODULE, "sdm", ServiceDiscoveryManager.class);
+                // We'll also need a proxy preparer.
+                ProxyPreparer preparer=(ProxyPreparer) config.getEntry(MODULE, 
+                        "greeterPreparer", ProxyPreparer.class);
+                // While the sdm is finding registrars, let's ask the user for their
+                // name.
+                Scanner in = new Scanner(System.in);
+                System.out.println("Please enter your name:");
+                String name = in.nextLine();
+                // Query the sdm for Greeter services.
+                ServiceTemplate template=new ServiceTemplate(
+                        null,
+                        new Class[] { Greeter.class },
+                        new Entry[0]
+                );
+                ServiceItem[] serviceItems=sdm.lookup(template, 5, null);
+                if (serviceItems.length==0) {
+                    System.out.println("We didn't find any greeter services.");
+                    System.exit(0);
+                }
+                // Pick a service item
+                ServiceItem chosen=serviceItems[0];
+                // Prepare the proxy.
+                Greeter greeter=(Greeter) preparer.prepareProxy(chosen.service);
+                // Make the call
+                String message=greeter.sayHello(name);
+                // Print the result
+                System.out.println("Greeter replied '" + message + "'.");
+            } catch (Exception ex) {
+                ex.printStackTrace();
+            } finally {
+                System.exit(0);
+            }
+        }
+    }
+
+The only thing that looks a little funny is that we call the main(...) method
+from the constructor.  This quirk is because of the way the ServiceStarter works, by 
+instantiating the object.
+
+Apart from that, we can see the usual pattern of getting a Configuration object based
+on the command-line parameters, and pulling entries out of the configuration.  In this case,
+the program shows the basic pattern for using a service:
+
+1 - Get a ServiceDiscoveryManager from the configuration.  Inside the configuration, the
+ServiceDiscoveryManager is configured to use a LookupDiscoveryManager to find all the service

+registrars that appear on the network.  
+2 - Use the ServiceDiscoveryManager to look up the service itself.  Note that we lookup the
+service by its interface, as defined in the API module.  
+3 - Select a proxy (in this case, we simply use the first one we find), and prepare it
+using a ProxyPreparer.  
+4 - Invoke methods on the proxy, which in turn communicates with the real service.
+
+The configuration for the client is as follows:
+
+    org.apache.river.examples.hello.client {
+
+        discoveryGroup="example-group";
+
+        groups = new String[] {discoveryGroup};
+
+        exporter = new BasicJeriExporter(TcpServerEndpoint.getInstance(0),
+                                         new BasicILFactory());
+
+        serviceInvocationConstraints=InvocationConstraints.EMPTY;
+
+        basicPreparer = 
+            new BasicProxyPreparer(false, new BasicMethodConstraints(serviceInvocationConstraints),
+                new Permission[] { new RuntimePermission("accessClassInPackage.com.sun.proxy")
} );
+
+        static discoveryManager = 
+            new LookupDiscovery( groups, this);
+
+        greeterPreparer = basicPreparer;
+        registrarPreparer = basicPreparer;
+
+        static sdm = new ServiceDiscoveryManager(discoveryManager, null);
+
+    }
+
+And the 'starter' configuration is:
+
+    com.sun.jini.start {
+
+        private static policy = "server.policy";
+        private static classpath = "lib${/}hello-api.jar:lib${/}hello-client.jar";
+        private static config = "hello-client.config";
+        private static codebase="";
+
+        static serviceDescriptors = new ServiceDescriptor[] {
+            new NonActivatableServiceDescriptor(
+                codebase, policy, classpath,
+                "org.apache.river.examples.hello.client.App",
+                new String[] { config })
+        };
+
+    }//com.sun.jini.start
+
+Finally, run the client:
+
+    java -Djava.security.manager -Djava.security.policy=server.policy -Djava.rmi.server.useCodebaseOnly=false
-jar lib/start.jar start-hello-client.config
+
+The client will ask you to enter your name on the command line, and then call the
+service's 'sayHello(..)' method, and print out the results.
+
+![Running the client](Client-run.png)
+
+Now, for extra points, copy the 'home' binary to another machine that has Java 
+installed, and run the client.  You should see that it still works, with no real
+configuration other than the name of the discovery group.
+

Modified: river/river-examples/river-examples/trunk/src/site/markdown/hello-service/hello-service.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/markdown/hello-service/hello-service.md?rev=1657985&r1=1657984&r2=1657985&view=diff
==============================================================================
--- river/river-examples/river-examples/trunk/src/site/markdown/hello-service/hello-service.md
(original)
+++ river/river-examples/river-examples/trunk/src/site/markdown/hello-service/hello-service.md
Fri Feb  6 22:55:01 2015
@@ -283,7 +283,7 @@ that's built by the 'home' module:
 
 and then execute the service-starter with the required configuration file:
 
-    java -Djava.security.manager -Djava.security.policy=server.policy -jar lib/start.jar
start-hello-service.config
+    java -Djava.security.manager -Djava.security.policy=server.policy -Djava.rmi.server.useCodebaseOnly=false
-jar lib/start.jar start-hello-service.config
 
 You should see the service start up:  
 ![Hello service start-up](hello-service-cmd.png)

Modified: river/river-examples/river-examples/trunk/src/site/markdown/index.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/markdown/index.md?rev=1657985&r1=1657984&r2=1657985&view=diff
==============================================================================
--- river/river-examples/river-examples/trunk/src/site/markdown/index.md (original)
+++ river/river-examples/river-examples/trunk/src/site/markdown/index.md Fri Feb  6 22:55:01
2015
@@ -77,3 +77,8 @@ Application Programming Interface...
 
 [Read More...](hello-service/hello-service.html)
 
+## The Hello Client
+
+Finally, we are ready to code a service consumer, also known as a client.
+
+[Read More...](hello-client/hello-client.html)

Modified: river/river-examples/river-examples/trunk/src/site/markdown/infrastructure/infrastructure.md
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/markdown/infrastructure/infrastructure.md?rev=1657985&r1=1657984&r2=1657985&view=diff
==============================================================================
--- river/river-examples/river-examples/trunk/src/site/markdown/infrastructure/infrastructure.md
(original)
+++ river/river-examples/river-examples/trunk/src/site/markdown/infrastructure/infrastructure.md
Fri Feb  6 22:55:01 2015
@@ -23,7 +23,7 @@ single point of failure.
 In any case, in order to show a simple client and service, we'll need a service registrar.
 There's another configuration provided in the examples 'home' module, which we can run as
below:
 
-    java -Djava.security.manager -Djava.security.policy=server.policy -jar lib/start.jar
start-infra.config
+    java -Djava.security.manager -Djava.security.policy=server.policy -Djava.rmi.server.useCodebaseOnly=false
-jar lib/start.jar start-infra.config
 
 If you run this command line, and you still have your service browser open from the 
 previous section, you should see a registrar appear in the browser, like so:

Added: river/river-examples/river-examples/trunk/src/site/resources/hello-client/Client-run.png
URL: http://svn.apache.org/viewvc/river/river-examples/river-examples/trunk/src/site/resources/hello-client/Client-run.png?rev=1657985&view=auto
==============================================================================
Binary file - no diff available.

Propchange: river/river-examples/river-examples/trunk/src/site/resources/hello-client/Client-run.png
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream



Mime
View raw message