org.codegist.crest
Class CRestBuilder

java.lang.Object
  extended by org.codegist.crest.CRestBuilder

public class CRestBuilder
extends Object

CRest instance can be obtain through this builder.

Author:
Laurent Gilles (laurent.gilles@codegist.org)

Constructor Summary
CRestBuilder()
           
 
Method Summary
 CRestBuilder addPlaceholders(Map<String,String> placeholders)
          Adds all given placeholders to the string-based annotations placeholders replacement map.
 CRestBuilder addProperties(Map<String,Object> crestProperties)
          Adds all given properties to the CRestConfig that will be passed to all CRest components.
 CRestBuilder basicAuth(String username, String password)
          Configures the resulting CRest instance to authenticate all requests using Basic Auth
<A extends Annotation>
CRestBuilder
bindAnnotationHandler(Class<? extends AnnotationHandler<A>> handler, Class<A> annotationCls)
          Binds an annotation handler for the given annotation.
<A extends Annotation>
CRestBuilder
bindAnnotationHandler(Class<? extends AnnotationHandler<A>> handler, Class<A> annotationCls, Map<String,Object> config)
          Binds an annotation handler for the given annotation.
 CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer, Class<?>... classes)
          Binds a deserializer to a list of interface method's return types.
 CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer, Class<?>[] classes, Map<String,Object> config)
          Binds a deserializer to a list of interface method's return types.
 CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer, String... mimeTypes)
          Binds a deserializer to a list of response Content-Type mime-types.
 CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer, String[] mimeTypes, Map<String,Object> config)
          Binds a deserializer to a list of response Content-Type mime-types.
 CRestBuilder bindJsonDeserializerWith(String... mimeTypes)
          Adds the given list of response Content-Type mime-types to be consider as JSON mime-types and to be deserialized by the default JSON Deserializer
 CRestBuilder bindPlainTextDeserializerWith(String... mimeTypes)
          Adds the given list of response Content-Type mime-types to be consider as plain-text mime-types and to be deserialized to plain String
 CRestBuilder bindSerializer(Class<? extends Serializer> serializer, Class<?>... classes)
          Binds a serializer to a list of interface method's parameter types
 CRestBuilder bindSerializer(Class<? extends Serializer> serializer, Class<?>[] classes, Map<String,Object> config)
          Binds a serializer to a list of interface method's parameter types
 CRestBuilder bindXmlDeserializerWith(String... mimeTypes)
          Adds the given list of response Content-Type mime-types to be consider as XML mime-types and to be deserialized by the default XML Deserializer
 CRestBuilder booleanFormat(String trueFormat, String falseFormat)
          Overrides the default boolean format for serialization (default are "true" and "false").
 CRest build()
          Build a CRest instance.
 CRestBuilder dateFormat(String dateFormat)
          Overrides the default date format for serialization (default is "yyyy-MM-dd'T'HH:mm:ssZ").
 CRestBuilder deserializeJsonWith(Class<? extends Deserializer> deserializer)
          Overrides the default JacksonDeserializer JSON deserializer with the given one
 CRestBuilder deserializeJsonWith(Class<? extends Deserializer> deserializer, Map<String,Object> config)
          Overrides the default JacksonDeserializer JSON deserializer with the given one
 CRestBuilder deserializeXmlWith(Class<? extends Deserializer> deserializer)
          Overrides the default JaxbDeserializer XML deserializer with the given one
 CRestBuilder deserializeXmlWith(Class<? extends Deserializer> deserializer, Map<String,Object> config)
          Overrides the default JaxbDeserializer XML deserializer with the given one
 CRestBuilder endpoint(String endpoint)
          Sets the default endpoint all interfaces build through the resulting CRest instance will point at.
 CRestBuilder extractsEntityAuthParamsWith(String entityContentType, EntityParamExtractor entityParamExtractor)
          Sets an entity parameters extractor for authenticated requests.
 CRestBuilder oauth(String consumerKey, String consumerSecret, String accessToken, String accessTokenSecret)
          Configures the resulting CRest instance to authenticate all requests using OAuth 1.0
 CRestBuilder oauth(String consumerKey, String consumerSecret, String accessToken, String accessTokenSecret, String sessionHandle, String accessTokenRefreshUrl)
          Configures the resulting CRest instance to authenticate all requests using OAuth 1.0
 CRestBuilder placeholder(String placeholder, String value)
          Adds the given placeholder to the string-based annotations placeholders replacement map.
 CRestBuilder property(String name, Object value)
          Adds given property to the CRestConfig that will be passed to all CRest components.
 CRestBuilder setConcurrencyLevel(int concurrencyLevel)
          Overrides the default concurrency level (default is 1).
 CRestBuilder setHttpChannelFactory(Class<? extends HttpChannelFactory> httpChannelFactory)
          Overrides the default HttpURLConnectionHttpChannelFactory channel factory to use initiating http requests.
 CRestBuilder setHttpChannelFactory(HttpChannelFactory httpChannelFactory)
          Overrides the default HttpURLConnectionHttpChannelFactory channel factory to use initiating http requests.
 CRestBuilder setPlaceholders(Map<String,String> placeholders)
          Sets all given placeholders to the string-based annotations placeholders replacement map.
 CRestBuilder setProperties(Map<String,Object> crestProperties)
          Sets all given properties to the CRestConfig that will be passed to all CRest components.
 CRestBuilder setProxyFactory(Class<? extends ProxyFactory> proxyFactory)
          Overrides the default JdkProxyFactory proxy factory to use for building user Interfaces proxies.
 CRestBuilder setProxyFactory(ProxyFactory proxyFactory)
          Overrides the default JdkProxyFactory proxy factory to use for building user Interfaces proxies.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CRestBuilder

