com.atlassian.sal.api.net
Interface Request<T extends Request<?,?>,RESP extends Response>

Type Parameters:

T - the type of request used for method chaining

public interface Request<T extends Request<?,?>,RESP extends Response>

Interface Request represents a request to retrieve data. To execute a request call execute(ResponseHandler).

Since:

2.0

Nested Class Summary

static class

Request.MethodType Represents type of network request

Method Summary

T	addAuthentication(Authenticator authenticator) Adds generic Authenticator to the request.
T	addBasicAuthentication(String username, String password) Adds basic authentication to the request.
T	addHeader(String headerName, String headerValue) Adds the specified header to the request, not overwriting any previous value.
T	addRequestParameters(String... params) Sets parameters of the request.
T	addSeraphAuthentication(String username, String password) Adds seraph authentication to the request.
T	addTrustedTokenAuthentication() Adds TrustedTokenAuthentication to the request.
T	addTrustedTokenAuthentication(String username) Adds TrustedTokenAuthentication to the request.
String	execute() Executes a request and if response is successful, returns response as a string.
void	execute(ResponseHandler<RESP> responseHandler) Executes the request.
<RET> RET	executeAndReturn(ReturningResponseHandler<RESP,RET> responseHandler) Executes the request and returns a result value.
Map<String,List<String>>	getHeaders()
T	setConnectionTimeout(int connectionTimeout) Setting connection timeout in milliseconds.
T	setEntity(Object entity) Set an entity as the request body
T	setFiles(List<RequestFilePart> files) Sets file parts of the request.
T	setFollowRedirects(boolean follow) Sets whether the request should transparently follow a redirect from the server.
T	setHeader(String headerName, String headerValue) Sets the specified header to the request, overwriting any previous value.
T	setRequestBody(String requestBody) Sets the body of the request.
T	setRequestContentType(String contentType) Sets Content-Type of the body of the request.
T	setSoTimeout(int soTimeout) Setting socket timeout in milliseconds.
T	setUrl(String url)

Method Detail

setConnectionTimeout

T setConnectionTimeout(int connectionTimeout)

Setting connection timeout in milliseconds.

Parameters:

connectionTimeout - The timeout in milliseconds

Returns:

a reference to this object.

setSoTimeout

T setSoTimeout(int soTimeout)

Setting socket timeout in milliseconds.

Parameters:

soTimeout - the timeout in milliseconds

Returns:

a reference to this object.

setUrl

T setUrl(String url)

Parameters:

url - the url to request

Returns:

a reference to this object.

setRequestBody

T setRequestBody(String requestBody)

Sets the body of the request. In default implementation only requests of type Request.MethodType.POST and Request.MethodType.PUT can have a request body.

Parameters:

requestBody - the body of the request

Returns:

a reference to this object.

setFiles

T setFiles(List<RequestFilePart> files)

Sets file parts of the request. File parts can only be added if the request body is empty. Only requests of type Request.MethodType.POST and Request.MethodType.PUT can have file parts.

Parameters:

files - the file parts, cannot be null.

Returns:

a reference to this object.

Throws:

IllegalArgumentException - if the method of this request is not a POST or PUT or files is NULL.

IllegalStateException - if the request body for this request has already been set.

Since:

2.6

setEntity

T setEntity(Object entity)

Set an entity as the request body

Parameters:

entity - the request entity to be marshalled, not null

Returns:

this Request object

setRequestContentType

T setRequestContentType(String contentType)

Sets Content-Type of the body of the request. In default implementation only requests of type Request.MethodType.POST and Request.MethodType.PUT can have a request body.

Parameters:

contentType - the contentType of the request

Returns:

a reference to this object.

addRequestParameters

T addRequestParameters(String... params)

Sets parameters of the request. In default implementation only requests of type Request.MethodType.POST can have parameters. For other requests include parameters in url. This method accepts an even number of arguments, in form of name, value, name, value, name, value, etc

Parameters:

params - parameters of the request in as name, value pairs

Returns:

a reference to this object.

addAuthentication

T addAuthentication(Authenticator authenticator)

Adds generic Authenticator to the request.

Parameters:

authenticator - the authenticator to use for authentication

Returns:

a reference to this object.

addTrustedTokenAuthentication

T addTrustedTokenAuthentication()

Adds TrustedTokenAuthentication to the request. Trusted token authenticator uses current user to make a trusted application call.

Returns:

a reference to this object.

addTrustedTokenAuthentication

T addTrustedTokenAuthentication(String username)

Adds TrustedTokenAuthentication to the request. Trusted token authenticator uses the passed user to make a trusted application call.

Parameters:

username - The user to make the request with

Returns:

this

addBasicAuthentication

T addBasicAuthentication(String username,
                         String password)

Adds basic authentication to the request.

Parameters:

username - The user name

password - The password

Returns:

a reference to this object.

addSeraphAuthentication

T addSeraphAuthentication(String username,
                          String password)

Adds seraph authentication to the request.

Parameters:

username - The user name

password - The password

Returns:

a reference to this object.

addHeader

T addHeader(String headerName,
            String headerValue)

Adds the specified header to the request, not overwriting any previous value. Support for this operation is optional.

Parameters:

headerName - the header's name

headerValue - the header's value

Returns:

a reference to this object

See Also:

RequestFactory.supportsHeader()

setHeader

T setHeader(String headerName,
            String headerValue)

Sets the specified header to the request, overwriting any previous value. Support for this operation is optional.

Parameters:

headerName - the header's name

headerValue - the header's value

Returns:

a reference to this object

See Also:

RequestFactory.supportsHeader()

setFollowRedirects

T setFollowRedirects(boolean follow)

Sets whether the request should transparently follow a redirect from the server. The default behavior is that when a response is received with a status code in the 300s, a new request is made using the location header of the response without notifying the client. Set this to false to turn this behavior off.

Parameters:

follow - set this to false to have the request not transparently follow redirects.

Returns:

a reference to this object.

getHeaders

Map<String,List<String>> getHeaders()

Returns:

an immutable Map of headers added to the request so far

Since:

2.1

execute

void execute(ResponseHandler<RESP> responseHandler)
             throws ResponseException

Executes the request.

Parameters:

responseHandler - Callback handler of the response.

Throws:

ResponseProtocolException - If the server returned a malformed response

ResponseTimeoutException - If a connection timeout or read timeout occurred

ResponseTransportException - If an I/O error occurred in request transport

ResponseException - For all errors not otherwise specified

execute

String execute()
               throws ResponseException

Executes a request and if response is successful, returns response as a string. @see Response.getResponseBodyAsString()

Returns:

response as String

Throws:

ResponseStatusException - If the server returned a response that contained an error code

ResponseProtocolException - If the server returned a malformed response

ResponseTimeoutException - If a connection timeout or read timeout occurred

ResponseTransportException - If an I/O error occurred in request transport

ResponseException - For all errors not otherwise specified

executeAndReturn

<RET> RET executeAndReturn(ReturningResponseHandler<RESP,RET> responseHandler)
                     throws ResponseException

Executes the request and returns a result value.

Parameters:

responseHandler - Callback handler of the response.

Throws:

ResponseProtocolException - If the server returned a malformed response

ResponseTimeoutException - If a connection timeout or read timeout occurred

ResponseTransportException - If an I/O error occurred in request transport

ResponseException - For all errors not otherwise specified

Since:

v2.2.0