Getting Started

Lets get started with a simple example.

First, create an instance of Janus.

//create a Builder that will construct a Janus for "UserService"
Builder builder = Janus.builder("UserService");

//provide a static list of urls of the server instances that should be used.
builder.withServers("http://userserviceinstance1:8080,http://userserviceinstance2:8080");

//configures Janus to use random load balancing
builder.withRandomLoadBalancing();

//build the Janis instance that will be used for "UserService" 
Janus janus = builder.build();

//ask Janus for a server.
ServerStats server = janus.getServer();

So, whats going on here?

builder.withServers("http://userserviceinstance1:8080,http://userserviceinstance2:8080");

We configure Janus with a server instance discovery strategy. The strategy in snippet above simply provides a static list of URLs.

builder.withRandomLoadBalancing();

We configure Janus with a load balancing strategy which will select one of the available server instances. The strategy in the snippet above randomly selects a server instance from the list of available server instances.

ServerStats server = janus.getServer();

Janus applies the load balancing strategy to the available servers and returns the "best" server for the next request/message. The returned ServerStats object includes information about the selected server (its hostname, ports, etc) as well as the selected server instance's usage statistics.

The returned ServerStats object is used to track various metrics about how a backend server instance is being used Janus instance. When using one of the provided clients (below), the ServerStats object is updated automatically when you connect or send messages to backend server instances. However, if you're not using a provided client, and only using Janus for server selection, you may need to update the ServerStats yourself (if your load balancing strategy depends on it).

Provided Clients

You can use Janus directly (as above) if you'd like, but if you're sending messages to you server instances over HTTP or WebSockets, you can take advantage of one of Janus's provided clients for sending the messages. Using one of the provided clients gives you:

1. automatic statistics tracking for messages sent to your server instances
2. retry functionality for failed connects/sends
3. message payload marshalling/unmarshalling

For example, if you're make HTTP requests to your server instance, you can use the DefaultRestTemplateClient

Janus janus = Janus.builder("UserService")
    .withServers("http://userserviceinstance1:8080,http://userserviceinstance2:8080")
    .withRandomLoadBalancing()
    .build();

DefaultRestTemplateClient restClient = new DefaultRestTemplateClient(janus, 3/*number of retries*/)

User user = restClient.getForObject("/users/{userId}", User.class, userId);

In the previous example, DefaultRestTemplateClient is used for making HTTP requests to the "UserService" service cluster. The DefaultRestTemplateClient will ask Janus for a server instance to send the request to. DefaultRestTemplateClient will send the request to the returned service instance, and track the server's request statistics.

More information about the provided message clients is available here.