sirius.web.http

Class Response

java.lang.Object

sirius.web.http.Response

public class Response
extends Object

Represents a response which is used to reply to a HTTP request.

Responses are created by calling WebContext.respondWith().

See Also:

WebContext

Field Summary

Fields

Modifier and Type	Field and Description
protected static com.ning.http.client.AsyncHttpClient	asyncClient
static int	BUFFER_SIZE Size of the internally used transfer buffers
protected Integer	cacheSeconds
protected ChannelHandlerContext	ctx
protected boolean	download
static int	HTTP_CACHE Default cache duration for responses which can be cached
static int	HTTP_CACHE_INFINITE Expires value used to indicate that a resource can be infinitely long cached
protected boolean	isPrivate
protected String	name
protected boolean	responseChunked
protected WebContext	wc

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Response(WebContext wc) Creates a new response for the given request.

Method Summary

Modifier and Type	Method and Description
Response	addHeader(CharSequence name, Object value) Adds the specified header.
Response	addHeaderIfNotExists(CharSequence name, Object value) Only adds the given header if no header with the given name does exist yet.
Response	cached() Marks this response as cachable.
Response	cachedForSeconds(int numberOfSeconds) Marks this response as cachable for the given amount of time.
protected boolean	canBeCompressed(String contentType)
protected static void	closeAsyncClient()
protected ChannelFuture	commit(HttpResponse response)
protected ChannelFuture	commit(HttpResponse response, boolean flush)
protected void	complete(ChannelFuture future)
protected void	contentionAwareWrite(Object message) Writes the given message probably a chunk of output data into the channel.
protected DefaultHttpResponse	createChunkedResponse(HttpResponseStatus status, boolean keepalive)
protected DefaultFullHttpResponse	createFullResponse(HttpResponseStatus status, boolean keepalive, ByteBuf buffer)
protected DefaultHttpResponse	createResponse(HttpResponseStatus status, boolean keepalive)
void	direct(HttpResponseStatus status, String content) Directly sends the given string as response, without any content type.
Response	download(String name) Instructs the browser to treat the response as download with the given file name.
void	error(HttpResponseStatus status) Sends the given HTTP status as error.
void	error(HttpResponseStatus status, sirius.kernel.health.HandledException t) Sends the given HTTP status as error.
void	error(HttpResponseStatus status, String message) Sends the given HTTP status as error.
void	file(File file) Sends the given file as response.
protected static com.ning.http.client.AsyncHttpClient	getAsyncClient()
protected SimpleDateFormat	getHTTPDateFormat()
boolean	handleIfModifiedSince(long lastModifiedInMillis) Determines if the given modified date is past the If-Modified-Since header of the request.
protected HttpHeaders	headers()
Response	headers(sirius.kernel.commons.MultiMap<String,Object> inputHeaders) Adds all given headers
Response	infinitelyCached() Marks this response as infinitely cachable.
Response	inline(String name) Instructs the browser to treat the response as inline-download with the given file name.
protected void	installChunkedWriteHandler()
protected void	internalServerError(String debugMessage, Throwable t)
JSONStructuredOutput	json() Creates a JSON output which can be used to generate well formed json.
Response	named(String name) Forces the use of a given name.
Response	noKeepalive() Disables keep-alive protocol (even if it would have been otherwise supported).
Response	notCached() Marks this response as not-cachable.
OutputStream	outputStream(HttpResponseStatus status, String contentType) Creates an OutputStream which is sent to the client.
Response	privateCached() Marks this response as only privately cachable (only the browser may cache it, but not a proxy etc.)
void	redirectPermanently(String url) Sends a 301 (permanent redirect) to the given url as result.
void	redirectTemporarily(String url) Sends a 307 (temporary redirect) or 302 (found) to the given url as result, depending on the given HTTP protocol in the request.
void	redirectToGet(String url) Sends 302 (found) to the given url as result.
void	resource(URLConnection urlConnection) Sends the given resource (potentially from classpath) as result.
void	sendContent(String name) Tries to resolve the given name into a Resource using the Resources lookup framework.
protected void	sendTemplateContent(HttpResponseStatus status, String name, String content)
protected void	setContentDisposition(String name, boolean download)
protected void	setContentTypeHeader(String name)
protected void	setDateAndCacheHeaders(long lastModifiedMillis, int cacheSeconds, boolean isPrivate)
Response	setHeader(CharSequence name, Object value) Sets the specified header.
void	status(HttpResponseStatus status) Completes this response by sending the given status code without any content
void	template(HttpResponseStatus status, String name, Object... params) Renders the given template and sends the output as response.
void	template(HttpResponseStatus status, Template template, Object... params) Renders the given Rythm template and sends the output as response.
void	template(String name, Object... params) Renders the given template and sends the output as response.
String	toString()
void	tunnel(String url) Tunnels the contents retrieved from the given URL as result of this response.
void	tunnel(String url, Consumer<Integer> failureHandler) Tunnels the contents retrieved from the given URL as result of this response.
void	unauthorized(String realm) Sends an 401 UNAUTHORIZED response with a WWW-Authenticate header for the given realm.
sirius.kernel.xml.XMLStructuredOutput	xml() Creates a XML output which can be used to generate well formed XML.

