Ribbon Client API Design

ClientOptions.java

public final class ClientOptions {
    
    private Map<IClientConfigKey<?>, Object> options;
    
    private ClientOptions() {
        options = new ConcurrentHashMap<IClientConfigKey<?>, Object>();
    }
    
    public static ClientOptions create() {
        return new ClientOptions();
    }
        
    public ClientOptions withDiscoveryServiceIdentifier(String identifier) {
        options.put(IClientConfigKey.CommonKeys.DeploymentContextBasedVipAddresses, identifier);
        return this;
    }
    
    public ClientOptions withConfigurationBasedServerList(String serverList) {
        options.put(IClientConfigKey.CommonKeys.ListOfServers, serverList);
        return this;
    }
        
    public ClientOptions withMaxAutoRetries(int value) {
        options.put(IClientConfigKey.CommonKeys.MaxAutoRetries, value);
        return this;
    }

    public ClientOptions withMaxAutoRetriesNextServer(int value) {
        options.put(IClientConfigKey.CommonKeys.MaxAutoRetriesNextServer, value);
        return this;        
    }
    
    public ClientOptions withRetryOnAllOperations(boolean value) {
        options.put(IClientConfigKey.CommonKeys.OkToRetryOnAllOperations, value);
        return this;
    }
        
    public ClientOptions withMaxConnectionsPerHost(int value) {
        options.put(IClientConfigKey.CommonKeys.MaxConnectionsPerHost, value);
        return this;        
    }

    public ClientOptions withMaxTotalConnections(int value) {
        options.put(IClientConfigKey.CommonKeys.MaxTotalConnections, value);
        return this;        
    }
    
    public ClientOptions withConnectTimeout(int value) {
        options.put(IClientConfigKey.CommonKeys.ConnectTimeout, value);
        return this;                
    }

    public ClientOptions withReadTimeout(int value) {
        options.put(IClientConfigKey.CommonKeys.ReadTimeout, value);
        return this;        
    }

    public ClientOptions withFollowRedirects(boolean value) {
        options.put(IClientConfigKey.CommonKeys.FollowRedirects, value);
        return this;                
    }
            
    public ClientOptions withConnectionPoolIdleEvictTimeMilliseconds(int value) {
        options.put(IClientConfigKey.CommonKeys.ConnIdleEvictTimeMilliSeconds, value);
        return this;                        
    }
    
    public ClientOptions withLoadBalancerEnabled(boolean value) {
        options.put(IClientConfigKey.CommonKeys.InitializeNFLoadBalancer, value);
        return this;                                
    }
    
    Map<IClientConfigKey<?>, Object> getOptions() {
        return options;
    }

}

FallbackHandler.java

public interface FallbackHandler<T> {
    public Observable<T> getFallback(HystrixExecutableInfo<?> hystrixInfo, Map<String, Object> requestProperties);
}

HttpRequestTemplate.java

public class HttpRequestTemplate<I, O> implements RequestTemplate<I, O, HttpClientResponse<O>> {


    @Override
    public HttpRequestTemplate<I, O> withFallbackProvider(FallbackHandler<O> fallbackHandler) {
    }

    @Override
    public HttpRequestBuilder<I, O> requestBuilder() {
    }
    
    public HttpRequestTemplate<I, O> withMethod(String method) {
    }
    
    public HttpRequestTemplate<T> withUriTemplate(String template) {
    }
    
    public HttpRequestTemplate<I, O> withHeader(String name, String value) {
    }    
    
    @Override
    public HttpRequestTemplate<I, O> withHystrixCacheKey(
            String cacheKeyTemplate) {
    }

    @Override
    public HttpRequestTemplate<I, O> addCacheProvider(String keyTemplate, 
            CacheProvider<O> cacheProvider) {
    }
        
    @Override
    public String name() {
    }
    
    @Override
    public HttpRequestTemplate<I, O> withResponseValidator(
            ResponseValidator<HttpClientResponse<O>> transformer) {
    }

    @Override
    public HttpRequestTemplate<I, O> copy(String name) {
    }

    @Override
    public HttpRequestTemplate<I, O> withHystrixProperties(
            Setter propertiesSetter) {
    }
    
    
}

