javax.portlet
Interface MimeResponse

All Superinterfaces:
PortletResponse
All Known Subinterfaces:
RenderResponse, ResourceResponse
All Known Implementing Classes:
RenderResponseWrapper, ResourceResponseWrapper

public interface MimeResponse
extends PortletResponse

The MimeResponse defines the base interface to assist a portlet in returning MIME content.

Since:
2.0

Field Summary
static java.lang.String CACHE_SCOPE
          Property to set the cache scope for this response using the setProperty method intended to be used in forwarded or included servlets/JSPs.
static java.lang.String ETAG
          Property to tell the portlet container the new ETag for this response intended to be used in forwarded or included servlets/JSPs.
static java.lang.String EXPIRATION_CACHE
          Property to set the expiration time in seconds for this response using the setProperty method intended to be used in forwarded or included servlets/JSPs.
static java.lang.String MARKUP_HEAD_ELEMENT
          Property intended to be a hint to the portal application that the provided DOM element should be added to the markup head section of the response to the client.
static java.lang.String NAMESPACED_RESPONSE
          Property intended to be a hint to the portal application that the returned content is completely namespaced.
static java.lang.String PRIVATE_SCOPE
          Private cache scope, indicating that the cache entry must not be shared across users.
static java.lang.String PUBLIC_SCOPE
          Public cache scope, indicating that the cache entry can be shared across users.
static java.lang.String USE_CACHED_CONTENT
          Property to tell the portlet container to use the cached markup for the validation token provided in the request.
 
Method Summary
 PortletURL createActionURL()
          Creates a portlet URL targeting the portlet.
 PortletURL createRenderURL()
          Creates a portlet URL targeting the portlet.
 ResourceURL createResourceURL()
          Creates a portlet URL targeting the portlet.
 void flushBuffer()
          Forces any content in the buffer to be written to the underlying output stream.
 int getBufferSize()
          Returns the actual buffer size used for the response.
 CacheControl getCacheControl()
          Returns the cache control object allowing to set specific cache settings valid for the markup returned in this response.
 java.lang.String getCharacterEncoding()
          Returns the name of the charset used for the MIME body sent in this response.
 java.lang.String getContentType()
          Returns the MIME type that can be used to contribute markup to the render response.
 java.util.Locale getLocale()
          Returns the locale assigned to the response.
 java.io.OutputStream getPortletOutputStream()
          Returns a OutputStream suitable for writing binary data in the response.
 java.io.PrintWriter getWriter()
          Returns a PrintWriter object that can send character text to the portal.
 boolean isCommitted()
          Returns a boolean indicating if the response has been committed.
 void reset()
          Clears any data that exists in the buffer as well as the properties set.
 void resetBuffer()
          Clears the content of the underlying buffer in the response without clearing properties set.
 void setBufferSize(int size)
          Sets the preferred buffer size for the body of the response.
 void setContentType(java.lang.String type)
          Sets the MIME type for the response.
 
Methods inherited from interface javax.portlet.PortletResponse
addProperty, addProperty, addProperty, createElement, encodeURL, getNamespace, setProperty
 

Field Detail

EXPIRATION_CACHE

static final java.lang.String EXPIRATION_CACHE
Property to set the expiration time in seconds for this response using the setProperty method intended to be used in forwarded or included servlets/JSPs.

If the expiration value is set to 0, caching is disabled for this portlet; if the value is set to -1, the cache does not expire.

A default can be defined in the portlet deployment descriptor with the expiration-cache tag, otherwise it is 0.

Non-integer values are treated as 0.

The value is "portlet.expiration-cache".

See Also:
CacheControl, Constant Field Values

CACHE_SCOPE

static final java.lang.String CACHE_SCOPE
Property to set the cache scope for this response using the setProperty method intended to be used in forwarded or included servlets/JSPs.

Predefined cache scopes are: PUBLIC_SCOPE and PRIVATE_SCOPE.

A default can be defined in the portlet deployment descriptor with the cache-scope tag, otherwise it is PRIVATE_SCOPE.

