Getting Started

The simplest way to get started is to use the property driven factory to create instance of client with load balancer. The sample application in ribbon-httpclient shows the basic usage and is described below:

The properties file (sample-client.properties)

# Max number of retries on the same server (excluding the first try)
sample-client.ribbon.MaxAutoRetries=1

# Max number of next servers to retry (excluding the first server)
sample-client.ribbon.MaxAutoRetriesNextServer=1

# Whether all operations can be retried for this client
sample-client.ribbon.OkToRetryOnAllOperations=true

# Interval to refresh the server list from the source
sample-client.ribbon.ServerListRefreshInterval=2000

# Connect timeout used by Apache HttpClient
sample-client.ribbon.ConnectTimeout=3000

# Read timeout used by Apache HttpClient
sample-client.ribbon.ReadTimeout=3000

# Initial list of servers, can be changed via Archaius dynamic property at runtime
sample-client.ribbon.listOfServers=www.microsoft.com:80,www.yahoo.com:80,www.google.com:80

The format of the entry is

<clientName>.<nameSpace>.<propertyName>=<value>

The clientName will be used later in the factory to create client. The nameSpace is configurable and is by default “ribbon”. The common property name is available in CommonClientConfigKey.

The properties can be also defined as system properties, or in any property source loaded by Archaius.

The code

public static void main(String[] args) throws Exception {
      ConfigurationManager.loadPropertiesFromResources("sample-client.properties");  // 1
      System.out.println(ConfigurationManager.getConfigInstance().getProperty("sample-client.ribbon.listOfServers"));
      RestClient client = (RestClient) ClientFactory.getNamedClient("sample-client");  // 2
      HttpClientRequest request = HttpClientRequest.newBuilder().setUri(new URI("/")).build(); // 3
      for (int i = 0; i < 20; i++)  {
      	HttpClientResponse response = client.executeWithLoadBalancer(request); // 4
      	System.out.println("Status code for " + response.getRequestedURI() + "  :" + response.getStatus());
      }
      ZoneAwareLoadBalancer lb = (ZoneAwareLoadBalancer) client.getLoadBalancer();
      System.out.println(lb.getLoadBalancerStats());
      ConfigurationManager.getConfigInstance().setProperty(
      		"sample-client.ribbon.listOfServers", "www.linkedin.com:80,www.google.com:80"); // 5
      System.out.println("changing servers ...");
      Thread.sleep(3000); // 6
      for (int i = 0; i < 20; i++)  {
      	HttpClientResponse response = client.executeWithLoadBalancer(request);
      	System.out.println("Status code for " + response.getRequestedURI() + "  : " + response.getStatus());
      	response.releaseResources();
      }
      System.out.println(lb.getLoadBalancerStats()); // 7
}

Notes:

1. Load the properties file using Archaius ConfigurationManager.
2. Use ClientFactory to create client and the load balancer.
3. Build the http request using the builder. Note that we only supply the path part (“/”) of the URI. The complete URI will be computed by the client once the server is chosen by the load balancer.
4. Call client.executeWithLoadBalancer() API, not the execute() API.
5. Dynamically change the server pool from the configuration.
6. Wait until server list is refreshed (2 seconds refersh interval defined in properties file)
7. Print out the server stats recorded by the load balancer.

The load balancer stats contain lots of information for monitoring and is used as input for load balancer algorithms. Here is an example from the output:

Zone stats: {unknown=[Zone:unknown;	Instance count:2;	Active connections count: 0;	Circuit breaker tripped count: 0;	Active connections per server: 0.0;]
},Server stats: [[Server:www.microsoft.com:80;	Zone:UNKNOWN;	Total Requests:6;	Successive connection failure:0;	Total blackout seconds:0;	Last connection made:Fri Jan 25 14:52:18 PST 2013;	First connection made: Fri Jan 25 14:52:15 PST 2013;	Active Connections:0;	total failure count in last (1000) msecs:0;	average resp time:129.83333333333334;	90 percentile resp time:0.0;	95 percentile resp time:0.0;	min resp time:33.0;	max resp time:530.0;	stddev resp time:179.30180949697325]
, [Server:www.google.com:80;	Zone:UNKNOWN;	Total Requests:17;	Successive connection failure:0;	Total blackout seconds:0;	Last connection made:Fri Jan 25 14:52:23 PST 2013;	First connection made: Fri Jan 25 14:52:14 PST 2013;	Active Connections:0;	total failure count in last (1000) msecs:0;	average resp time:67.6470588235294;	90 percentile resp time:50.0;	95 percentile resp time:50.0;	min resp time:45.0;	max resp time:384.0;	stddev resp time:79.12234842799629]
, [Server:www.yahoo.com:80;	Zone:UNKNOWN;	Total Requests:7;	Successive connection failure:0;	Total blackout seconds:0;	Last connection made:Fri Jan 25 14:52:18 PST 2013;	First connection made: Fri Jan 25 14:52:13 PST 2013;	Active Connections:0;	total failure count in last (1000) msecs:0;	average resp time:561.1428571428571;	90 percentile resp time:0.0;	95 percentile resp time:0.0;	min resp time:445.0;	max resp time:879.0;	stddev resp time:132.42618274930024]
, [Server:www.linkedin.com:80;	Zone:UNKNOWN;	Total Requests:10;	Successive connection failure:0;	Total blackout seconds:0;	Last connection made:Fri Jan 25 14:52:23 PST 2013;	First connection made: Fri Jan 25 14:52:22 PST 2013;	Active Connections:0;	total failure count in last (1000) msecs:0;	average resp time:94.6;	90 percentile resp time:404.0;	95 percentile resp time:404.0;	min resp time:53.0;	max resp time:404.0;	stddev resp time:103.25037530198135]
]