public CRestBuilder()
Method Detail

build

public CRest build()

Build a CRest instance.

CRest is an expensive object to create and should be created once at the application bootstrap and re-used. CRest instances are threadsafe.

Returns:
a CRest instance

setProxyFactory

public CRestBuilder setProxyFactory(Class<? extends ProxyFactory> proxyFactory)
Overrides the default JdkProxyFactory proxy factory to use for building user Interfaces proxies.

Parameters:
proxyFactory - proxy factory class to use
Returns:
current builder
See Also:
CglibProxyFactory, JdkProxyFactory

setProxyFactory

public CRestBuilder setProxyFactory(ProxyFactory proxyFactory)
Overrides the default JdkProxyFactory proxy factory to use for building user Interfaces proxies.

Parameters:
proxyFactory - proxy factory to use
Returns:
current builder
See Also:
CglibProxyFactory, JdkProxyFactory

setHttpChannelFactory

public CRestBuilder setHttpChannelFactory(Class<? extends HttpChannelFactory> httpChannelFactory)
Overrides the default HttpURLConnectionHttpChannelFactory channel factory to use initiating http requests.

Parameters:
httpChannelFactory - http channel factory class to use
Returns:
current builder
See Also:
HttpClientHttpChannelFactory, HttpURLConnectionHttpChannelFactory

setHttpChannelFactory

public CRestBuilder setHttpChannelFactory(HttpChannelFactory httpChannelFactory)
Overrides the default HttpURLConnectionHttpChannelFactory channel factory to use initiating http requests.

Parameters:
httpChannelFactory - http channel factory to use
Returns:
current builder
See Also:
HttpClientHttpChannelFactory, HttpURLConnectionHttpChannelFactory

setConcurrencyLevel

public CRestBuilder setConcurrencyLevel(int concurrencyLevel)
Overrides the default concurrency level (default is 1).

Parameters:
concurrencyLevel - Concurrency level various CRest should be able to deal with
Returns:
current builder
See Also:
CRestConfig.CREST_CONCURRENCY_LEVEL, CRestConfig.getConcurrencyLevel()

dateFormat

public CRestBuilder dateFormat(String dateFormat)
Overrides the default date format for serialization (default is "yyyy-MM-dd'T'HH:mm:ssZ").

Parameters:
dateFormat - new date format
Returns:
current builder
See Also:
CRestConfig.CREST_DATE_FORMAT, CRestConfig.getDateFormat()

booleanFormat

public CRestBuilder booleanFormat(String trueFormat,
                                  String falseFormat)
Overrides the default boolean format for serialization (default are "true" and "false").

Parameters:
trueFormat - format for TRUE
falseFormat - format for FALSE
Returns:
current builder
See Also:
CRestConfig.CREST_BOOLEAN_TRUE, CRestConfig.CREST_BOOLEAN_FALSE, CRestConfig.getBooleanTrue(), CRestConfig.getBooleanFalse()

