org.springframework.extensions.webscripts.connector

Class RemoteClient

java.lang.Object

org.springframework.extensions.webscripts.connector.AbstractClient

org.springframework.extensions.webscripts.connector.RemoteClient

All Implemented Interfaces:

Cloneable, Client

public class RemoteClient
extends AbstractClient
implements Cloneable

Remote client bean for retrieving data from URL resources.

Can be used as a Script root object for HTTP methods via ScriptRemote

Generally remote URLs will be "data" webscripts (i.e. returning XML/JSON) called from web-tier script objects or directly from Java backed webscript methods.

Support for HTTP methods of GET, DELETE, PUT and POST of body content data. The Apache commons HttpClient library is used to provide superior handling of large POST body rather than the default JDK implementation.

A 'Response' is returned containing the response data stream as a String and the Status object representing the status code and error information if any. Methods supplying an InputStream will force a POST and methods supplying an OutputStream will stream the result directly to it (i.e. for a proxy) and will not generate a String response in the 'Response' object.

By default this bean has the id of 'connector.remoteclient' and is configured in spring-webscripts-application-context.xml found in the spring-webscripts project.

Version:

5.0 Note since Alfresco 5.0 this was rewritten against Apache HttpClient 4.3

Author:

Kevin Roast

Field Summary

Fields

Modifier and Type	Field and Description
protected static String	CHARSETEQUALS
protected static int	DEFAULT_BUFFERSIZE
protected static int	DEFAULT_CONNECT_TIMEOUT
protected static int	DEFAULT_MAX_REDIRECTS
protected static int	DEFAULT_POOLSIZE
protected static int	DEFAULT_READ_TIMEOUT
protected static String	DEFAULT_REQUEST_CONTENT_TYPE
protected static String	DEFAULT_TICKET_NAME
protected static String	HEADER_CONTENT_LENGTH
protected static String	HEADER_CONTENT_TYPE
protected static String	HEADER_COOKIE
protected static String	HEADER_SERVER
protected static String	HEADER_SET_COOKIE
protected static String	HEADER_TRANSFER_ENCODING
static int	SC_MOVED_PERMANENTLY
static int	SC_MOVED_TEMPORARILY
static int	SC_SEE_OTHER
static int	SC_TEMPORARY_REDIRECT
protected static String	X_WWW_FORM_URLENCODED

Fields inherited from class org.springframework.extensions.webscripts.connector.AbstractClient

endpoint

Constructor Summary

Constructors

Constructor and Description
RemoteClient()

Method Summary

Methods

