com.atlassian.httpclient.api
Interface Request

All Superinterfaces:

Message

public interface Request
extends Message

An interface for building and executing HTTP requests.

Nested Class Summary

static class

Request.Method

Method Summary

ResponsePromise	delete() Executes this request through the HttpClient service as a DELETE operation.
ResponsePromise	get() Executes this request through the HttpClient service as a GET operation.
java.lang.String	getAccept() Returns this request's Accept header, if set.
java.lang.String	getAttribute(java.lang.String name) Gets an attribute from the request.
java.util.Map<java.lang.String,java.lang.String>	getAttributes() Gets all attributes for this request.
Request.Method	getMethod()
java.net.URI	getUri() Returns this request's URI, if set.
ResponsePromise	head() Executes this request through the HttpClient service as a HEAD operation.
ResponsePromise	options() Executes this request through the HttpClient service as a OPTIONS operation.
ResponsePromise	post() Executes this request through the HttpClient service as a POST operation.
ResponsePromise	put() Executes this request through the HttpClient service as a PUT operation.
Request	setAccept(java.lang.String accept) Sets the Accept header for the request.
Request	setAttribute(java.lang.String name, java.lang.String value) Sets an attribute on the request.
Request	setAttributes(java.util.Map<java.lang.String,java.lang.String> properties) Sets attributes on the request.
Request	setCacheDisabled() Bypasses the cache for this request
Request	setContentCharset(java.lang.String contentCharset) Sets the charset for this object's entity, if any.
Request	setContentType(java.lang.String contentType) Sets the IANA media type, for the current entity, if any.
Request	setEntity(EntityBuilder entityBuilder) Sets the entity and any associated headers from an entity builder.
Request	setEntity(java.lang.String entity) Sets this object's entity stream from a string.
Request	setEntityStream(java.io.InputStream entityStream) Sets this object's entity as an input stream.
Request	setEntityStream(java.io.InputStream entityStream, java.lang.String encoding) Sets this object's entity as an input stream, encoded with the specified charset.
Request	setHeader(java.lang.String name, java.lang.String value) Sets an HTTP header on this object.
Request	setHeaders(java.util.Map<java.lang.String,java.lang.String> headers) Copies the specified map of HTTP headers into this object.
Request	setUri(java.net.URI uri) Sets this request's URI.
ResponsePromise	trace() Executes this request through the HttpClient service as a TRACE operation.

Methods inherited from interface com.atlassian.httpclient.api.Message

getContentCharset, getContentType, getEntity, getEntityStream, getHeader, getHeaders, hasEntity, hasReadEntity, isFrozen

Method Detail

getUri

java.net.URI getUri()

Returns this request's URI, if set.

Returns:

The URI or null if not yet set

setUri

Request setUri(java.net.URI uri)

Sets this request's URI. Must not be null by the time the request is executed.

Parameters:

uri - The URI

Returns:

This object, for builder-style chaining

getAccept

java.lang.String getAccept()

Returns this request's Accept header, if set.

Returns:

The accept header value

setAccept

Request setAccept(java.lang.String accept)

Sets the Accept header for the request.

Parameters:

accept - An accept header expression containing media types, ranges, and/or quality factors

Returns:

This object, for builder-style chaining

setCacheDisabled

Request setCacheDisabled()

Bypasses the cache for this request

Returns:

This object, for builder-style chaining

setAttribute

Request setAttribute(java.lang.String name,
                     java.lang.String value)

Sets an attribute on the request. Attributes are request metadata that are forwarded to the analytics plugin when enabled.

Parameters:

name - The attribute name

value - The attribute value

Returns:

This object, for builder-style chaining

setAttributes

Request setAttributes(java.util.Map<java.lang.String,java.lang.String> properties)

Sets attributes on the request. Attributes are request metadata that are forwarded to the analytics plugin when enabled.

Parameters:

properties - A map of attributes

Returns:

This object, for builder-style chaining

getAttribute

java.lang.String getAttribute(java.lang.String name)

Gets an attribute from the request. Attributes are request metadata that are forwarded to the analytics plugin when enabled.

Parameters:

name - The attribute name

Returns:

The attribute value, or null if not set

getAttributes

java.util.Map<java.lang.String,java.lang.String> getAttributes()

Gets all attributes for this request. Attributes are request metadata that are forwarded to the analytics plugin when enabled.

Returns:

All attributes

setEntity

Request setEntity(EntityBuilder entityBuilder)

Sets the entity and any associated headers from an entity builder.

Parameters:

entityBuilder - An entity builder