Values that are not either PUBLIC_SCOPE or PRIVATE_SCOPE are treated as PRIVATE_SCOPE.

The value is "portlet.cache-scope".

Since:
2.0
See Also:
CacheControl, Constant Field Values

PUBLIC_SCOPE

static final java.lang.String PUBLIC_SCOPE
Public cache scope, indicating that the cache entry can be shared across users. The value is "portlet.public-scope".

Since:
2.0
See Also:
Constant Field Values

PRIVATE_SCOPE

static final java.lang.String PRIVATE_SCOPE
Private cache scope, indicating that the cache entry must not be shared across users. The value is "portlet.private-scope".

Since:
2.0
See Also:
Constant Field Values

ETAG

static final java.lang.String ETAG
Property to tell the portlet container the new ETag for this response intended to be used in forwarded or included servlets/JSPs.

This property needs to be set using the setProperty method.

The value is "portlet.ETag ".

Since:
2.0
See Also:
CacheControl, Constant Field Values

USE_CACHED_CONTENT

static final java.lang.String USE_CACHED_CONTENT
Property to tell the portlet container to use the cached markup for the validation token provided in the request. This property needs to be set using the setProperty method with a non-null value and is intended to be used in forwarded or included servlets/JSPs. The value itself is not evaluated.

The value is "portlet.use-cached-content ".

Since:
2.0
See Also:
CacheControl, Constant Field Values

NAMESPACED_RESPONSE

static final java.lang.String NAMESPACED_RESPONSE
Property intended to be a hint to the portal application that the returned content is completely namespaced. This includes all markup id elements, form fields, etc. One example where this is might be used is for portal applications that are form-based and thus need to re-write any forms included in the portlet markup.

This property needs to be set using the setProperty method with a non-null value. The value itself is not evaluated.

The value is "X-JAVAX-PORTLET-NAMESPACED-RESPONSE".

Since:
2.0
See Also:
Constant Field Values

MARKUP_HEAD_ELEMENT

static final java.lang.String MARKUP_HEAD_ELEMENT
Property intended to be a hint to the portal application that the provided DOM element should be added to the markup head section of the response to the client.

Support for this property is optional and the portlet can verify if the calling portal supports this property via the MARKUP_HEAD_ELEMENT_SUPPORT property on the PortalContext.

Even if the calling portal support this property delivery of the DOM element to the client cannot be guaranteed, e.g. due to possible security rules of the portal application or elements that conflict with the response of other portlets.

This property needs to be set using the setProperty(String key,org.w3c.dom.Element element) method.

The value is "javax.portlet.markup.head.element".

Since:
2.0
See Also:
Constant Field Values
Method Detail

getContentType

java.lang.String getContentType()
Returns the MIME type that can be used to contribute markup to the render response.

If no content type was set previously using the setContentType(java.lang.String) method this method returns null.

Returns:
the MIME type of the response, or null if no content type is set
See Also:
setContentType(java.lang.String)

setContentType

void setContentType(java.lang.String type)
Sets the MIME type for the response. The portlet should set the content type before calling getWriter() or getPortletOutputStream(). If the content type is not the PortletRequest.getResponseContentType() value is set as response content type by the portlet container.

Calling setContentType after getWriter or getOutputStream does not change the content type.

Parameters:
type - the content MIME type
See Also:
PortletRequest.getResponseContentTypes(), getContentType()

getCharacterEncoding

java.lang.String getCharacterEncoding()
Returns the name of the charset used for the MIME body sent in this response.

See RFC 2047 for more information about character encoding and MIME.

Returns:
a String specifying the name of the charset, for example, ISO-8859-1

getWriter

java.io.PrintWriter getWriter()
                              throws java.io.IOException
Returns a PrintWriter object that can send character text to the portal.

Before calling this method the content type of the render response should be set using the setContentType(java.lang.String) method.

Either this method or getPortletOutputStream() may be called to write the body, not both.

Returns:
a PrintWriter object that can return character data to the portal
Throws:
java.io.IOException - if an input or output exception occurred
java.lang.IllegalStateException - if the getPortletOutputStream method has been called on this response.
See Also:
setContentType(java.lang.String), getPortletOutputStream()

