com.aspc.remote.rest

Class ReST.Builder

java.lang.Object

com.aspc.remote.rest.ReST.Builder

Enclosing class:

ReST

public static class ReST.Builder
extends java.lang.Object

Method Summary

Modifier and Type	Method and Description
ReST.Builder	addParameter(java.lang.String name, long value) Add a parameter
ReST.Builder	addParameter(java.lang.String name, java.lang.String value) Add a parameter (decoded)
ReST.Builder	addQuery(java.lang.String query) A ampersand(&) separated list of encoded name/value pairs.
static java.net.URL	correctURL(java.net.URL url)
java.io.File	getCachePath() What directory should be used for the cache.
java.lang.String	getContentAsString() Fetch a ReST request
Method	getMethod() Get the call method
java.lang.String[]	getParameterValues(java.lang.String name) Return the current parameter values.
Response	getResponse() Call the server and return the response.
Response	getResponseAndCheck() Short hand method to call getResponse() & checkStatus()
boolean	hasParameter(java.lang.String name) check if a parameter is set
java.lang.String	makeFileName() make the cache file name.
ReST.Builder	setAgent(java.lang.String agent) Set the agent to use
ReST.Builder	setAuthorization(java.lang.String token) sets the authorization token to use for this call.
ReST.Builder	setAuthorization(java.lang.String user, java.lang.String passwd) sets the user/password to use for this call.
ReST.Builder	setAuthorization(java.lang.String user, java.lang.String passwd, java.lang.String domain) sets the user/password to use for this call.
ReST.Builder	setBody(org.w3c.dom.Document bodyXML) Set the body of this POST/PUT request.
ReST.Builder	setBody(org.w3c.dom.Document bodyXML, ContentType contentType, DispositionType dispositionType) set the body of this POST/PUT request with given contentType and dispositionType
ReST.Builder	setBody(java.io.File body) Set the body of this POST/PUT request.
ReST.Builder	setBody(java.io.File body, ContentType contentType, DispositionType dispositionType) Set the body of this POST/PUT request.
ReST.Builder	setBody(JSONArray bodyJSONArray)
ReST.Builder	setBody(JSONObject bodyJSON)
ReST.Builder	setCachePath(java.io.File cachePath) Set the cache path to use
ReST.Builder	setDisableGZIP(boolean disableGZIP) true to NOT accept GZIP encoding, default is false
ReST.Builder	setDisableURLLenghCheck(boolean disable)
ReST.Builder	setEnableValidateCharactersInURL(boolean enable)
ReST.Builder	setErrorCachePeriod(java.lang.String cachePeriod) Set the ERROR cache period for this request
ReST.Builder	setMaxBlockPeriod(java.lang.String maxBlockPeriod) Set the maximum time we are prepared to wait for a NEW result.
ReST.Builder	setMethod(Method method) Set the method to use
ReST.Builder	setMethod(java.lang.String method) Set the method to use
ReST.Builder	setMinCachePeriod(java.lang.String cachePeriod) Set the minimum cache period for this request.
ReST.Builder	setParameter(java.lang.String name, boolean value) set a Boolean parameter
ReST.Builder	setParameter(java.lang.String name, long value) set a parameter
ReST.Builder	setParameter(java.lang.String name, java.lang.String value) set a parameter (decoded)
ReST.Builder	setPlugin(ReSTPlugin plugin) sets the customized authorization to use for this call.
ReST.Builder	setStaleBlockPeriod(java.lang.String staleBlockPeriod) The block time before we will use a stale version ( previously cached) of the request response.
ReST.Builder	setTimeout(java.lang.String timeoutPeriod) The maximum time to wait.
ReST.Builder	setTransport(RestTransport transport) Sets the underlying transport for this ReST call.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

setAuthorization

@Nonnull
public ReST.Builder setAuthorization(@Nonnull
                                              java.lang.String user,
                                              @Nonnull
                                              java.lang.String passwd)
                                       throws InvalidDataException

sets the user/password to use for this call.

Parameters:

user - the user

passwd -

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setAuthorization

@Nonnull
public ReST.Builder setAuthorization(@Nonnull
                                              java.lang.String token)
                                       throws InvalidDataException

sets the authorization token to use for this call.

Parameters:

token - the authorization token

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setAuthorization

@Nonnull
public ReST.Builder setAuthorization(@Nonnull
                                              java.lang.String user,
                                              @Nonnull
                                              java.lang.String passwd,
                                              @Nullable
                                              java.lang.String domain)
                                       throws InvalidDataException

sets the user/password to use for this call.

Parameters:

user - the user

passwd -

domain - the domain

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setPlugin

@Nonnull
public ReST.Builder setPlugin(@Nonnull
                                       ReSTPlugin plugin)
                                throws InvalidDataException