HttpResourceGroup.java

public class HttpResourceGroup extends ResourceGroup<HttpRequestTemplate<?>> {

    public HttpResourceGroup(String groupName) {
    }
    
    public HttpResourceGroup(String groupName, ClientOptions options) {
    }
    
    public HttpResourceGroup withCommonHeader(String name, String value) {
        return this;
    }

    @Override
    public <T> HttpRequestTemplate<T> newRequestTemplate(String name,
            Class<? extends T> classType) {
    }

    
    public HttpRequestTemplate<ByteBuf> newRequestTemplate(String name) {
    }
    
}

RequestTemplate.java

/**
 * @param <T> response entity type
 * @param <R> response meta data, e.g. HttpClientResponse
 */
public abstract class RequestTemplate<T, R> {
    
    public abstract RequestBuilder<T> requestBuilder();
    
    public abstract String name();
    
    public abstract RequestTemplate<T, R> copy(String name);
        
    public abstract RequestTemplate<T, R> withFallbackProvider(FallbackHandler<T> fallbackProvider);
    
    public abstract RequestTemplate<T, R> withResponseValidator(ResponseValidator<R> transformer);
        
    /**
     * Calling this method will enable both Hystrix request cache and supplied external cache providers  
     * on the supplied cache key. Caller can explicitly disable Hystrix request cache by calling 
     * {@link #withHystrixProperties(com.netflix.hystrix.HystrixObservableCommand.Setter)}
     *     
     * @param cacheKeyTemplate
     * @return
     */
    public abstract RequestTemplate<T, R> withRequestCacheKey(String cacheKeyTemplate);

    public abstract RequestTemplate<T, R> withCacheProvider(String cacheKeyTemplate, CacheProvider<T> cacheProvider);
    
    public abstract RequestTemplate<T, R> withHystrixProperties(HystrixObservableCommand.Setter setter);
    
    public static abstract class RequestBuilder<T> {
        public abstract RequestBuilder<T> withRequestProperty(String key, Object value);
        
        public abstract RibbonRequest<T> build();
    }
}

RequestWithMetaData.java

public interface RequestWithMetaData<T> {
    Observable<RibbonResponse<Observable<T>>> observe();

    Observable<RibbonResponse<Observable<T>>> toObservable();

    Future<RibbonResponse<T>> queue();

    RibbonResponse<T> execute();
}

ResourceGroup.java

public abstract class ResourceGroup<T extends RequestTemplate<?, ?>> {

    public ResourceGroup(String name) {
    }

    public ResourceGroup(String name, ClientOptions options) {
    }
    
    public String name() {
        return name;
    }
    
    public abstract <S> T newRequestTemplate(String name, Class<? extends S> classType);
}

ResponseValidator.java

public interface ResponseValidator<T> {
    /**
     * @param response Protocol specific response object, e.g., {@link HttpClientResponse}
     * @throws UnsuccessfulResponseException throw if server is able to execute the request, but 
     *              returns an an unsuccessful response.
     *              For example, HTTP response with 404 status code. This will be treated as a valid
     *              response and will not trigger Hystrix fallback
     * @throws ServerError throw if the response indicates that there is an server error in executing the request. 
     *              For example, HTTP response with 500 status code. This will trigger Hystrix fallback.
     */
    public void validate(T response) throws UnsuccessfulResponseException, ServerError;
}

Ribbon.java

public final class Ribbon {
    
    private Ribbon() {
    }
 
    public static HttpResourceGroup createHttpResourceGroup(String name) {
        return new HttpResourceGroup(name);
    }

    public static HttpResourceGroup createHttpResourceGroup(String name, ClientOptions options) {
        return new HttpResourceGroup(name, options);
    }

    public static <T> T from(Class<T> contract) {
        return null;
    } 
}

RibbonRequest.java

public interface RibbonRequest<T> {

    public T execute();
    
    public Future<T> queue();
    
    public Observable<T> observe();
    
    public Observable<T> toObservable();
    
    public RequestWithMetaData<T> withMetadata();
}

RibbonResponse.java

public abstract class RibbonResponse<T> {
    public abstract T content();
    
    public abstract HystrixExecutableInfo<?> getHystrixInfo();   
}