org.apache.juneau.rest

Class RestResponse

java.lang.Object

javax.servlet.ServletResponseWrapper

javax.servlet.http.HttpServletResponseWrapper

org.apache.juneau.rest.RestResponse

All Implemented Interfaces:

javax.servlet.http.HttpServletResponse, javax.servlet.ServletResponse

public final class RestResponse
extends javax.servlet.http.HttpServletResponseWrapper

Represents an HTTP response for a REST resource.

Essentially an extended HttpServletResponse with some special convenience methods that allow you to easily output POJOs as responses.

Since this class extends HttpServletResponse, developers are free to use these convenience methods, or revert to using lower level methods like any other servlet response.

Example:

@RestMethod(name=GET) public void doGet(RestRequest req, RestResponse res) { res.setOutput("Simple string response"); }

See Also:

• Overview > juneau-rest-server > RestResponse

Field Summary

Fields inherited from interface javax.servlet.http.HttpServletResponse

SC_ACCEPTED, SC_BAD_GATEWAY, SC_BAD_REQUEST, SC_CONFLICT, SC_CONTINUE, SC_CREATED, SC_EXPECTATION_FAILED, SC_FORBIDDEN, SC_FOUND, SC_GATEWAY_TIMEOUT, SC_GONE, SC_HTTP_VERSION_NOT_SUPPORTED, SC_INTERNAL_SERVER_ERROR, SC_LENGTH_REQUIRED, SC_METHOD_NOT_ALLOWED, SC_MOVED_PERMANENTLY, SC_MOVED_TEMPORARILY, SC_MULTIPLE_CHOICES, SC_NO_CONTENT, SC_NON_AUTHORITATIVE_INFORMATION, SC_NOT_ACCEPTABLE, SC_NOT_FOUND, SC_NOT_IMPLEMENTED, SC_NOT_MODIFIED, SC_OK, SC_PARTIAL_CONTENT, SC_PAYMENT_REQUIRED, SC_PRECONDITION_FAILED, SC_PROXY_AUTHENTICATION_REQUIRED, SC_REQUEST_ENTITY_TOO_LARGE, SC_REQUEST_TIMEOUT, SC_REQUEST_URI_TOO_LONG, SC_REQUESTED_RANGE_NOT_SATISFIABLE, SC_RESET_CONTENT, SC_SEE_OTHER, SC_SERVICE_UNAVAILABLE, SC_SWITCHING_PROTOCOLS, SC_TEMPORARY_REDIRECT, SC_UNAUTHORIZED, SC_UNSUPPORTED_MEDIA_TYPE, SC_USE_PROXY

Method Summary

Modifier and Type	Method and Description
void	flushBuffer()
PrintWriter	getDirectWriter(String contentType) Convenience method meant to be used when rendering directly to a browser with no buffering.
HtmlDocBuilder	getHtmlDocBuilder() Returns a programmatic interface for setting properties for the HTML doc view.
MediaType	getMediaType() Returns the Content-Type header stripped of the charset attribute if present.
FinishableServletOutputStream	getNegotiatedOutputStream() Equivalent to ServletResponse.getOutputStream(), except wraps the output stream if an Encoder was found that matched the Accept-Encoding header.
FinishablePrintWriter	getNegotiatedWriter() Equivalent to ServletResponse.getWriter(), except wraps the output stream if an Encoder was found that matched the Accept-Encoding header and sets the Content-Encoding header to the appropriate value.
Object	getOutput() Returns the output that was set by calling setOutput(Object).
javax.servlet.ServletOutputStream	getOutputStream()
boolean	getOutputStreamCalled() Returns true if getOutputStream() has been called.
HttpPartSerializer	getPartSerializer() Returns the HTTP-part serializer associated with this response.
RequestProperties	getProperties() Retrieve the properties active for this request.
SerializerGroup	getSerializers() Gets the serializer group for the response.
List<String>	getSupportedEncodings() Returns the codings that are valid for Accept-Encoding and Content-Encoding headers on the request.
List<MediaType>	getSupportedMediaTypes() Returns the media types that are valid for Accept headers on the request.
PrintWriter	getWriter() Returns the writer to the response body.
boolean	hasOutput() Returns true if this response has any output associated with it.
RestResponse	prop(String name, Object value) Shortcut for calling getProperties().append(name, value); fluently.
RestResponse	sendPlainText(String text) Sets the output to a plain-text message regardless of the content type.
void	sendRedirect(String uri) Redirects to the specified URI.
void	setHeader(String name, String value)
RestResponse	setOutput(Object output) Sets the HTTP output on the response.
RestResponse	setOutputs(Object... output) Shortcut method that allows you to use var-args to simplify setting array output.