addProperties

public CRestBuilder addProperties(Map<String,Object> crestProperties)

Adds all given properties to the CRestConfig that will be passed to all CRest components.

Note that these properties can be used to override defaut CRest's MethodConfig and ParamConfig values when none are provided through annotations.

Parameters:
crestProperties - properties
Returns:
current builder
See Also:
CRestConfig, MethodConfig, ParamConfig

property

public CRestBuilder property(String name,
                             Object value)

Adds given property to the CRestConfig that will be passed to all CRest components.

Note that this property can be used to override defaut CRest's MethodConfig and ParamConfig values when none are provided through annotations.

Parameters:
name - property name
value - property value
Returns:
current builder
See Also:
CRestConfig, MethodConfig, ParamConfig

setProperties

public CRestBuilder setProperties(Map<String,Object> crestProperties)

Sets all given properties to the CRestConfig that will be passed to all CRest components.

Note that these properties can be used to override defaut CRest's MethodConfig and ParamConfig values when none are provided through annotations.

Parameters:
crestProperties - properties
Returns:
current builder
See Also:
CRestConfig, MethodConfig, ParamConfig

endpoint

public CRestBuilder endpoint(String endpoint)

Sets the default endpoint all interfaces build through the resulting CRest instance will point at.

By setting it, it is not required anymore to set the @EndPoint annotation to the interfaces passed to the resulting CRest instance.

Shortcut to:

 CRestBuilder.property(MethodConfig.METHOD_CONFIG_DEFAULT_ENDPOINT, endpoint)
 

Parameters:
endpoint - end point to point at
Returns:
current builder

addPlaceholders

public CRestBuilder addPlaceholders(Map<String,String> placeholders)

Adds all given placeholders to the string-based annotations placeholders replacement map.

Expects a map with keys being the placeholder name (used in string-based annotations) and with values being the value to be used as replacement.

So for the given annotation:

 @EndPoint("http://{app.host}:{app.port}")
 

The placeholders map will be:

 String server = ...;
 String port = ...;
 Map<String,String> placeholders = new HashMap<String,String>();
 placeholders.put("app.host", server);
 placeholders.put("app.port", port);
 CRestBuilder builder = ...;

 builder.addPlaceholders(placeholders);
 

Parameters:
placeholders - placeholder map to use for string-based annotation placeholder replacement
Returns:
current builder

placeholder

public CRestBuilder placeholder(String placeholder,
                                String value)

Adds the given placeholder to the string-based annotations placeholders replacement map.

So for the given annotation:

 @EndPoint("http://{app.host}:{app.port}")
 

The placeholders will be replace if the builder is configured as follow:

 String server = ...;
 String port = ...;
 CRestBuilder builder = ...;

 builder.placeholder("app.host", server)
        .placeholder("app.port", port);
 

Parameters:
placeholder - the placeholder to be replaced
value - the value to replace the placeholder with in string-based annotations
Returns:
current builder

setPlaceholders

public CRestBuilder setPlaceholders(Map<String,String> placeholders)

Sets all given placeholders to the string-based annotations placeholders replacement map.

Expects a map with keys being the placeholder name (used in string-based annotations) and with values being the value to be used as replacement.

So for the given annotation:

 @EndPoint("http://{app.host}:{app.port}")
 

The placeholders map will be:

 String server = ...;
 String port = ...;
 Map<String,String> placeholders = new HashMap<String,String>();
 placeholders.put("app.host", server);
 placeholders.put("app.port", port);
 CRestBuilder builder = ...;

 builder.setPlaceholders(placeholders);
 

Parameters:
placeholders - placeholder map to use for string-based annotation placeholder replacement
Returns:
current builder

bindAnnotationHandler

public <A extends Annotation> CRestBuilder bindAnnotationHandler(Class<? extends AnnotationHandler<A>> handler,
                                                                 Class<A> annotationCls)

Binds an annotation handler for the given annotation.

Can be used to tell CRest how to handle user-defined annotation used in interfaces.

Type Parameters:
A - Used-defined annotation type
Parameters:
handler - The user-defined annotation handler
annotationCls - The user-defined annotation
Returns:
current builder

bindAnnotationHandler

