This project is the initial development of the Apache River Container. It is not yet released as Apache Software. Use at your own risk, and please post comments to dev@river.apache.org.
Let‘s assume you’ve managed to download the source from git. In fact, let‘s assume that you’re reasonably conversant with git, so you can pull the examples project below.
You'll need Maven 3.x installed, such that you can run ‘mvn’ from the command line.
This step may not be required in the future, since you'll be able to download a convenience binary once the project is released
Go to the root of the river-container download, and type
mvn clean install
cd product/target/product* bin/run
The steps above will startup a default container that has instances of the service registrar (Reggie) and the transaction manager (Mahalo). All services are registered in a workgroup called ‘RiverContainerDefault’.
Open a new command line window in the root of the river-container download, then do the following:
cd product/target/product* bin/run client browser
You'll see a service browser window open up. It should show one registrar. Select the registrar. You should now see the infrastructure services, Reggie and Mahalo. Leave the service browser running while we start up a “Hello-world” service, below.
Maybe the ‘hello-world’ example should be included in the container deliverable? Please comment on ‘dev@river.apache.org’. Eventually, we should be able to create this example service using a Maven archetype.
Using git, pull the examples from https://github.com/trasukg/river-container-examples.
‘cd’ into your hello-example' directory, and then:
mvn clean install
When Maven is done, you should be able to see the finished service archive, ‘hello-module/target/hello-module-1.0-SNAPSHOT.jar’
Copy that ‘jar’ file into the ‘profiles/default/deploy’ folder inside our ‘river-container/product/target/product*’ folder.
Eventually, we'll have a maven plugin that does this, so you can just do ‘mvn river:deploy’ rather than copying it manually.
If you left the container running, you should see some output indicating that the service is being deployed. If you didn't leave the container running, start it up now.
You should also see the service in the service browser, with the interface ‘org.apache.river.container.hello.example.api.Greeter’
When Maven finished above, it also created a client archive, ‘hello-client-module/target/hello-client-module-1.0-SNAPSHOT.jar’
Copy that ‘jar’ file into the ‘profiles/client/deploy’ folder inside our ‘river-container/product/target/product*’ folder.
Open a new command line window in the root of the river-container download, then do the following:
cd product/target/product* bin/run client hello-client
The client starts up, and eventually prompts ‘Please enter your name’. Enter your name and then press return.
The client sends the greeter service a message, then prints out the reply.
If you have another machine on the local area network, and if the network is configured to allow multicast, you should be able to run the browser and the hello-client on a different machine.
That concludes the ‘First Fifteen Minutes’ demo. Below, there is a little more detailed information...
mvn clean install
cd product/target/product* bin/run [profile] arg*
If you don‘t specify [profile] the ‘default’ profile will be used. ‘arg*’ isn’t really used much in the service container profiles (like ‘default’).
Services are packaged into a jar file and placed into the ‘deploy’ folder of the profile that you want to run. When you run the container, all services in the profile are started up. The default profile monitors the deploy folder each 5s and starts up any new services you put into the deploy folder. The ‘default’ profile already includes a transient reggie instance and a transient mahalo instance. You can add your own services to this folder as well.
Have a look at the ‘reggie-module’ or ‘mahalo-module’ target folders to see what the archive should look like. Startup parameters are in ‘start.properties’. ‘start.properties’ calls out the startup class and the parameters to its constructor (typically the name of the configuration file and any overrides to the config).
cd product/target/product* bin/run client AppName arg*
Starts up the container using the ‘client’ profile, which then starts the client that is named by ‘AppName’ (and only that client, no matter if there are multiple apps in the deploy folder).
The container will host client applications, making the downloads available via a codebase server, and setting up all the security polices that are required. Client apps are packaged much like the services mentioned above.
cd product/target/product* bin/run client browser
Starts up the service browser.
Reggie-module and mahalo-module might be interesting samples. For a simpler ‘hello-world’ example with a Maven build, see https://github.com/trasukg/river-container-examples.