Getting started

This guide walks you through the process of creating a "hello world" JSON-RPC safe (over HTTP) service, whose responses can be cached for 1 hour in the browser cache.

In particular you are going to create a service that greets many people at the same time, that is, it receives an array of people: Person[], and returns an array of greetings: Greeting[].

Requisites:

• JDK 1.7 or later
• Maven 3.0+

Creating the project

The first step is to create the project structure by using the rpc-tomcat-jar maven archetype.

In a directory of your choice, run the following maven command:

mvn archetype:generate -B -DarchetypeGroupId=org.brutusin -DarchetypeArtifactId=rpc-tomcat-jar -DarchetypeVersion=${version} -DgroupId=test -DartifactId=brutusin-rpc-demo -Dversion=1.0.0-SNAPSHOT

By substituting: ${version} with the latest version of the archetype

and the following project structure will be created:

.
|-- brutusin-rpc-demo
|   |-- src/main
|   |   |-- resources
|   |   |   |-- brutusin-rpc.md
|   |   |   |-- brutusin-rpc.version
|   |   |   |-- brutusin-rpc.xml
|   |   |   |-- META-INF/resources
|   |   |   |   |-- index.jsp
|   |   |-- java/test/brutusin_rpc_demo/security
|   |   |   |-- SecurityConfig.java
|   |   |   |-- SecurityInitializer.java
|   |-- pom.xml

then set the created project folder as working directory:

cd brutusin-rpc-demo

Input and output message classes

Create the input class test.Person in the following location:

src/main/java/test/brutusin_rpc_demo/Person.java

Input class:

package test.brutusin_rpc_demo;

public class Person {

    private String name;
    private Integer age;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }
}

Now create the output class test.Greeting in the following location:

src/main/java/test/brutusin_rpc_demo/Greeting.java

Output class:

package test.brutusin_rpc_demo;

public class Greeting {

    private String greeting;

    public String getGreeting() {
        return greeting;
    }

    public void setGreeting(String greeting) {
        this.greeting = greeting;
    }
}

Action implementation

Actions define the behavior of the service, since we are interested in a HTTP safe service, the respective framework base action (SafeAction) has to be extended.

Create the action class test.brutusin_rpc_demo.HelloWorldAction in the following location:

./src/main/java/test/brutusin_rpc_demo/HelloWorldAction.java

package test.brutusin_rpc_demo;

import org.brutusin.rpc.Server;
import org.brutusin.rpc.http.Cacheable;
import org.brutusin.rpc.http.SafeAction;

public class HelloWorldAction extends SafeAction<Person[], Greeting[]> {

    @Override
    public Cacheable<Greeting[]> execute(Person[] list) {
        if (list == null) {
            list = new Person[1];
        }
        Greeting[] ret = new Greeting[list.length];
        for (int i = 0; i < list.length; i++) {
            ret[i] = greetPerson(list[i]);
        }
        return Cacheable.forMaxHours(ret,1);
    }

    private Greeting greetPerson(Person person) {
        StringBuilder sb = new StringBuilder("Hello");
        Greeting ret = new Greeting();
        if (person != null) {
            if (person.getName() != null) {
                sb.append(" ");
                sb.append(person.getName());
            }
            if (person.getAge() != null) {
                sb.append(", you are ");
                sb.append(person.getAge());
                sb.append(" years old");
            }
        }
        sb.append("!");
        ret.setGreeting(sb.toString());
        return ret;
    }
    
    public static void main(String[] args) {
        Server.test(new HelloWorldAction());
    }
}

Project build

Build the project running the following maven command:

mvn clean package

Quick test

Run the previous executable class, and then, the default browser will open the functional testing module pointing at the newly created service.

mvn exec:java -Dexec.mainClass=test.brutusin_rpc_demo.HelloWorldAction

Now you can execute the service twice:

and check that browser is effectively caching the resource.

Stop the test server instance by pressing Ctrl+C in the console.

Registration

Register the service in the file src/main/resources/brutusin-rpc.xml (Spring syntax):

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
	   					   http://www.springframework.org/schema/beans/spring-beans.xsd">

     <bean id="http.hello" class="test.brutusin_rpc_demo.HelloWorldAction"/>
</beans>

and build the project again (mvn clean package).

Application running

Finally, after building the project you can run the application using maven

mvn exec:java -Dexec.mainClass=org.brutusin.rpc.Main

or running the shaded jar

java -jar target/brutusin-rpc-demo-1.0.0-SNAPSHOT-executable.jar

Now, the browser will be open rendering the page at src/main/resources/META-INF/resources/index.jsp:

.

Typically you would edit this page to create the client-side part (using the Javascript API) of your single page application.

Notice that a service repository is accessible at http://localhost:8080/rpc/repo:

where you can see the newly created service with id http.hello, and the rest of builtin services provided by the framework.

Congratulations!! you have just created and application with one HTTP service.