public <A extends Annotation> CRestBuilder bindAnnotationHandler(Class<? extends AnnotationHandler<A>> handler,
                                                                 Class<A> annotationCls,
                                                                 Map<String,Object> config)

Binds an annotation handler for the given annotation.

Can be used to tell CRest how to handle user-defined annotation used in interfaces.

Type Parameters:
A - Used-defined annotation type
Parameters:
handler - The user-defined annotation handler
annotationCls - The user-defined annotation
config - State that will be passed to the annotation handler along with the CRestConfig object if the handler has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
CRestConfig

bindDeserializer

public CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer,
                                     String... mimeTypes)

Binds a deserializer to a list of response Content-Type mime-types.

By default, CRest handle the following types:

Parameters:
deserializer - Deserializer class to use for the given mime-types
mimeTypes - Response Content-Types to bind deserializer to
Returns:
current builder

bindDeserializer

public CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer,
                                     String[] mimeTypes,
                                     Map<String,Object> config)

Binds a deserializer to a list of response Content-Type mime-types.

By default, CRest handle the following types:

Parameters:
deserializer - Deserializer class to use for the given mime-types
mimeTypes - Response Content-Types to bind deserializer to
config - State that will be passed to the deserializer along with the CRestConfig object if the deserializer has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
CRestConfig

bindDeserializer

public CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer,
                                     Class<?>... classes)

Binds a deserializer to a list of interface method's return types.

By default, CRest handle the following types:

Meaning that any interface method return type can be by default one of these types.

Parameters:
deserializer - Deserializer class to use for the given interface method's return types
classes - Interface method's return types to bind deserializer to
Returns:
current builder

bindDeserializer

public CRestBuilder bindDeserializer(Class<? extends Deserializer> deserializer,
                                     Class<?>[] classes,
                                     Map<String,Object> config)

Binds a deserializer to a list of interface method's return types.

By default, CRest handle the following types:

Meaning that any interface method return type can be by default one of these types.

Parameters:
deserializer - Deserializer class to use for the given interface method's return types
classes - Interface method's return types to bind deserializer to
config - State that will be passed to the deserializer along with the CRestConfig object if the deserializer has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
CRestConfig

bindSerializer

public CRestBuilder bindSerializer(Class<? extends Serializer> serializer,
                                   Class<?>... classes)

Binds a serializer to a list of interface method's parameter types

By default, CRest handle the following types:

Meaning any interface method parameter type can be by default one of these types and be serialized properly.

Parameters:
serializer - Serializer class to use to serialize the given interface method's parameter types
classes - Interface method's parameter types to bind the serializer to
Returns:
current builder
See Also:
CRestConfig.getDateFormat(), CRestConfig.getBooleanTrue(), CRestConfig.getBooleanFalse()

bindSerializer

public CRestBuilder bindSerializer(Class<? extends Serializer> serializer,
                                   Class<?>[] classes,
                                   Map<String,Object> config)

Binds a serializer to a list of interface method's parameter types

By default, CRest handle the following types:

Meaning any interface method parameter type can be by default one of these types and be serialized properly.

Parameters:
serializer - Serializer class to use to serialize the given interface method's parameter types
classes - Interface method's parameter types to bind the serializer to
config - State that will be passed to the serializer along with the CRestConfig object if the serializer has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
CRestConfig.getDateFormat(), CRestConfig.getBooleanTrue(), CRestConfig.getBooleanFalse()

oauth

public CRestBuilder oauth(String consumerKey,
                          String consumerSecret,
                          String accessToken,
                          String accessTokenSecret)

Configures the resulting CRest instance to authenticate all requests using OAuth 1.0

Parameters:
consumerKey - consumer key to use
consumerSecret - consumer secret to use
accessToken - access token to use
accessTokenSecret - access token secret to use
Returns:
current builder

oauth

public CRestBuilder oauth(String consumerKey,
                          String consumerSecret,
                          String accessToken,
                          String accessTokenSecret,
                          String sessionHandle,
                          String accessTokenRefreshUrl)

Configures the resulting CRest instance to authenticate all requests using OAuth 1.0

When the end-point indicates the access token is expired, CRest will use the given session handle and access toklen refresh url to refresh the access token used as defined in OAuth Session 1.0 Draft 1

