org.osgl.http

Class H.Response<T extends H.Response>

java.lang.Object

org.osgl.http.H.Response<T>

Direct Known Subclasses:

ServletResponse

Enclosing class:

H

public abstract static class H.Response<T extends H.Response>
extends Object

Defines the HTTP response trait

Field Summary

Fields

Modifier and Type	Field and Description
protected org.osgl.util.Output	output
protected OutputStream	outputStream
protected Writer	writer

Constructor Summary

Constructors

Constructor and Description
H.Response()

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract Class<T>	_impl() Returns the class of the implementation.
protected abstract void	_setContentType(String type) Sub class to overwrite this method to set content type to the response
protected abstract void	_setLocale(Locale loc) Sets the locale of the response, setting the headers (including the Content-Type’s charset) as appropriate.
abstract void	addCookie(H.Cookie cookie) Adds the specified cookie to the response.
abstract T	addHeader(String name, String value) Adds a response header with the given name and value.
T	addHeaderIfNotAdded(String name, String value) Adds a response header with given name and value if the header with the same name has not been added yet
String	buildContentDispositionString(String filename, boolean inline)
abstract String	characterEncoding() Returns the name of the character encoding (MIME charset) used for the body sent in this response.
abstract T	characterEncoding(String encoding) Returns the content type used for the MIME body sent in this response.
void	close() Close output or outputStream or writer opened on this response
abstract void	commit() Calling this method commits the response, meaning the status code and headers will be written to the client
abstract boolean	containsHeader(String name) Returns a boolean indicating whether the named response header has already been set.
T	contentDisposition(String filename, boolean inline)
abstract T	contentLength(long len) Set the length of the content to be write to the response
T	contentType(String type) Sets the content type of the response being sent to the client.
<CONTEXT> CONTEXT	context() Get the context object from the response instance
T	context(Object context) Attach a context object to the response instance
protected abstract org.osgl.util.Output	createOutput()
protected abstract OutputStream	createOutputStream()
protected Writer	createWriter()
static <T extends H.Response> T	current() Return a request instance of the current execution context, For example from a ThreadLocal
static <T extends H.Response> void	current(T response) Set a request instance into the current execution context, for example into a ThreadLocal
T	etag(String etag) Set the etag header
abstract T	header(String name, String value) Sets a response header with the given name and value.
T	initContentType(String type) This method set the content type to the response if there is no content type been set already.
abstract Locale	locale() Returns the locale assigned to the response.
T	locale(Locale locale)
protected T	me()
org.osgl.util.Output	output() Returns the output to write to the response.
boolean	outputCreated()
OutputStream	outputStream() Returns the output stream to write to the response.
boolean	outputStreamCreated()
T	prepareDownload(String filename) This method will prepare response header for file download.
PrintWriter	printWriter() Returns a print writer to write to the response
void	removeCookie(H.Cookie cookie) Remove a cookie.
void	removeCookie(String name) Removes cookie with given name.
abstract T	sendError(int statusCode) Sends an error response to the client using the specified status code and clearing the buffer.
abstract T	sendError(int statusCode, String msg) Sends an error response to the client using the specified status.
T	sendError(int statusCode, String msg, Object... args) Sames as sendError(int, String) but accept message format arguments
abstract T	sendRedirect(String location) Sends a temporary redirect response to the client using the specified redirect location URL.
T	status(H.Status status) Sets the status for this response.
abstract T	status(int statusCode) Sets the status code for this response.
abstract int	statusCode() Get the status code of this response.
T	writeBinary(org.osgl.storage.ISObject binary)
abstract T	writeContent(ByteBuffer buffer)
T	writeContent(String s) Write a string to the response
T	writeHtml(String content) Write content to the response
T	writeJSON(String content) Write content to the response
Writer	writer() Returns the writer to write to the response
boolean	writerCreated()
T	writeText(String content) Write content to the response
T	writeYAML(String content)

Methods inherited from class java.lang.Object

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

Field Detail

outputStream

protected volatile OutputStream outputStream

writer

protected volatile Writer writer

output

protected volatile org.osgl.util.Output output

Constructor Detail

H.Response

public H.Response()

Method Detail

context

public T context(Object context)

Attach a context object to the response instance

Parameters:

context - the context object

Returns:

the response instance itself

context

public <CONTEXT> CONTEXT context()

Get the context object from the response instance

Type Parameters:

CONTEXT - the generic type of the context object

Returns:

the context object

_impl

protected abstract Class<T> _impl()

Returns the class of the implementation. Not to be used by application

Returns:

implementation class

writerCreated

public boolean writerCreated()

outputCreated

public boolean outputCreated()

outputStreamCreated

public boolean outputStreamCreated()

createOutputStream

protected abstract OutputStream createOutputStream()

createWriter

protected Writer createWriter()

createOutput

protected abstract org.osgl.util.Output createOutput()

output

public org.osgl.util.Output output()

Returns the output to write to the response.

Returns:

output of the response.

Throws:

IllegalStateException - if writer() or outputStream() is called already

