You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by gt...@apache.org on 2015/02/06 23:55:01 UTC
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/
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.
+
+
+
+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:
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