Methods inherited from class javax.servlet.http.HttpServletResponseWrapper

addCookie, addDateHeader, addHeader, addIntHeader, containsHeader, encodeRedirectUrl, encodeRedirectURL, encodeUrl, encodeURL, getHeader, getHeaderNames, getHeaders, getStatus, sendError, sendError, setDateHeader, setIntHeader, setStatus, setStatus

Methods inherited from class javax.servlet.ServletResponseWrapper

getBufferSize, getCharacterEncoding, getContentType, getLocale, getResponse, isCommitted, isWrapperFor, isWrapperFor, reset, resetBuffer, setBufferSize, setCharacterEncoding, setContentLength, setContentLengthLong, setContentType, setLocale, setResponse

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.servlet.ServletResponse

getBufferSize, getCharacterEncoding, getContentType, getLocale, isCommitted, reset, resetBuffer, setBufferSize, setCharacterEncoding, setContentLength, setContentLengthLong, setContentType, setLocale

Method Detail

getSerializers

public SerializerGroup getSerializers()

Gets the serializer group for the response.

See Also:

• Overview > juneau-rest-server > Serializers

Returns:

The serializer group for the response.

getSupportedMediaTypes

public List<MediaType> getSupportedMediaTypes()

Returns the media types that are valid for Accept headers on the request.

Returns:

The set of media types registered in the parser group of this request.

getSupportedEncodings

public List<String> getSupportedEncodings()
                                   throws RestServletException

Returns the codings that are valid for Accept-Encoding and Content-Encoding headers on the request.

Returns:

The set of media types registered in the parser group of this request.

Throws:

RestServletException

setOutput

public RestResponse setOutput(Object output)

Sets the HTTP output on the response.

The object type can be anything allowed by the registered response handlers.

Calling this method is functionally equivalent to returning the object in the REST Java method.

Example:

@RestMethod(..., path="/example2/{personId}") public void doGet2(RestResponse res, @Path UUID personId) { Person p = getPersonById(personId); res.setOutput(p); }

Notes:

• Calling this method with a null value is NOT the same as not calling this method at all.
  A null output value means we want to serialize null as a response (e.g. as a JSON null).
  Not calling this method or returning a value means you're handing the response yourself via the underlying stream or writer.
  This distinction affects the hasOutput() method behavior.

See Also:

• RestContext.REST_responseHandlers
• Overview > juneau-rest-server > Method Return Types

Parameters:

output - The output to serialize to the connection.

Returns:

This object (for method chaining).

getHtmlDocBuilder

public HtmlDocBuilder getHtmlDocBuilder()

Returns a programmatic interface for setting properties for the HTML doc view.

This is the programmatic equivalent to the @RestMethod.htmldoc() annotation.

Example:

// Declarative approach. @RestMethod( htmldoc=@HtmlDoc( header={ "<p>This is my REST interface</p>" }, aside={ "<p>Custom aside content</p>" } ) ) public Object doGet(RestResponse res) { // Equivalent programmatic approach. res.getHtmlDocBuilder() .header("<p>This is my REST interface</p>") .aside("<p>Custom aside content</p>"); }

See Also:

• RestMethod.htmldoc()
• Overview > juneau-rest-server > @HtmlDoc

Returns:

A new programmatic interface for setting properties for the HTML doc view.

getProperties

public RequestProperties getProperties()

Retrieve the properties active for this request.

This contains all resource and method level properties from the following:

• RestResource.properties()
• RestMethod.properties()
• RestContextBuilder.set(String, Object)

The returned object is modifiable and allows you to override session-level properties before they get passed to the serializers.
However, properties are open-ended, and can be used for any purpose.

Example:

