Fork me on GitHub

This tutorial describes how to create, develop and deploy a simple Hello World application using Rio.

Introduction

Rio provides a dynamic service oriented architecture, allowing the development, deployment and management of services through the network. Rio provides the ability to develop POJO based services, Spring supported deployment as well as using the Rio Service Bean approach.

Service Beans provide a simple component model defining lifecycle semantics of a dynamic service (start, init, advertise, unadvertise, stop, destroy). The fundamental premise is for the infrastructure to provide an easy to use programming model, whole maintaining access to lower level APIs such as Watches, Associations and Remote Events.

The POJO approach leverages the Service Bean model, allowing POJOs to be developed and deployed without using any Rio infrastructure code. Our example in this section uses a simple Hello World Plain Old Java Object (POJO). The bean is dynamically made available as a distributed service by Rio, allowing the bean to be accessed remotely, with built-in management, fault detection and automated deployment.

This example will also use a test client, showing how the service can be tested and invoked.

Project Creation

This tutorial uses the Rio Maven Archetype to create a project.

  1. Open a terminal window
  2. Run the following command:
    mvn archetype:generate
    -DarchetypeGroupId=org.rioproject
    -DarchetypeArtifactId=rio-archetype
    -DarchetypeRepository=http://www.rio-project.org/maven2
    -DarchetypeVersion=4.2
  3. When prompted for the service, enter Hello. Provide appropriate values for the artifactId, groupId, version and package name.
  4. When complete cd into the newly created project
Maven also comes pre-packaged with plugins for getting up and running with your favorite IDE. Try using mvn idea:idea or mvn eclipse:eclipse for each respective editor.

The Rio Maven Archetype generates a fully functional multi-module Maven project for you with the following structure:

The following items are generated

  • The pom.xml
  • hello-api/pom.xml
  • hello-api/src/main/java/package/hello/Hello.java (interface)
  • hello-service/src/main/java/package/hello/HelloImpl.java (implementation)
  • hello-service/src/test/java/package/hello/ITAbstractHelloTest.java (used as a base class for service testing)
  • hello-service/src/test/java/package/hello/ITHelloTest.java (uses a StaticCybernode for testing your service)
  • hello-service/src/test/java/package/hello/ITHelloDeployTest.java (starts Rio services and deploys your service for testing)
  • hello-service/src/test/conf/test-config.groovy
  • src/main/opstring/artifactId.groovy (OperationalString)
The package name is replaced with the value you provided when prompted by the Rio Maven Archetype.

If you'd like to add a smart proxy to your service, add another module to the project as follows:

Make sure to adjust the service's module dependency to depend on the proxy, not the api.

Service Interface and Implementation

Open up the generated Hello.java interface. You'll see the interface is quite simple:

import java.rmi.RemoteException;
    
public interface Hello {

}

Add the following to the interface:

import java.rmi.RemoteException;
    
public interface Hello {
    String hello(String message) throws RemoteException;
}


Note the declaration of java.rmi.RemoteException for the hello method. This is required to distinguish that the method invocation is remote-able. Why is this important? For one, the distinction between local invocation vs. remote invocation is a distinction that should not be papered over.

When developing a system composed of distributed services, the developer (and deployer) need to be aware of the semantics of remote invocations. Masking that a method may be local or remote can have adverse side-effects in the deployment of enterprise-wide systems, since such issues of partial failure and latency are not formal considerations of the designers and developers.

Rio provides great utility here, especially in the context of Associations, however, the enforcement of declaring throws RemoteException for methods that are to be invoked remotely is a requirement when developing services with Rio.

The implementation of the bean for the Hello interface is equally as simple. You'll need to implement the hello method:

public class HelloImpl implements Hello {
    int visitorNumber = 1;

    public String hello(String message) {
        System.out.println("Client says hello : "+message);
        return("Hello visitor : "+visitorNumber++);
    }
}

Testcases

The Rio Maven Archetype generates 3 test classes:

  • hello-service/src/test/java/package/hello/ITAbstractHelloTest.java (used as a base class for service testing)
  • hello-service/src/test/java/package/hello/ITHelloTest.java (uses a StaticCybernode for testing your service)
  • hello-service/src/test/java/package/hello/ITHelloDeployTest.java (starts Rio services and deploys your service for testing)

Open up the generated ITAbstractHelloTest.java class. Modify the testService method as follows:

void testService(Hello service) {
    Assert.assertNotNull(service);
    /* Add your testing code here ...*/
    Throwable thrown = null;
    try {
        for(int i=1; i<10; i++) {
	        String result = service.hello("Test Client");
            Assert.assertEquals("Hello visitor : "+i, result);
        }
    } catch(Throwable t) {
	    thrown = t;
    }
    Assert.assertNull(thrown);
}

Build and Deploy

Once you've made those modifications, the example can be run during the integration-test lifecycle phase of the project (see the declaration of the failsafe-maven-plugin in the pom), or by deploying the example to a running Rio system.

To deploy the example to a running Rio system:

Note: Make sure your project is built. If you run mvn install, your project will be built, packaged tested and installed to your local repository. The integration tests include starting Rio services and deploying the application. If you want to skip the tests and just deploy the project, run mvn install -Dmaven.test.skip and follow the steps below.

  1. Make sure Rio services are running
  2. Deploy the example
  3. View the deployed example

Back to top

Version: 5.0-M3. Last Published: 2013-06-04.