org.osgl.exception.UnexpectedIOException - if there are IO exception

outputStream

public OutputStream outputStream()
                          throws IllegalStateException,
                                 org.osgl.exception.UnexpectedIOException

Returns the output stream to write to the response.

Returns:

output stream to the response

Throws:

IllegalStateException - if writer() is called already

org.osgl.exception.UnexpectedIOException - if there are output exception

writer

public Writer writer()
              throws IllegalStateException,
                     org.osgl.exception.UnexpectedIOException

Returns the writer to write to the response

Returns:

writer to the response

Throws:

IllegalStateException - if outputStream() is called already

org.osgl.exception.UnexpectedIOException - if there are output exception

printWriter

public PrintWriter printWriter()

Returns a print writer to write to the response

Returns:

the print writer for the response

Throws:

IllegalStateException - if outputStream() is called already

org.osgl.exception.UnexpectedIOException - if there are output exception

characterEncoding

public abstract String characterEncoding()

Returns the name of the character encoding (MIME charset) used for the body sent in this response. The character encoding may have been specified explicitly using the characterEncoding(String) or contentType(String) methods, or implicitly using the locale(java.util.Locale) method. Explicit specifications take precedence over implicit specifications. Calls made to these methods after getWriter has been called or after the response has been committed have no effect on the character encoding. If no character encoding has been specified, ISO-8859-1 is returned.

See RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt) for more information about character encoding and MIME.

Returns:

a String specifying the name of the character encoding, for example, UTF-8

characterEncoding

public abstract T characterEncoding(String encoding)

Returns the content type used for the MIME body sent in this response. The content type proper must have been specified using contentType(String) before the response is committed. If no content type has been specified, this method returns null. If a content type has been specified, and a character encoding has been explicitly or implicitly specified as described in characterEncoding() or writer() has been called, the charset parameter is included in the string returned. If no character encoding has been specified, the charset parameter is omitted.

Parameters:

encoding - the encoding

Returns:

a String specifying the content type, for example, text/html; charset=UTF-8, or null

contentLength

public abstract T contentLength(long len)

Set the length of the content to be write to the response

Parameters:

len - an long value specifying the length of the content being returned to the client; sets the Content-Length header

Returns:

the response it self

See Also:

outputStream, writer

_setContentType

protected abstract void _setContentType(String type)

Sub class to overwrite this method to set content type to the response

Parameters:

type - a String specifying the MIME type of the content

contentType

public T contentType(String type)

Sets the content type of the response being sent to the client. The content type may include the type of character encoding used, for example, text/html; charset=ISO-8859-4. If content type has already been set to the response, this method will update the content type with the new value

this method must be called before calling writer() or outputStream()

Parameters:

type - a String specifying the MIME type of the content

Returns:

the response it self

See Also:

outputStream, writer, initContentType(String)

initContentType

public T initContentType(String type)

This method set the content type to the response if there is no content type been set already.

Parameters:

type - a String specifying the MIME type of the content

Returns:

the response it self

See Also:

contentType(String)

contentDisposition

public T contentDisposition(String filename,
                   boolean inline)

buildContentDispositionString

public String buildContentDispositionString(String filename,
                                   boolean inline)

prepareDownload

public T prepareDownload(String filename)

This method will prepare response header for file download.

Parameters:

filename - the filename

Returns:

this response instance

etag

public T etag(String etag)

Set the etag header

Parameters:

etag - the etag content

Returns:

this response

_setLocale

protected abstract void _setLocale(Locale loc)

Sets the locale of the response, setting the headers (including the Content-Type’s charset) as appropriate. This method should be called before a call to writer(). By default, the response locale is the default locale for the server.

Parameters:

loc - the locale of the response

See Also:

locale()

locale

public T locale(Locale locale)

locale

public abstract Locale locale()

Returns the locale assigned to the response.

Returns:

locale

See Also:

locale(java.util.Locale)

addCookie

public abstract void addCookie(H.Cookie cookie)

Adds the specified cookie to the response. This method can be called multiple times to add more than one cookie.

Parameters:

cookie - the Cookie to return to the client

removeCookie

public void removeCookie(String name)

Removes cookie with given name.

Parameters:

name - the name of the cookie to be removed.

removeCookie

public void removeCookie(H.Cookie cookie)

Remove a cookie.

This literally will reset a MaxAge of the cookie and then add it to the response.

Refer to https://stackoverflow.com/questions/890935/how-do-you-remove-a-cookie-in-a-java-servlet

Parameters:

cookie - the cookie to be removed.

containsHeader

public abstract boolean containsHeader(String name)

Returns a boolean indicating whether the named response header has already been set.

Parameters:

name - the header name

Returns:

true if the named response header has already been set; false otherwise

sendError

public abstract T sendError(int statusCode,
          String msg)

Sends an error response to the client using the specified status. The server defaults to creating the response to look like an HTML-formatted server error page containing the specified message, setting the content type to “text/html”, leaving cookies and other headers unmodified.

If an error-page declaration has been made for the web application corresponding to the status code passed in, it will be served back in preference to the suggested msg parameter.