getLocale

java.util.Locale getLocale()
Returns the locale assigned to the response.

Returns:
Locale of this response

setBufferSize

void setBufferSize(int size)
Sets the preferred buffer size for the body of the response. The portlet container will use a buffer at least as large as the size requested.

This method must be called before any response body content is written; if content has been written, or the portlet container does not support buffering, this method may throw an IllegalStateException.

Parameters:
size - the preferred buffer size
Throws:
java.lang.IllegalStateException - if this method is called after content has been written, or the portlet container does not support buffering
See Also:
getBufferSize(), flushBuffer(), isCommitted(), reset()

getBufferSize

int getBufferSize()
Returns the actual buffer size used for the response. If no buffering is used, this method returns 0.

Returns:
the actual buffer size used
See Also:
setBufferSize(int), flushBuffer(), isCommitted(), reset()

flushBuffer

void flushBuffer()
                 throws java.io.IOException
Forces any content in the buffer to be written to the underlying output stream. A call to this method automatically commits the response.

Throws:
java.io.IOException - if an error occurred when writing the output
See Also:
setBufferSize(int), getBufferSize(), isCommitted(), reset()

resetBuffer

void resetBuffer()
Clears the content of the underlying buffer in the response without clearing properties set. If the response has been committed, this method throws an IllegalStateException.

Throws:
java.lang.IllegalStateException - if this method is called after response is committed
See Also:
setBufferSize(int), getBufferSize(), isCommitted(), reset()

isCommitted

boolean isCommitted()
Returns a boolean indicating if the response has been committed.

Returns:
a boolean indicating if the response has been committed
See Also:
setBufferSize(int), getBufferSize(), flushBuffer(), reset()

reset

void reset()
Clears any data that exists in the buffer as well as the properties set. If the response has been committed, this method throws an IllegalStateException.

Throws:
java.lang.IllegalStateException - if the response has already been committed
See Also:
setBufferSize(int), getBufferSize(), flushBuffer(), isCommitted()

getPortletOutputStream

java.io.OutputStream getPortletOutputStream()
                                            throws java.io.IOException
Returns a OutputStream suitable for writing binary data in the response. The portlet container does not encode the binary data.

Before calling this method the content type of the render response must be set using the setContentType(java.lang.String) method.

Calling flush() on the OutputStream commits the response.

Either this method or getWriter() may be called to write the body, not both.

Returns:
a OutputStream for writing binary data
Throws:
java.lang.IllegalStateException - if the getWriter method has been called on this response.
java.io.IOException - if an input or output exception occurred
See Also:
setContentType(java.lang.String), getWriter()

createRenderURL

PortletURL createRenderURL()
Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in a render request.

The returned URL can be further extended by adding portlet-specific parameters and portlet modes and window states.

The created URL will per default not contain any parameters of the current render request.

Returns:
a portlet render URL

createActionURL

PortletURL createActionURL()
Creates a portlet URL targeting the portlet. If no portlet mode, window state or security modifier is set in the PortletURL the current values are preserved. If a request is triggered by the PortletURL, it results in an action request.

The returned URL can be further extended by adding portlet-specific parameters and portlet modes and window states.

The created URL will per default not contain any parameters of the current render request.

Returns:
a portlet action URL

createResourceURL

ResourceURL createResourceURL()
Creates a portlet URL targeting the portlet. If no security modifier is set in the PortletURL the current values are preserved. The current render parameters, portlet mode and window state are preserved.

If a request is triggered by the PortletURL, it results in a serve resource request of the ResourceServingPortlet interface.

The returned URL can be further extended by adding portlet-specific parameters .

The created URL will per default contain the current cacheability setting of the parent resource. If no parent resource is available, PAGE is the default.

Returns:
a portlet resource URL
Since:
2.0

getCacheControl

CacheControl getCacheControl()
Returns the cache control object allowing to set specific cache settings valid for the markup returned in this response.

Returns:
Cache control for the current response.
Since:
2.0