Returns:

This object, for builder-style chaining

get

ResponsePromise get()

Executes this request through the HttpClient service as a GET operation. The request SHOULD NOT contain an entity for the GET operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

post

ResponsePromise post()

Executes this request through the HttpClient service as a POST operation. The request SHOULD contain an entity for the POST operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

put

ResponsePromise put()

Executes this request through the HttpClient service as a PUT operation. The request SHOULD contain an entity for the PUT operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

delete

ResponsePromise delete()

Executes this request through the HttpClient service as a DELETE operation. The request SHOULD NOT contain an entity for the DELETE operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

options

ResponsePromise options()

Executes this request through the HttpClient service as a OPTIONS operation. The request MAY contain an entity for the OPTIONS operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

head

ResponsePromise head()

Executes this request through the HttpClient service as a HEAD operation. The request SHOULD NOT contain an entity for the HEAD operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

trace

ResponsePromise trace()

Executes this request through the HttpClient service as a TRACE operation. The request SHOULD contain an entity for the TRACE operation.

Returns:

A promise object that can be used to receive the response and handle exceptions

getMethod

Request.Method getMethod()

setContentType

Request setContentType(java.lang.String contentType)

Description copied from interface: Message

Sets the IANA media type, for the current entity, if any. If the contentType argument also contains charset information, this method will have the side effect of parsing the charset out and storing the component parts independently. The method getContentCharset() can be used to retrieve extracted content charset, if present, and getHeader("Content-Type") can be used to retrieve the entire Content-Type header, complete with charset information, if set. The content type property is required when an entity is present.

Specified by:

setContentType in interface Message

Parameters:

contentType - An IANA media type with optional charset information

Returns:

This object, for builder-style chaining

setContentCharset

Request setContentCharset(java.lang.String contentCharset)

Description copied from interface: Message

Sets the charset for this object's entity, if any. This value is ignored during headeer access if no entity is present or if the content type property is not set.

Specified by:

setContentCharset in interface Message

Parameters:

contentCharset - The entity's charset value, or null

Returns:

This object, for builder-style chaining

setHeaders

Request setHeaders(java.util.Map<java.lang.String,java.lang.String> headers)

Description copied from interface: Message

Copies the specified map of HTTP headers into this object. It will also parse any included Content-Type header into its constituent parts of IANA media type and content charset, updating those properties as appropriate.

Specified by:

setHeaders in interface Message

Parameters:

headers - A map of HTTP headers

Returns:

This object, for builder-style chaining

setHeader

Request setHeader(java.lang.String name,
                  java.lang.String value)

Description copied from interface: Message

Sets an HTTP header on this object. If the header's name is "Content-Type", the value will be parsed into this object's content type and content charset properties, as appropriate.

Specified by:

setHeader in interface Message

Parameters:

name - The name of the header to be set

value - The value of the header to be set

Returns:

This object, for builder-style chaining

setEntity

Request setEntity(java.lang.String entity)

Description copied from interface: Message

Sets this object's entity stream from a string. Using this method of setting the entity automatically sets this object's content charset property to "UTF-8" if the entity is not null.

Specified by:

setEntity in interface Message

Parameters:

entity - An entity string

Returns:

This object, for builder-style chaining

setEntityStream

Request setEntityStream(java.io.InputStream entityStream,
                        java.lang.String encoding)

Description copied from interface: Message

Sets this object's entity as an input stream, encoded with the specified charset. Invocations of this method reset this object's hasReadEntity() state to false. This method should only be called for entity streams targetting textual media types -- that is, it's nonsensical to set the charset of an entity stream for binary media types (e.g. image/*, etc).

Specified by:

setEntityStream in interface Message

Parameters:

entityStream - An entity input stream ready to be read

encoding - The charset in which the entity stream is encoded

Returns:

This object, for builder-style chaining

setEntityStream

Request setEntityStream(java.io.InputStream entityStream)

Description copied from interface: Message

Sets this object's entity as an input stream. Invocations of this method reset this object's hasReadEntity() state to false. It is recommended to also set this object's content charset property when setting an entity stream for a textual media type (or using the overloaded form that takes both the entity stream and charset in the same call). Clients of this object should assume the HTTP standard of ISO-8859-1 (latin-1) for the content charset property if a textual media type is set but no explcit charset was provided for this message. A charset should NOT be provided for entity streams targetting binary media types.

Specified by:

setEntityStream in interface Message

Parameters:

entityStream - An entity input stream ready to be read

Returns:

This object, for builder-style chaining