Tutorial

This tutorial shows how to create a simple application that uses Ratel mechanisms.

Downloading

All Ratel artifacts are available in the maven central repository, so maven will download them for you automatically, as soon as add a dependency to you project. The only exception to this rule is a ratel-server which is released as a separate executable jar. You can download the ratel server from here: http://search.maven.org/#artifactdetails%7Ccom.payu.ratel%7Cratel-server%7C1.2.7%7Cjar (please note the version number in the url).

Starting the server

Once you downloaded it and saved to your disc, you can run the server in the console:

java -jar ratel-server-<version>.jar

As the server is up running, we can create and run our first distributed system:

Implement a service

In this example we will implement a service with use of spring boot. First, we create appropriate pom.xml with dependendencies to spring boot and ratel:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.payu.ratel</groupId>
	<artifactId>ratel-examples</artifactId>
	<version>1.2.4-SNAPSHOT</version>
	<packaging>jar</packaging>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
			<version>1.2.0.RELEASE</version>
		</dependency>
		<dependency>
			<!-- Import dependency management from Spring Boot -->
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-dependencies</artifactId>
			<version>1.2.0.RELEASE</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
		<dependency>
			<groupId>com.payu.ratel</groupId>
			<artifactId>ratel-core</artifactId>
			<version>${project.version}</version>
		</dependency>
	</dependencies>
</project>

Now, let's assume that we want to have a service with such a contract:

public interface CalculatorService {

  int add(int a, int b);
  
  int divide(int a, int b);
}

We implement it and put @Service and @Publish annotations on the implementation:

@Publish
@Service
public class CalculatorServiceImpl implements CalculatorService {

  public int add(int a, int b) {
    return a + b;
  }

  public int divide(int a, int b) {
    return a / b;
  }

Now let's put it all together into spring application:

@Configuration
@EnableAutoConfiguration
@EnableServiceDiscovery
@ComponentScan(basePackageClasses={CalculatorServiceImpl.class})
public class Calculator {
  
  public static void main(String[] args) {
    SpringApplication.run(Calculator.class, args);
  }

}

Once you start this application your Calculator service should be up, running and registered in the discovery server. You can check it by looking up http://localhost:8090/services/

Implement a client

Once the service is ready, let's create a simple client for it. We can start with the same pom.xml as was used for the service and then just implement an examplary application. If you want to use a service in your app, all you need to do is to use @EnableServiceDiscovery configuration and annotate a field with @Discover. All together put inside a simple console spring application looks like this:

@Configuration
@EnableServiceDiscovery //<- Ratel configuration is included
@Component
public class MyApplication{
  
  @Discover //<- this annotation does the job.
  private CalculatorService calc;
  
  private boolean running;
  
  public static void main(String[] args) {
      SpringApplication app = new SpringApplication(MyApplication.class);
      app.setWebEnvironment(false);
      ConfigurableApplicationContext ctx = app.run(args);
      
      MyApplication myApp = ctx.getBean(MyApplication.class);
      myApp.playConsoleGame();
      
      ctx.close();
  }

  private void playConsoleGame() {
    running = true;
    Scanner scanner = new Scanner(System.in);
    int a, b, sum;
    String quotient;
    
    while (running) {
      System.out.println("Please enter two numbers separated by whitespace");
      a = scanner.nextInt();
      b = scanner.nextInt();
      
      sum = calc.add(a, b); //<- calling the service
      
      try {
        quotient = String.valueOf(calc.divide(a, b)); //<- calling it again
      } catch (ArithmeticException e) {
          //Ratel will transport exception thrown by the remote service implementation
          quotient = "<undefined>";
      }
      
      System.out.printf("Sum of your numbers is %d\nInteger quotient is %s\n\n\n", sum, quotient);;
      
      System.out.println("Try again (y/n)?");
      running = scanner.next("[yY]|[nN]").equalsIgnoreCase("y");
    }    
  }  
}

Further reading

• Standalone client
• Exporting services
• Creating service clients
• Configuration