Methods inherited from class java.lang.Object

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

Field Detail

HTTP_CACHE

public static final int HTTP_CACHE

Default cache duration for responses which can be cached

See Also:

Constant Field Values

HTTP_CACHE_INFINITE

public static final int HTTP_CACHE_INFINITE

Expires value used to indicate that a resource can be infinitely long cached

See Also:

Constant Field Values

BUFFER_SIZE

public static final int BUFFER_SIZE

Size of the internally used transfer buffers

See Also:

Constant Field Values

wc

protected WebContext wc

ctx

protected ChannelHandlerContext ctx

cacheSeconds

protected Integer cacheSeconds

isPrivate

protected boolean isPrivate

download

protected boolean download

name

protected String name

responseChunked

protected boolean responseChunked

asyncClient

protected static com.ning.http.client.AsyncHttpClient asyncClient

Constructor Detail

Response

protected Response(WebContext wc)

Creates a new response for the given request.

Parameters:

wc - the context representing the request for which this response is created

Method Detail

createFullResponse

protected DefaultFullHttpResponse createFullResponse(HttpResponseStatus status,
                                                     boolean keepalive,
                                                     ByteBuf buffer)

createResponse

protected DefaultHttpResponse createResponse(HttpResponseStatus status,
                                             boolean keepalive)

createChunkedResponse

protected DefaultHttpResponse createChunkedResponse(HttpResponseStatus status,
                                                    boolean keepalive)

commit

protected ChannelFuture commit(HttpResponse response)

commit

protected ChannelFuture commit(HttpResponse response,
                               boolean flush)

noKeepalive

public Response noKeepalive()

Disables keep-alive protocol (even if it would have been otherwise supported).

Returns:

the response itself for fluent method calls

complete

protected void complete(ChannelFuture future)

handleIfModifiedSince

public boolean handleIfModifiedSince(long lastModifiedInMillis)

Determines if the given modified date is past the If-Modified-Since header of the request. If not the request is auto-completed with a 304 status (NOT_MODIFIED)

Parameters:

lastModifiedInMillis - the modification date of the resource being delivered

Returns:

true if the request was answered via a 304, false otherwise

named

public Response named(String name)

Forces the use of a given name. This is also used to derive the mime type.

Parameters:

name - the file name to use

Returns:

this to fluently create the response

download

public Response download(@Nullable
                         String name)

Instructs the browser to treat the response as download with the given file name.

Parameters:

name - the file name to send to the browser. If the given name is null nothing happens (We won't force a download).

Returns:

this to fluently create the response

inline

public Response inline(String name)

Instructs the browser to treat the response as inline-download with the given file name.

Parameters:

name - the file name to send to the browser

Returns:

this to fluently create the response

notCached

public Response notCached()

Marks this response as not-cachable.

Returns:

this to fluently create the response

privateCached

public Response privateCached()

Marks this response as only privately cachable (only the browser may cache it, but not a proxy etc.)

Returns:

this to fluently create the response

cachedForSeconds

public Response cachedForSeconds(int numberOfSeconds)

Marks this response as cachable for the given amount of time.

Parameters:

numberOfSeconds - the number of seconds the response might be cached

Returns:

this to fluently create the response

cached

public Response cached()

Marks this response as cachable.

Returns:

this to fluently create the response

infinitelyCached

public Response infinitelyCached()

Marks this response as infinitely cachable.

This suggests that it will never change.

Returns:

this to fluently create the response

setHeader

public Response setHeader(CharSequence name,
                          Object value)

Sets the specified header.

Parameters:

name - name of the header

value - value of the header

Returns:

this to fluently create the response

headers

protected HttpHeaders headers()

addHeader

public Response addHeader(CharSequence name,
                          Object value)

Adds the specified header.

In contrast to setHeader(CharSequence, Object) this method can be called multiple times for the same header and its values will be concatenated as specified in the HTTP protocol.

Parameters:

name - name of the header

value - value of the header

Returns:

this to fluently create the response

addHeaderIfNotExists

public Response addHeaderIfNotExists(CharSequence name,
                                     Object value)

Only adds the given header if no header with the given name does exist yet.

Parameters:

name - name of the header

value - value of the header

Returns:

this to fluently create the response

headers

public Response headers(sirius.kernel.commons.MultiMap<String,Object> inputHeaders)

Adds all given headers

Parameters:

inputHeaders - headers to add

Returns:

this to fluently create the response

status

public void status(HttpResponseStatus status)

Completes this response by sending the given status code without any content

Parameters:

status - the HTTP status to sent

redirectTemporarily

public void redirectTemporarily(String url)

Sends a 307 (temporary redirect) or 302 (found) to the given url as result, depending on the given HTTP protocol in the request.

If contrast to redirectToGet(String), this uses 307 as status code - if possible (HTTP 1.1). This will re-issue the same request method which was made to trigger the original request.

Parameters:

url - the URL to redirect to

redirectToGet

public void redirectToGet(String url)

Sends 302 (found) to the given url as result.

In contrast to redirectTemporarily(String), which uses 307 as HTTP response code, a 302 will cause the browser to always GET as method to access the new URL. A 307 preserves the method and e.g. keeps a POST as being a POST.

Parameters:

url - the URL to redirect to

redirectPermanently

public void redirectPermanently(String url)

Sends a 301 (permanent redirect) to the given url as result.

Parameters:

url - the URL to redirect to

canBeCompressed

protected boolean canBeCompressed(String contentType)

installChunkedWriteHandler

protected void installChunkedWriteHandler()

file

public void file(File file)

Sends the given file as response.

Based on the file, full HTTP caching is supported, taking care of If-Modified-Since headers etc.

If the request does not use HTTPS, the server tries to support a zero-copy approach leading to maximal throughput as no copying between user space and kernel space buffers is required.

Parameters:

file - the file to send

internalServerError

protected void internalServerError(String debugMessage,
                                   Throwable t)

setDateAndCacheHeaders

protected void setDateAndCacheHeaders(long lastModifiedMillis,
                                      int cacheSeconds,
                                      boolean isPrivate)

getHTTPDateFormat

protected SimpleDateFormat getHTTPDateFormat()

setContentDisposition

protected void setContentDisposition(String name,
                                     boolean download)

setContentTypeHeader

protected void setContentTypeHeader(String name)

sendContent

public void sendContent(String name)

Tries to resolve the given name into a Resource using the Resources lookup framework.

Sends the resource found or a 404 NOT_FOUND otherwise.

Parameters:

name - the path of the resource to lookup

resource

public void resource(URLConnection urlConnection)

Sends the given resource (potentially from classpath) as result.

This will support HTTP caching if enabled (default).

Parameters:

urlConnection - the connection to get the data from.

unauthorized

public void unauthorized(String realm)

Sends an 401 UNAUTHORIZED response with a WWW-Authenticate header for the given realm.

This will generally force the client to perform a HTTP Basic authentication.

Parameters:

realm - the realm to report to the client. This will be used to select an appropriate username and password

error

public void error(HttpResponseStatus status)

Sends the given HTTP status as error.

If possible a specific template /view/errors/ERRORCODE.html. If not available, /view/errors/default.html will be rendered.

Parameters:

status - the HTTP status to send.

error

public void error(HttpResponseStatus status,
                  sirius.kernel.health.HandledException t)

Sends the given HTTP status as error. Uses the given exception to provide further insight what went wrong.

If possible a specific template /view/errors/ERRORCODE.html. If not available, /view/errors/default.html will be rendered.

Parameters:

status - the HTTP status to send

t - the exception to display. Use Exceptions to create a handled exception.

error

public void error(HttpResponseStatus status,
                  String message)

Sends the given HTTP status as error. Uses the given message to provide further insight what went wrong.

If possible a specific template /view/errors/ERRORCODE.html. If not available, /view/errors/default.html will be rendered.

Parameters:

status - the HTTP status to send

message - A message or description of what went wrong

direct

public void direct(HttpResponseStatus status,
                   String content)

Directly sends the given string as response, without any content type. Enable the caller to close the underlying channel (without caring about keep-alive). This can be used to report errors as JSON result to AJAX callers.

This should only be used when really required (meaning when you really know what you're doing. The encoding used will be UTF-8).

Parameters:

status - the HTTP status to send

content - the string contents to send.

template

public void template(String name,
                     Object... params)

Renders the given template and sends the output as response.

By default caching will be disabled. If the file ends with .html, text/html; charset=UTF-8 will be set as content type. Otherwise the content type will be guessed from the filename.

Parameters:

name - the name of the template to render. It's recommended to use files in /templates/... and to place them in the resources directory.

params - contains the parameters sent to the template

template

public void template(HttpResponseStatus status,
                     String name,
                     Object... params)

Renders the given template and sends the output as response.

By default caching will be disabled. If the file ends with .html, text/html; charset=UTF-8 will be set as content type. Otherwise the content type will be guessed from the filename.

Parameters:

status - the HTTP status to send. HttpResponseStatus.OK would be appropriate in most cases.

name - the name of the template to render. It's recommended to use files in /templates/... and to place them in the resources directory.

params - contains the parameters sent to the template

See Also:

template(String, Object...)

template

public void template(HttpResponseStatus status,
                     Template template,
                     Object... params)

Renders the given Rythm template and sends the output as response.

By default caching will be disabled. If the file ends with .html, text/html; charset=UTF-8 will be set as content type. Otherwise the content type will be guessed from the filename.

Parameters:

status - the HTTP status to send. HttpResponseStatus.OK would be appropriate in most cases.

template - the template to render

params - contains the parameters sent to the template

See Also:

template(HttpResponseStatus, String, Object...)

sendTemplateContent

protected void sendTemplateContent(HttpResponseStatus status,
                                   String name,
                                   String content)

getAsyncClient

protected static com.ning.http.client.AsyncHttpClient getAsyncClient()

closeAsyncClient

protected static void closeAsyncClient()

tunnel

public void tunnel(String url)

Tunnels the contents retrieved from the given URL as result of this response.

Caching and range headers will be forwarded and adhered.

Uses non-blocking APIs in order to maximize throughput. Therefore this can be called in an unforked dispatcher.

Parameters:

url - the url to tunnel through.

tunnel

public void tunnel(String url,
                   @Nullable
                   Consumer<Integer> failureHandler)

Tunnels the contents retrieved from the given URL as result of this response.

Caching and range headers will be forwarded and adhered.

Uses non-blocking APIs in order to maximize throughput. Therefore this can be called in an unforked dispatcher.

If the called URL returns an error (>= 400) and the given failureHandler is non null, it is supplied with the status code and can re-try or answer the request by itself.

Parameters:

url - the url to tunnel through.

failureHandler - supplies a handler which is invoked if the called URL fails. The handler is provided with the HTTP status code and can (and must) handle the request on its own. It is save to call WebContext.respondWith() again for the request, as no response was created yet.

json

public JSONStructuredOutput json()

Creates a JSON output which can be used to generate well formed json.

By default, caching will be disabled. If the generated JSON is small enough, it will be transmitted in one go. Otherwise a chunked response will be sent.

Returns:

a structured output which will be sent as JSON response

xml

public sirius.kernel.xml.XMLStructuredOutput xml()

Creates a XML output which can be used to generate well formed XML.

By default, caching will be disabled. If the generated XML is small enough, it will be transmitted in one go. Otherwise a chunked response will be sent.

Returns:

a structured output which will be sent as XML response

outputStream

public OutputStream outputStream(HttpResponseStatus status,
                                 @Nullable
                                 String contentType)

Creates an OutputStream which is sent to the client.

If the contents are small enough, everything will be sent in one response. Otherwise a chunked response will be sent. The size of the underlying buffer will be determined by BUFFER_SIZE.

By default, caching will be supported.

Parameters:

status - the HTTP status to send

contentType - the content type to use. If null, we rely on a previously set header.

Returns:

an output stream which will be sent as response

contentionAwareWrite

protected void contentionAwareWrite(Object message)

Writes the given message probably a chunk of output data into the channel.

If the channel buffer is full (not writeable anymore) we need to trigger a flush, so that the data is shovelled into the network. If this doesn't clear up the buffer immediatelly, we block the current thread to throttle the application until free space is available again.

Note that this method must not be invoked in the event loop as otherwise a deadlock might occur. Therefore all dispatchers now always for a new thread to handle requests.

Parameters:

message - the data to sent

toString

public String toString()

Overrides:

toString in class Object