sets the customized authorization to use for this call.

Parameters:

plugin - the customized authorization

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setBody

@Nonnull
public ReST.Builder setBody(@Nullable
                                     java.io.File body)
                              throws InvalidDataException

Set the body of this POST/PUT request.

Parameters:

body - the body to send.

Returns:

this

Throws:

InvalidDataException - The method must not be GET

setBody

@Nonnull
public ReST.Builder setBody(@Nonnull
                                     java.io.File body,
                                     @Nonnull
                                     ContentType contentType,
                                     @Nonnull
                                     DispositionType dispositionType)
                              throws InvalidDataException

Set the body of this POST/PUT request.

Parameters:

body - the body to send.

contentType - the content type to send

dispositionType - the disposition type.

Returns:

this

Throws:

InvalidDataException - The method must not be GET

setBody

@Nonnull
public ReST.Builder setBody(@Nullable
                                     org.w3c.dom.Document bodyXML)
                              throws InvalidDataException

Set the body of this POST/PUT request.

Parameters:

bodyXML - the body to send.

Returns:

this

Throws:

InvalidDataException - The method must not be GET

setBody

@Nonnull
public ReST.Builder setBody(@Nullable
                                     JSONObject bodyJSON)
                              throws InvalidDataException

Throws:

InvalidDataException

setBody

@Nonnull
public ReST.Builder setBody(@Nullable
                                     JSONArray bodyJSONArray)
                              throws InvalidDataException

Throws:

InvalidDataException

setBody

@Nonnull
public ReST.Builder setBody(@Nullable
                                     org.w3c.dom.Document bodyXML,
                                     @Nonnull
                                     ContentType contentType,
                                     @Nonnull
                                     DispositionType dispositionType)
                              throws InvalidDataException

set the body of this POST/PUT request with given contentType and dispositionType

Parameters:

bodyXML - the xml body to send

contentType - content type of this request

dispositionType - disposition type

Returns:

this

Throws:

InvalidDataException - The method must not be GET

setDisableURLLenghCheck

@Nonnull
public ReST.Builder setDisableURLLenghCheck(boolean disable)

setEnableValidateCharactersInURL

@Nonnull
public ReST.Builder setEnableValidateCharactersInURL(boolean enable)

setDisableGZIP

@Nonnull
public ReST.Builder setDisableGZIP(boolean disableGZIP)

true to NOT accept GZIP encoding, default is false

Parameters:

disableGZIP -

Returns:

setTimeout

@Nonnull
public ReST.Builder setTimeout(@Nullable
                                        java.lang.String timeoutPeriod)
                                 throws InvalidDataException

The maximum time to wait. If the request takes too long, a response with Status C504_TIMED_OUT_GATEWAY will return.

Parameters:

timeoutPeriod - the maximum time to block

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setMaxBlockPeriod

@Nonnull
public ReST.Builder setMaxBlockPeriod(@Nullable
                                               java.lang.String maxBlockPeriod)
                                        throws InvalidDataException

Set the maximum time we are prepared to wait for a NEW result. If the call times out the previous result will be used. The request will block forever(max request time ~60 mins) if there is no old cache file. The max block period only has effect when there is a cached version available.

Parameters:

maxBlockPeriod - the maximum time to block

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setStaleBlockPeriod

@Nonnull
public ReST.Builder setStaleBlockPeriod(@Nullable
                                                 java.lang.String staleBlockPeriod)
                                          throws InvalidDataException

The block time before we will use a stale version ( previously cached) of the request response. The stale block time must be greater or equal to the max block period. If there is no cache avaliable for the request then a response with C504_TIMED_OUT_GATEWAY will be returned.

Parameters:

staleBlockPeriod - the maximum time to block. eg 4 min 30 seconds

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setMethod

@Nonnull
public ReST.Builder setMethod(@Nullable
                                       java.lang.String method)
                                throws java.lang.IllegalArgumentException

Set the method to use

Parameters:

method - the method.

Returns:

this builder

Throws:

java.lang.IllegalArgumentException

getMethod

@Nonnull
public Method getMethod()

Get the call method

Returns:

the method

setMethod

@Nonnull
public ReST.Builder setMethod(@Nullable
                                       Method method)
                                throws java.lang.IllegalArgumentException

Set the method to use

Parameters:

method - the method.

Returns:

this builder

Throws:

java.lang.IllegalArgumentException

setAgent

@Nonnull
public ReST.Builder setAgent(@Nullable
                                      java.lang.String agent)

Set the agent to use

Parameters:

agent - the agent.

Returns:

this builder

addQuery

@Nonnull
public ReST.Builder addQuery(@Nonnull
                                      java.lang.String query)
                               throws java.lang.IllegalArgumentException

