Skip to content

Programmers Guide

allenxwang edited this page Jun 13, 2013 · 17 revisions

Client Configuration Options

The easiest way to configure client and load balancer is through loading properties into Archaius that conform to the specific format:


You can define properties in a file on classpath or as system properties. If former, ConfigurationManager.loadPropertiesFromResources() API should be called to load the file.

By default, “ribbon” should be the nameSpace.

If there is no property specified for a named client, ClientFactory will still create the client and load balancer with default values for all necessary properties. The default values are specified in DefaultClientConfigImpl.

If a property is missing the clientName, it is interpreted as a property that applies to all clients.

for example


This will establish the default ReadTimeout property for all clients.

You can also programmatically set properties by constructing instance of DefaultClientConfigImpl. Follow these steps:

  • Call DefaultClientConfigImpl.getClientConfigWithDefaultValues(String clientName) to load default values, and any properties that are already defined with Configuration in Archaius
  • Set all desired properties by calling DefaultClientConfigImpl.setProperty() API.
  • Pass this instance together with client name to proper ClientFactory API.

If it is desired to have properties defined in a different name space, for example, “foo”

you should use getClientConfigWithDefaultValues(String clientName, String nameSpace) constructor – in this case getClientConfigWithDefaultValues(“myclient”, “foo”) – in the first step above.

Use non-default property name space with ClientFactory

If you want to use a property name space other than “ribbon”, and utilize ClientFactory APIs to create client or load balancer, there are several ways:

Option 1

Extend DefaultClientConfigImpl and override the method getNameSpace(), e.g.,

public class MyClientConfig extends DefaultClientConfigImpl {
    // ...
    public String getNameSpace() {
        return "foo";

Assuming all your properties are defined as*, you can use the following ClientFactory API to create the client:

  MyClient client = (MyClient) ClientFactory.createNamedClient("myclient", MyClientConfig.class);

Option 2

Use DefaultClientConfigImpl but change its name space from the default. For example, we have the client
with the name “myclient” and its properties are defined in name space “foo”:

  DefaultClientConfigImpl clientConfig = new DefaultClientConfigImpl("foo");
  MyClient client = (MyClient) ClientFactory.registerClientFromProperties("myclient", clientConfig);

Implement your own client with load balancer support

You need to extend and implement a few methods. Specifically, IClient.execute() method should be implemented to carry out protocol specific operations.

AbstractLoadBalancerAwareClient takes care of the load balancer integration, retry logic, and collection of statistics that is used as input to load balancer algorithms and for monitoring.

The client application needs to define this property for its configuration

<clientName>.<nameSpace>.ClientClassName=<Your implementation class name>

Then the client application can get an instance of the client by using appropriate APIs from ClientFactory

Integration with Eureka

Eureka provides service discovery functionality and can be integrated with ribbon to provide dynamic list of servers. To use Eureka with ribbon, follow these steps:

  • Include ribbon-eureka in your dependency
  • (Done by default) Enable the load balancer for the client and configure the load balancer to be DynamicServerListLoadBalancer or its sub class. This is true by default.
  • Configure the ServerList to be
  • Configure the server refresh rate. (optional, default is 30 seconds)
  • Configure the server’s virtual address (“Vip Address”) for the client and make sure it matches the server’s “Vip Address” it uses to register with Eureka server.

Here is an example

# refresh every minute 

# movieservice is the virtual address that the target server(s) uses to register with Eureka server

In addition, your need to have proper configuration files for Eureka client. See here.

You can’t perform that action at this time.