Skip to content

Programmers Guide

Jump to bottom
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:


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

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


ribbon.ReadTimeout=1000

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”


myclient.foo.ReadTimeout=1000

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 myclient.foo.*, 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");
  clientConfig.loadProperites("myclient");
  MyClient client = (MyClient) ClientFactory.registerClientFromProperties("myclient", clientConfig);

Implement your own client with load balancer support

You need to extend com.netflix.client.AbstractLoadBalancerAwareClient 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 com.netflix.niws.loadbalancer.DiscoveryEnabledNIWSServerList
  • 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


myclient.ribbon.NIWSServerListClassName=com.netflix.niws.loadbalancer.DiscoveryEnabledNIWSServerList

# refresh every minute 
myclient.ribbon.ServerListRefreshInterval=60000

# movieservice is the virtual address that the target server(s) uses to register with Eureka server
myclient.ribbon.DeploymentContextBasedVipAddresses=movieservice

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

Clone this wiki locally