If the response has already been committed, this method throws an IllegalStateException. After using this method, the response should be considered to be committed and should not be written to.

Parameters:

statusCode - the error status code

msg - the descriptive message

Returns:

the response itself

Throws:

org.osgl.exception.UnexpectedIOException - If an input or output exception occurs

IllegalStateException - If the response was committed

sendError

public T sendError(int statusCode,
          String msg,
          Object... args)

Sames as sendError(int, String) but accept message format arguments

Parameters:

statusCode - the error status code

msg - the descriptive message template

args - the descriptive message arguments

Returns:

the response itself

Throws:

org.osgl.exception.UnexpectedIOException - If an input or output exception occurs

IllegalStateException - If the response was committed

sendError

public abstract T sendError(int statusCode)

Sends an error response to the client using the specified status code and clearing the buffer.

If the response has already been committed, this method throws an IllegalStateException. After using this method, the response should be considered to be committed and should not be written to.

Parameters:

statusCode - the error status code

Returns:

the response itself

Throws:

org.osgl.exception.UnexpectedIOException - If the response was committed before this method call

sendRedirect

public abstract T sendRedirect(String location)

Sends a temporary redirect response to the client using the specified redirect location URL. This method can accept relative URLs; the servlet container must convert the relative URL to an absolute URL before sending the response to the client. If the location is relative without a leading ‘/’ the container interprets it as relative to the current request URI. If the location is relative with a leading ‘/’ the container interprets it as relative to the servlet container root.

If the response has already been committed, this method throws an IllegalStateException. After using this method, the response should be considered to be committed and should not be written to.

Parameters:

location - the redirect location URL

Returns:

the response itself

Throws:

org.osgl.exception.UnexpectedIOException - If the response was committed before this method call

IllegalStateException - If the response was committed or if a partial URL is given and cannot be converted into a valid URL

header

public abstract T header(String name,
       String value)

Sets a response header with the given name and value. If the header had already been set, the new value overwrites the previous one. The containsHeader method can be used to test for the presence of a header before setting its value.

Parameters:

name - the name of the header

value - the header value If it contains octet string, it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)

Returns:

the response itself

See Also:

containsHeader(java.lang.String), addHeader(java.lang.String, java.lang.String)

status

public abstract T status(int statusCode)

Sets the status code for this response. This method is used to set the return status code when there is no error (for example, for the status codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the caller wishes to invoke an error-page defined in the web application, the sendError method should be used instead.

The container clears the buffer and sets the Location header, preserving cookies and other headers.

Parameters:

statusCode - the status code

Returns:

the response itself

See Also:

sendError(int, java.lang.String), status(int)

status

public T status(H.Status status)

Sets the status for this response. This method is used to set the return status code when there is no error (for example, for the status OK or MOVED_TEMPORARILY). If there is an error, and the caller wishes to invoke an error-page defined in the web application, the sendError method should be used instead.

The container clears the buffer and sets the Location header, preserving cookies and other headers.

Parameters:

status - the status

Returns:

the response itself

See Also:

sendError(int, java.lang.String)

statusCode

public abstract int statusCode()

Get the status code of this response.

If the status code has not been set to this response, -1 should be returned.

Returns:

the status code of this response

addHeader

public abstract T addHeader(String name,
          String value)

Adds a response header with the given name and value. This method allows response headers to have multiple values.

Parameters:

name - the name of the header

value - the additional header value If it contains octet string, it should be encoded according to RFC 2047 (http://www.ietf.org/rfc/rfc2047.txt)

Returns:

this response itself

See Also:

header(String, String)

addHeaderIfNotAdded

public T addHeaderIfNotAdded(String name,
                    String value)

Adds a response header with given name and value if the header with the same name has not been added yet

Parameters:

name - the name of the header

value - the header value

Returns:

this response itself

See Also:

addHeader(String, String)

writeBinary

public T writeBinary(org.osgl.storage.ISObject binary)

writeContent

public T writeContent(String s)

Write a string to the response

Parameters:

s - the string to write to the response

Returns:

this response itself

writeContent

public abstract T writeContent(ByteBuffer buffer)

writeText

public T writeText(String content)

Write content to the response

Parameters:

content - the content to write

Returns:

the response itself

writeHtml

public T writeHtml(String content)

Write content to the response

Parameters:

content - the content to write

Returns:

the response itself

writeJSON

public T writeJSON(String content)

Write content to the response

Parameters:

content - the content to write

Returns:

the response itself

writeYAML

public T writeYAML(String content)

commit

public abstract void commit()

Calling this method commits the response, meaning the status code and headers will be written to the client

close

public void close()

Close output or outputStream or writer opened on this response

current

public static <T extends H.Response> T current()

Return a request instance of the current execution context, For example from a ThreadLocal

Type Parameters:

T - the response type

Returns:

the current request instance

current

public static <T extends H.Response> void current(T response)

Set a request instance into the current execution context, for example into a ThreadLocal

Type Parameters:

T - the sub type of response

Parameters:

response - the request to be set to current execution context

me

protected T me()