Parameters:
consumerKey - consumer key to use
consumerSecret - consumer secret to use
accessToken - access token to use
accessTokenSecret - access token secret to use
sessionHandle - session handle to use to refresh an expired access token
accessTokenRefreshUrl - url to use to refresh an expired access token
Returns:
current builder
See Also:
OAuth Session 1.0 Draft 1

basicAuth

public CRestBuilder basicAuth(String username,
                              String password)

Configures the resulting CRest instance to authenticate all requests using Basic Auth

Parameters:
username - user name to authenticate the requests with
password - password to authenticate the requests with
Returns:
current builder

extractsEntityAuthParamsWith

public CRestBuilder extractsEntityAuthParamsWith(String entityContentType,
                                                 EntityParamExtractor entityParamExtractor)

Sets an entity parameters extractor for authenticated requests.

When CRest is configured to authenticate requests, it uses an EntityParamExtractor to extract parameters from the request entity to include them in the authentication process.

A common use case is to deal with OAuth and multipart as some provider will use some multipart parameters and some not (binaries usually) in order to sign a request

Parameters:
entityContentType - Entity Content-Type to bind the extractor to
entityParamExtractor - Extractor
Returns:
current builder

bindJsonDeserializerWith

public CRestBuilder bindJsonDeserializerWith(String... mimeTypes)

Adds the given list of response Content-Type mime-types to be consider as JSON mime-types and to be deserialized by the default JSON Deserializer

By default, CRest consider to be JSON mime-type the following response Content-Type:

Parameters:
mimeTypes - Response Content-Type mime-types to be consider as JSON mime-types
Returns:
current builder

bindXmlDeserializerWith

public CRestBuilder bindXmlDeserializerWith(String... mimeTypes)

Adds the given list of response Content-Type mime-types to be consider as XML mime-types and to be deserialized by the default XML Deserializer

By default, CRest consider to be XML mime-type the following response Content-Type:

Parameters:
mimeTypes - Response Content-Type mime-types to be consider as XML mime-types
Returns:
current builder

bindPlainTextDeserializerWith

public CRestBuilder bindPlainTextDeserializerWith(String... mimeTypes)

Adds the given list of response Content-Type mime-types to be consider as plain-text mime-types and to be deserialized to plain String

By default, CRest consider to be plain-text mime-type the following response Content-Type:

Parameters:
mimeTypes - Response Content-Type mime-types to be consider as plain-text mime-types
Returns:
current builder

deserializeXmlWith

public CRestBuilder deserializeXmlWith(Class<? extends Deserializer> deserializer)

Overrides the default JaxbDeserializer XML deserializer with the given one

By default, CRest will use this deserializer for the following response Content-Type:

Parameters:
deserializer - deserializer to use for XML response Content-Type requests
Returns:
current builder
See Also:
JaxbDeserializer, SimpleXmlDeserializer

deserializeXmlWith

public CRestBuilder deserializeXmlWith(Class<? extends Deserializer> deserializer,
                                       Map<String,Object> config)

Overrides the default JaxbDeserializer XML deserializer with the given one

By default, CRest will use this deserializer for the following response Content-Type:

Parameters:
deserializer - deserializer to use for XML response Content-Type requests
config - State that will be passed to the deserializer along with the CRestConfig object if the deserializer has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
JaxbDeserializer, SimpleXmlDeserializer

deserializeJsonWith

public CRestBuilder deserializeJsonWith(Class<? extends Deserializer> deserializer)

Overrides the default JacksonDeserializer JSON deserializer with the given one

By default, CRest will use this deserializer for the following response Content-Type:

Parameters:
deserializer - deserializer to use for JSON response Content-Type requests
Returns:
current builder
See Also:
JacksonDeserializer

deserializeJsonWith

public CRestBuilder deserializeJsonWith(Class<? extends Deserializer> deserializer,
                                        Map<String,Object> config)

Overrides the default JacksonDeserializer JSON deserializer with the given one

By default, CRest will use this deserializer for the following response Content-Type:

Parameters:
deserializer - deserializer to use for JSON response Content-Type requests
config - State that will be passed to the deserializer along with the CRestConfig object if the deserializer has declared a single argument constructor with CRestConfig parameter type
Returns:
current builder
See Also:
JacksonDeserializer


Copyright © 2011. All Rights Reserved.