Modifier and Type	Method and Description
protected URL	buildURL(String uri) Build the URL object based on the supplied uri and configured endpoint.
Response	call(String uri) Call a remote WebScript uri.
Response	call(String uri, boolean buildResponseString, InputStream in) Call a remote WebScript uri.
Response	call(String uri, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Call a remote WebScript uri.
Response	call(String uri, InputStream in) Call a remote WebScript uri.
Response	call(String uri, InputStream in, OutputStream out) Call a remote WebScript uri.
Response	call(String uri, OutputStream out) Call a remote WebScript uri.
Response	call(String uri, String body) Call a remote WebScript uri, passing the supplied body as a POST request (unless the request method is set to override as say PUT).
Object	clone() Clone a RemoteClient and all the properties.
protected void	copyResponseStreamOutput(URL url, javax.servlet.http.HttpServletResponse res, OutputStream out, org.apache.http.HttpResponse response, String contentType, int bufferSize) Copy response stream to the output
protected org.apache.http.client.HttpClient	createHttpClient(URL url) Create and configure an HttpClient per thread based on Pooled connection manager.
protected static org.apache.http.HttpHost	createProxyHost(String hostProperty, String portProperty, int defaultPort) Create HTTP proxy host for the given system host and port properties.
ConfigService	getConfigService()
Map<String,String>	getCookies() Gets the current set of cookies for state transfer.
int	getPoolSize()
String	getRequestContentType()
HttpMethod	getRequestMethod()
String	getTicket() Returns the authentication ticket
String	getTicketName()
void	init()
protected void	processContentType(URL url, javax.servlet.http.HttpServletResponse res, org.apache.http.Header contentType) Optional additional processing based on the contentType header
protected URL	processResponse(URL url, org.apache.http.HttpResponse response) Pre-processes the response, propagating cookies and deciding whether a redirect is required
void	setAllowHttpProxy(boolean allowHttpProxy)
void	setAllowHttpsProxy(boolean allowHttpsProxy)
void	setBufferSize(int bufferSize)
void	setCommitResponseOnAuthenticationError(boolean commitResponseOnAuthenticationError)
void	setConfigService(ConfigService configService)
void	setConnectTimeout(int connectTimeout)
void	setCookies(Map<String,String> cookies) Provides a set of cookies for state transfer.
void	setDefaultContentType(String defaultContentType)
void	setDefaultEncoding(String defaultEncoding)
void	setExceptionOnError(boolean exceptionOnError)
void	setHttpConnectionStalecheck(boolean httpConnectionStalecheck)
void	setHttpTcpNodelay(boolean httpTcpNodelay)
void	setMaxRedirects(int maxRedirects)
void	setPoolSize(int poolSize)
void	setReadTimeout(int readTimeout)
void	setRemoveRequestHeaders(Set<String> removeRequestHeaders)
void	setRemoveResponseHeaders(Set<String> removeResponseHeaders)
void	setRequestContentType(String contentType)
void	setRequestHeaders(Map<String,String> requestHeaders) Configuration of custom request headers to be applied to each request.
void	setRequestMethod(HttpMethod method)
void	setRequestProperties(Map<String,String> requestProperties) Allows for additional request properties to be set onto this object These request properties are applied to the connection when the connection is called.
void	setTicket(String ticket) Sets the authentication ticket to use.
void	setTicketName(String ticketName) Sets the authentication ticket name to use.
void	setUsernamePassword(String user, String pass) Basic HTTP auth.

Methods inherited from class org.springframework.extensions.webscripts.connector.AbstractClient

getEndpoint, getURL, setEndpoint

Methods inherited from class java.lang.Object

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

Field Detail

HEADER_TRANSFER_ENCODING

protected static final String HEADER_TRANSFER_ENCODING

See Also:

Constant Field Values

HEADER_CONTENT_LENGTH

protected static final String HEADER_CONTENT_LENGTH

See Also:

Constant Field Values

HEADER_CONTENT_TYPE

protected static final String HEADER_CONTENT_TYPE

See Also:

Constant Field Values

HEADER_SET_COOKIE

protected static final String HEADER_SET_COOKIE

See Also:

Constant Field Values

HEADER_COOKIE

protected static final String HEADER_COOKIE

See Also:

Constant Field Values

HEADER_SERVER

protected static final String HEADER_SERVER

See Also:

Constant Field Values

DEFAULT_CONNECT_TIMEOUT

protected static final int DEFAULT_CONNECT_TIMEOUT

See Also:

Constant Field Values

DEFAULT_READ_TIMEOUT

protected static final int DEFAULT_READ_TIMEOUT

See Also:

Constant Field Values

DEFAULT_BUFFERSIZE

protected static final int DEFAULT_BUFFERSIZE

See Also:

Constant Field Values

DEFAULT_MAX_REDIRECTS

protected static final int DEFAULT_MAX_REDIRECTS

See Also:

Constant Field Values

DEFAULT_POOLSIZE

protected static final int DEFAULT_POOLSIZE

See Also:

Constant Field Values

DEFAULT_TICKET_NAME

protected static final String DEFAULT_TICKET_NAME

See Also:

Constant Field Values

DEFAULT_REQUEST_CONTENT_TYPE

protected static final String DEFAULT_REQUEST_CONTENT_TYPE

See Also:

Constant Field Values

X_WWW_FORM_URLENCODED

protected static final String X_WWW_FORM_URLENCODED

See Also:

Constant Field Values

CHARSETEQUALS

protected static final String CHARSETEQUALS

See Also:

Constant Field Values

SC_MOVED_TEMPORARILY

public static final int SC_MOVED_TEMPORARILY

See Also:

Constant Field Values

SC_MOVED_PERMANENTLY

public static final int SC_MOVED_PERMANENTLY

See Also:

Constant Field Values

SC_SEE_OTHER

public static final int SC_SEE_OTHER

See Also:

Constant Field Values

SC_TEMPORARY_REDIRECT

public static final int SC_TEMPORARY_REDIRECT

See Also:

Constant Field Values

Constructor Detail

RemoteClient

public RemoteClient()

Method Detail

init

public void init()

clone

public Object clone()
             throws CloneNotSupportedException

Clone a RemoteClient and all the properties.

This method is preferable in hot code to requesting a new copy of the "connector.remoteclient" bean from Spring - as the bean makes use of the prototype pattern and is quite expensive to create each time - also the Spring code has synchronization during the bean creation pattern which is additionally expensive during heavily threaded applications.

This clone method will only duplicate the non-stateful members of RemoteClient i.e. the same properties that would have been set by Spring during bean initialisation.

Overrides:

clone in class Object

Throws:

CloneNotSupportedException

setConfigService

public void setConfigService(ConfigService configService)

getConfigService

public ConfigService getConfigService()

setTicketName

public void setTicketName(String ticketName)

Sets the authentication ticket name to use. Will be used for all future call() requests. This allows the ticket mechanism to be repurposed for non-Alfresco implementations that may require similar argument passing

Parameters:

ticketName - String

getTicketName

public String getTicketName()

Returns:

the authentication ticket name to use

setDefaultEncoding

public void setDefaultEncoding(String defaultEncoding)

Parameters:

defaultEncoding - the defaultEncoding to set

setDefaultContentType

public void setDefaultContentType(String defaultContentType)

Parameters:

defaultContentType - the defaultContentType to set

setBufferSize

public void setBufferSize(int bufferSize)

Parameters:

bufferSize - the bufferSize to set

setConnectTimeout

public void setConnectTimeout(int connectTimeout)

Parameters:

connectTimeout - the connectTimeout to set

setReadTimeout

public void setReadTimeout(int readTimeout)

Parameters:

readTimeout - the readTimeout to set

setMaxRedirects

public void setMaxRedirects(int maxRedirects)

Parameters:

maxRedirects - the maxRedirects to set

getPoolSize

public int getPoolSize()

Returns:

the connection thread pool size

setPoolSize

public void setPoolSize(int poolSize)

Parameters:

poolSize - the connection thread pool size to set

setAllowHttpProxy

public void setAllowHttpProxy(boolean allowHttpProxy)

Parameters:

allowHttpProxy - allowHttpProxy to set

setAllowHttpsProxy

public void setAllowHttpsProxy(boolean allowHttpsProxy)

Parameters:

allowHttpsProxy - allowHttpsProxy to set

setRemoveRequestHeaders

public void setRemoveRequestHeaders(Set<String> removeRequestHeaders)

Parameters:

removeRequestHeaders - the removeRequestHeaders to set

setRemoveResponseHeaders

public void setRemoveResponseHeaders(Set<String> removeResponseHeaders)

Parameters:

removeResponseHeaders - the removeResponseHeaders to set

setTicket

public void setTicket(String ticket)

Sets the authentication ticket to use. Will be used for all future call() requests.

Parameters:

ticket - String

getTicket

public String getTicket()

Returns the authentication ticket

Returns:

String

setUsernamePassword

public void setUsernamePassword(String user,
                       String pass)

Basic HTTP auth. Will be used for all future call() requests.

Parameters:

user - String

pass - String

setRequestContentType

public void setRequestContentType(String contentType)

Parameters:

contentType - the POST request "Content-Type" header value to set NOTE: this value is reset to the defaultContentType value after a call() is made.

getRequestContentType

public String getRequestContentType()

setRequestMethod

public void setRequestMethod(HttpMethod method)

Parameters:

method - the request Method to set i.e. one of GET/POST/PUT/DELETE etc. if not set, GET will be assumed unless an InputStream is supplied during call() in which case POST will be used unless the request method overrides it with PUT. NOTE: this value is reset to the default of GET after a call() is made.

getRequestMethod

public HttpMethod getRequestMethod()

Returns:

the current Request Method

setRequestProperties

public void setRequestProperties(Map<String,String> requestProperties)

Allows for additional request properties to be set onto this object These request properties are applied to the connection when the connection is called. Will be used for all future call() requests.

Parameters:

requestProperties - map of request properties to set

setRequestHeaders

public void setRequestHeaders(Map<String,String> requestHeaders)

Configuration of custom request headers to be applied to each request. The request properties set programmatically above at runtime will augment and override these configuration defaults.

Parameters:

requestHeaders - map of request headers to set

setCookies

public void setCookies(Map<String,String> cookies)

Provides a set of cookies for state transfer. This set of cookies is maintained through any redirects followed by the client (e.g. redirect through SSO host).

Parameters:

cookies - the cookies

getCookies

public Map<String,String> getCookies()

Gets the current set of cookies for state transfer. This set of cookies is maintained through any redirects followed by the client (e.g. redirect through SSO host).

Returns:

the cookies

setHttpTcpNodelay

public void setHttpTcpNodelay(boolean httpTcpNodelay)

Parameters:

httpTcpNodelay - Value for the http.tcp.nodelay setting - default is true

setHttpConnectionStalecheck

public void setHttpConnectionStalecheck(boolean httpConnectionStalecheck)

Parameters:

httpConnectionStalecheck - Value for the http.connection.stalecheck setting - default is true

setCommitResponseOnAuthenticationError

public void setCommitResponseOnAuthenticationError(boolean commitResponseOnAuthenticationError)

Parameters:

commitResponseOnAuthenticationError - true to commit the response if a 401 error is returned, false otherwise.

setExceptionOnError

public void setExceptionOnError(boolean exceptionOnError)

Parameters:

exceptionOnError - true to throw an exception on a server 500 response - else return 500 code in the usual Response object.

call

public Response call(String uri)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url. This API is generally called from a script host.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

Returns:

Response object from the call Response

call

public Response call(String uri,
            String body)

Call a remote WebScript uri, passing the supplied body as a POST request (unless the request method is set to override as say PUT).

Parameters:

uri - Uri to call on the endpoint

body - Body of the POST request.

Returns:

Response object from the call Response

call

public Response call(String uri,
            InputStream in)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

in - The optional InputStream to the call - if supplied a POST will be performed

Returns:

Response object from the call Response

call

public Response call(String uri,
            boolean buildResponseString,
            InputStream in)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

buildResponseString - True to build a String result automatically based on the response encoding, false to instead return the InputStream in the Response.

in - The optional InputStream to the call - if supplied a POST will be performed

Returns:

Response object from the call Response

call

public Response call(String uri,
            OutputStream out)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

out - OutputStream to stream successful response to - will be closed automatically. A response data string will not therefore be available in the Response object. If remote call fails the OutputStream will not be modified or closed.

Returns:

Response object from the call Response

call

public Response call(String uri,
            InputStream in,
            OutputStream out)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

in - The optional InputStream to the call - if supplied a POST will be performed

out - OutputStream to stream response to - will be closed automatically. A response data string will not therefore be available in the Response object. If remote call returns a status code then any available error response will be streamed into the output. If remote call fails completely the OutputStream will not be modified or closed.

Returns:

Response object from the call Response

call

public Response call(String uri,
            javax.servlet.http.HttpServletRequest req,
            javax.servlet.http.HttpServletResponse res)

Call a remote WebScript uri. The endpoint as supplied in the constructor will be used as the prefix for the full WebScript url.

Parameters:

uri - WebScript URI - for example /test/myscript?arg=value

req - HttpServletRequest the request to retrieve input and headers etc. from

res - HttpServletResponse the response to stream response to - will be closed automatically. A response data string will not therefore be available in the Response object. The HTTP method to be used should be set via the setter otherwise GET will be assumed and the InputStream will not be retrieve from the request. If remote call returns a status code then any available error response will be streamed into the response object. If remote call fails completely the OutputStream will not be modified or closed.

Returns:

Response object from the call Response

processResponse

protected URL processResponse(URL url,
                  org.apache.http.HttpResponse response)
                       throws MalformedURLException

Pre-processes the response, propagating cookies and deciding whether a redirect is required

Parameters:

url - URL that was executed

response - the executed HttpResponse from the method

Throws:

MalformedURLException

buildURL

protected URL buildURL(String uri)
                throws MalformedURLException

Build the URL object based on the supplied uri and configured endpoint. Ticket will be appiled as an argument if available.

Parameters:

uri - URI to build URL against

Returns:

the URL object representing the call.

Throws:

MalformedURLException

copyResponseStreamOutput

protected void copyResponseStreamOutput(URL url,
                            javax.servlet.http.HttpServletResponse res,
                            OutputStream out,
                            org.apache.http.HttpResponse response,
                            String contentType,
                            int bufferSize)
                                 throws IOException

Copy response stream to the output

Parameters:

url - The URL object that the response was retrieved from

res - The HttpServletResponse (can be null for in-memory response processing)

out - The OutputStream to use

response - The HttpResponse from the Method that was executed - will retrieve entity as stream

contentType - The ContentType value of the response

bufferSize - The buffer size to use

Throws:

IOException

processContentType

protected void processContentType(URL url,
                      javax.servlet.http.HttpServletResponse res,
                      org.apache.http.Header contentType)

Optional additional processing based on the contentType header

Parameters:

url - Source URL that was requested

res - The response (unprocessed as yet)

contentType - Content-Type header from the response

createHttpClient

protected org.apache.http.client.HttpClient createHttpClient(URL url)

Create and configure an HttpClient per thread based on Pooled connection manager. Proxy route will be applied the client based on current settings.

Parameters:

url - URL

Returns:

HttpClient

createProxyHost

protected static org.apache.http.HttpHost createProxyHost(String hostProperty,
                                       String portProperty,
                                       int defaultPort)

Create HTTP proxy host for the given system host and port properties. If the properties are not set, no proxy will be created.

Parameters:

hostProperty - String

portProperty - String

defaultPort - int

Returns:

HttpHost if appropriate properties have been set, null otherwise