@RestMethod( properties={ @Property(name=SERIALIZER_sortMaps, value="false") } ) public Map doGet(RestResponse res, @Query("sortMaps") Boolean sortMaps) { // Override value if specified through query parameter. if (sortMaps != null) res.getProperties().put(SERIALIZER_sortMaps, sortMaps); return getMyMap(); }

See Also:

• prop(String, Object)
• Overview > juneau-rest-server > Properties

Returns:

The properties active for this request.

prop

public RestResponse prop(String name,
                         Object value)

Shortcut for calling getProperties().append(name, value); fluently.

Parameters:

name - The property name.

value - The property value.

Returns:

This object (for method chaining).

setOutputs

public RestResponse setOutputs(Object... output)

Shortcut method that allows you to use var-args to simplify setting array output.

Example:

// Instead of... response.setOutput(new Object[]{x,y,z}); // ...call this... response.setOutput(x,y,z);

Parameters:

output - The output to serialize to the connection.

Returns:

This object (for method chaining).

getOutput

public Object getOutput()

Returns the output that was set by calling setOutput(Object).

Returns:

The output object.

hasOutput

public boolean hasOutput()

Returns true if this response has any output associated with it.

Returns:

true if setOutput(Object) has been called, even if the value passed was null.

sendPlainText

public RestResponse sendPlainText(String text)
                           throws IOException

Sets the output to a plain-text message regardless of the content type.

Parameters:

text - The output text to send.

Returns:

This object (for method chaining).

Throws:

IOException - If a problem occurred trying to write to the writer.

getNegotiatedOutputStream

public FinishableServletOutputStream getNegotiatedOutputStream()
                                                        throws IOException

Equivalent to ServletResponse.getOutputStream(), except wraps the output stream if an Encoder was found that matched the Accept-Encoding header.

Returns:

A negotiated output stream.

Throws:

IOException

getOutputStream

public javax.servlet.ServletOutputStream getOutputStream()
                                                  throws IOException

Specified by:

getOutputStream in interface javax.servlet.ServletResponse

Overrides:

getOutputStream in class javax.servlet.ServletResponseWrapper

Throws:

IOException

getOutputStreamCalled

public boolean getOutputStreamCalled()

Returns true if getOutputStream() has been called.

Returns:

true if getOutputStream() has been called.

getWriter

public PrintWriter getWriter()
                      throws IOException

Returns the writer to the response body.

This methods bypasses any specified encoders and returns a regular unbuffered writer. Use the getNegotiatedWriter() method if you want to use the matched encoder (if any).

Specified by:

getWriter in interface javax.servlet.ServletResponse

Overrides:

getWriter in class javax.servlet.ServletResponseWrapper

Throws:

IOException

getDirectWriter

public PrintWriter getDirectWriter(String contentType)
                            throws IOException

Convenience method meant to be used when rendering directly to a browser with no buffering.

Sets the header "x-content-type-options=nosniff" so that output is rendered immediately on IE and Chrome without any buffering for content-type sniffing.

This can be useful if you want to render a streaming 'console' on a web page.

Parameters:

contentType - The value to set as the Content-Type on the response.

Returns:

The raw writer.

Throws:

IOException

getNegotiatedWriter

public FinishablePrintWriter getNegotiatedWriter()
                                          throws IOException

Equivalent to ServletResponse.getWriter(), except wraps the output stream if an Encoder was found that matched the Accept-Encoding header and sets the Content-Encoding header to the appropriate value.

Returns:

The negotiated writer.

Throws:

IOException

getMediaType

public MediaType getMediaType()

Returns the Content-Type header stripped of the charset attribute if present.

Returns:

The media-type portion of the Content-Type header.

sendRedirect

public void sendRedirect(String uri)
                  throws IOException

Redirects to the specified URI.

Relative URIs are always interpreted as relative to the context root. This is similar to how WAS handles redirect requests, and is different from how Tomcat handles redirect requests.

Specified by:

sendRedirect in interface javax.servlet.http.HttpServletResponse

Overrides:

sendRedirect in class javax.servlet.http.HttpServletResponseWrapper

Throws:

IOException

getPartSerializer

public HttpPartSerializer getPartSerializer()

Returns the HTTP-part serializer associated with this response.

Returns:

The HTTP-part serializer associated with this response.

setHeader

public void setHeader(String name,
                      String value)

Specified by:

setHeader in interface javax.servlet.http.HttpServletResponse

Overrides:

setHeader in class javax.servlet.http.HttpServletResponseWrapper

flushBuffer

public void flushBuffer()
                 throws IOException

Specified by:

flushBuffer in interface javax.servlet.ServletResponse

Overrides:

flushBuffer in class javax.servlet.ServletResponseWrapper

Throws:

IOException