A ampersand(&) separated list of encoded name/value pairs.

Parameters:

query - the encoded name and value pairs to be added to the call.

Returns:

this

Throws:

java.lang.IllegalArgumentException

addParameter

@Nonnull
public ReST.Builder addParameter(@Nonnull
                                          java.lang.String name,
                                          long value)

Add a parameter

Parameters:

name - the name of the parameter

value - the long value

Returns:

this

setParameter

@Nonnull
public ReST.Builder setParameter(@Nonnull
                                          java.lang.String name,
                                          @Nullable
                                          java.lang.String value)

set a parameter (decoded)

Parameters:

name - the name of the parameter

value - the value

Returns:

this

setParameter

@Nonnull
public ReST.Builder setParameter(@Nonnull
                                          java.lang.String name,
                                          boolean value)

set a Boolean parameter

Parameters:

name - the name of the parameter

value - the value

Returns:

this

setParameter

@Nonnull
public ReST.Builder setParameter(@Nonnull
                                          java.lang.String name,
                                          long value)

set a parameter

Parameters:

name - the name of the parameter

value - the value

Returns:

this

hasParameter

public boolean hasParameter(@Nonnull
                            java.lang.String name)

check if a parameter is set

Parameters:

name - the name of the parameter

Returns:

true if the parameter was set (could be set to an empty String)

getParameterValues

@Nullable
public java.lang.String[] getParameterValues(@Nonnull
                                                       java.lang.String name)

Return the current parameter values.

Parameters:

name - the parameter name

Returns:

the values or NULL if not set.

addParameter

@Nonnull
public ReST.Builder addParameter(@Nonnull
                                          java.lang.String name,
                                          @Nullable
                                          java.lang.String value)

Add a parameter (decoded)

Parameters:

name - the name of the parameter

value - the value

Returns:

this

setMinCachePeriod

@Nonnull
public ReST.Builder setMinCachePeriod(@Nullable
                                               java.lang.String cachePeriod)
                                        throws InvalidDataException

Set the minimum cache period for this request. The server cache period sent will extend this minimum cache period if sent.

Parameters:

cachePeriod - how long to remember the response for this URL.

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setErrorCachePeriod

@Nonnull
public ReST.Builder setErrorCachePeriod(@Nullable
                                                 java.lang.String cachePeriod)
                                          throws InvalidDataException

Set the ERROR cache period for this request

Parameters:

cachePeriod - how long to remember this URL returns an error.

Returns:

this builder

Throws:

InvalidDataException - the duration is not valid

setTransport

@Nonnull
public ReST.Builder setTransport(@Nullable
                                          RestTransport transport)

Sets the underlying transport for this ReST call.

Parameters:

transport - the transport to use.

Returns:

this builder

getContentAsString

@CheckReturnValue
 @Nonnull
public java.lang.String getContentAsString()
                                                                throws java.io.IOException

Fetch a ReST request

Returns:

the resulting data

Throws:

java.io.IOException - a serious problem.

makeFileName

@CheckReturnValue
 @Nonnull
public java.lang.String makeFileName()

make the cache file name.

Returns:

the file name.

correctURL

@Nonnull
 @CheckReturnValue
public static java.net.URL correctURL(@Nonnull
                                                                  java.net.URL url)

toString

@CheckReturnValue
 @Nonnull
public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getResponse

@CheckReturnValue
 @Nonnull
public Response getResponse()

Call the server and return the response. Note you must call checkStatus() determine if the call actually worked. This is the heart of the ReST calls. Before calling the remote server it first checks the local disk cache for the matching request property file. The rest call property file contains the checksum of the results file plus a history of results files for later clean up. If the result file is present and it matches the checksum of when it was cached and the cache period hasn't expired then the previous result can be returned without even calling the server. If the server is to be called then a future task is scheduled for this URL. Other call for the same URL that is made while the server is processing this call will be joined together as one. Previous result files will be cleaned removed only after a period of time has expired to handle possible race conditions when there are multiple calls for the same resource.

Returns:

the response object.

getResponseAndCheck

@CheckReturnValue
 @Nonnull
public Response getResponseAndCheck()
                                                         throws java.io.FileNotFoundException,
                                                                ReSTException

Short hand method to call getResponse() & checkStatus()

Returns:

the response

Throws:

java.io.FileNotFoundException

ReSTException

setCachePath

@Nonnull
public ReST.Builder setCachePath(@Nonnull
                                          java.io.File cachePath)

Set the cache path to use

Parameters:

cachePath - the new cache path

Returns:

this

getCachePath

@Nonnull
 @CheckReturnValue
public java.io.File getCachePath()

What directory should be used for the cache.

Returns:

the file.