javax.portlet

Interface ResourceRequest

All Superinterfaces:

ClientDataRequest, PortletRequest, RenderState

All Known Implementing Classes:

ResourceRequestWrapper

public interface ResourceRequest
extends ClientDataRequest

The ResourceRequest interface represents the request send to the portlet for rendering resources. It extends the ClientDataRequest interface and provides resource request information to portlets.

The portlet container creates an ResourceRequest object and passes it as argument to the portlet's serveResource method.

The ResourceRequest is provided with the current portlet mode, window state, and render parameters that the portlet can access via the PortletResourceRequest with getPortletMode and, getWindowState, or one of the getParameter methods. ResourceURLs cannot change the current portlet mode, window state or render parameters. Parameters set on a resource URL are not render parameters but parameters for serving this resource and will last only for only this the current serveResource request.
If a parameter is set that has the same name as a render parameter that this resource URL contains, the render parameter must be the last entry in the parameter value array.

Since:

2.0

See Also:

ClientDataRequest, ResourceServingPortlet

Nested Class Summary

Nested classes/interfaces inherited from interface javax.portlet.PortletRequest

PortletRequest.P3PUserInfos

Field Summary

Fields

Modifier and Type	Field and Description
static String	ETAG This property is set by the container if the container has a cached response for the given validation tag.

Fields inherited from interface javax.portlet.PortletRequest

ACTION_PHASE, ACTION_SCOPE_ID, BASIC_AUTH, CCPP_PROFILE, CLIENT_CERT_AUTH, DIGEST_AUTH, EVENT_PHASE, FORM_AUTH, HEADER_PHASE, LIFECYCLE_PHASE, RENDER_HEADERS, RENDER_MARKUP, RENDER_PART, RENDER_PHASE, RESOURCE_PHASE, USER_INFO

Method Summary

Methods

Modifier and Type	Method and Description
String	getCacheability() Returns the cache level of this resource request.
DispatcherType	getDispatcherType() Gets the dispatcher type of this request.
String	getETag() Returns the validation tag if the portlet container has a cached response for this validation tag, or null if no cached response exists.
PortletAsyncContext	getPortletAsyncContext() Gets the AsyncContext that was created or reinitialized by the most recent invocation of startAsync() or startAsync(ResourceRequest,ResourceResponse) on this request.
PortletMode	getPortletMode() Returns the current portlet mode of the portlet.
Map<String,String[]>	getPrivateRenderParameterMap() Deprecated. As of version 3.0. Use RenderState.getRenderParameters() instead.
String	getResourceID() Returns the resource ID set on the ResourceURL or null if no resource ID was set on the URL.
ResourceParameters	getResourceParameters() Gets the resource parameters set for this request.
String	getResponseContentType() Returns the portal preferred content type for the response.
Enumeration<String>	getResponseContentTypes() Gets a list of content types which the portal accepts for the response.
WindowState	getWindowState() Returns the current window state of the portlet.
boolean	isAsyncStarted() Checks if this request has been put into asynchronous mode.
boolean	isAsyncSupported() Checks if this request supports asynchronous operation.
PortletAsyncContext	startPortletAsync() Puts this request into asynchronous mode and initializes the AsyncContext object.
PortletAsyncContext	startPortletAsync(ResourceRequest request, ResourceResponse response) Puts this request into asynchronous mode and initializes the AsyncContext object.

Methods inherited from interface javax.portlet.ClientDataRequest

getCharacterEncoding, getContentLength, getContentLengthLong, getContentType, getMethod, getPart, getParts, getPortletInputStream, getReader, setCharacterEncoding

Methods inherited from interface javax.portlet.PortletRequest

getAttribute, getAttributeNames, getAuthType, getContextPath, getCookies, getLocale, getLocales, getParameter, getParameterMap, getParameterNames, getParameterValues, getPortalContext, getPortletContext, getPortletSession, getPortletSession, getPreferences, getPrivateParameterMap, getProperties, getProperty, getPropertyNames, getPublicParameterMap, getRemoteUser, getRequestedSessionId, getScheme, getServerName, getServerPort, getUserAgent, getUserPrincipal, getWindowID, isPortletModeAllowed, isRequestedSessionIdValid, isSecure, isUserInRole, isWindowStateAllowed, removeAttribute, setAttribute

Methods inherited from interface javax.portlet.RenderState

getRenderParameters

Field Detail

ETAG

static final String ETAG

This property is set by the container if the container has a cached response for the given validation tag. The property can be retrieved using the getProperty method.

The value is "portlet.ETag ".

See Also:

Constant Field Values

Method Detail

getETag

String getETag()

Returns the validation tag if the portlet container has a cached response for this validation tag, or null if no cached response exists.

This call returns the same value as ResourceRequest.getProperty(ResourceRequest.ETAG).

Returns:

the validation tag if the portlet container has a cached response for this validation tag, or null if no cached response exists.

getResourceID

String getResourceID()

Returns the resource ID set on the ResourceURL or null if no resource ID was set on the URL.

Returns:

the resource ID set on the ResourceURL,or null if no resource ID was set on the URL.

getPrivateRenderParameterMap

@Deprecated
Map<String,String[]> getPrivateRenderParameterMap()

Deprecated. As of version 3.0. Use RenderState.getRenderParameters() instead.

Returns a Map of the private render parameters of this request. Private parameters are not shared with other portlets or components. The returned parameters are "x-www-form-urlencoded" decoded.

The parameters returned do not include the resource parameters that the portlet may have set on the resource URL triggering this serveResource call.

The values in the returned Map are from type String array (String[]).

If no private parameters exist this method returns an empty Map.

Returns:

an immutable Map containing private parameter names as keys and private parameter values as map values, or an empty Map if no private parameters exist. The keys in the parameter map are of type String. The values in the parameter map are of type String array (String[]).

getResourceParameters

ResourceParameters getResourceParameters()

Gets the resource parameters set for this request.

Resource parameters are additional portlet parameters added to the URL triggering the request that extend the state information provided by the render parameters.

PortletParameters provides a description of the parameter concept.

Returns:

an immutable ResourceParameters object representing the resource parameters

Since:

3.0

See Also:

PortletParameters, MutableResourceParameters, ResourceURL

getResponseContentType

String getResponseContentType()

Returns the portal preferred content type for the response.

The returned content type should be based on the HTTP Accept header provided by the client.

Specified by:

getResponseContentType in interface PortletRequest

Returns:

preferred content type of the response

getResponseContentTypes

Enumeration<String> getResponseContentTypes()

Gets a list of content types which the portal accepts for the response. This list is ordered with the most preferable types listed first.

The returned content types should be based on the HTTP Accept header provided by the client.

Specified by:

getResponseContentTypes in interface PortletRequest

Returns:

ordered list of content types for the response

getCacheability

String getCacheability()

Returns the cache level of this resource request.

Possible return values are: ResourceURL.FULL, ResourceURL.PORTLET or ResourceURL.PAGE.

Returns:

the cache level of this resource request.

getPortletMode

PortletMode getPortletMode()

Returns the current portlet mode of the portlet.

If called during a request where the cache level is set to ResourceURL.FULL, the portlet mode will not be available.

Specified by:

getPortletMode in interface RenderState

Returns:

the portlet mode. The portlet mode UNDEFINED will be returned if the cache level is set to ResourceURL.FULL.

See Also:

PortletMode

getWindowState

WindowState getWindowState()

Returns the current window state of the portlet.

If called during a request where the cache level is set to ResourceURL.FULL, the window state will not be available.

Specified by:

getWindowState in interface RenderState

Returns:

the window state. The window state UNDEFINED will be returned if the cache level is set to ResourceURL.FULL.

See Also:

WindowState

startPortletAsync

PortletAsyncContext startPortletAsync()
                                      throws IllegalStateException

Puts this request into asynchronous mode and initializes the AsyncContext object.

Calling this method will cause committal of the associated response to be delayed until AsyncContext#complete is called on the returned AsyncContext, or the asynchronous operation has timed out.

This method clears the list of AsyncListener instances (if any) that were registered with the AsyncContext returned by the previous call to one of the startAsync methods, after calling each AsyncListener at its onStartAsync method.

Subsequent invocations of this method, or its overloaded variant, will return the same AsyncContext instance, reinitialized as appropriate.

The AsyncContext object can be used as described by the servlet specification. The ServletRequest and ServletResponse objects obtained from the AsyncContext will provide functionality appropriate for the portlet environment.

The original ResourceRequest and ResourceResponse objects will be made available as request attributes on the code>ServletRequest object obtained from the AsyncContext under the names javax.portlet.request and javax.portlet.response, respectively. The PortletConfig object will be made available on the ServletRequest under the name javax.portlet.config.

The AsyncContext#dispatch() method will cause the portlet resource method to be invoked with the ResourceRequest and ResourceResponse objects available as attributes on the ServletRequest object obtained from the AsyncContext. In this case, the ResourceRequest#isAsyncStarted() method will return false and the ResourceRequest#getDispatcherType() method will return DispatcherType#ASYNC.

A portlet ResourceFilter that allocates resources and attaches them to the ResourceRequest or that wraps the ResourceRequest or ResourceResponse should not release resources in the outbound direction if asynchronous mode has been started. A portlet ResourceFilter can use the values provided by the ResourceRequest#isAsyncStarted() and the ResourceRequest#getDispatcherType() methods to determine when to allocate and release resources.

Returns:

the (re)initialized AsyncContext

Throws:

IllegalStateException - if this request is within the scope of a filter or servlet that does not support asynchronous operations (that is, isAsyncSupported() returns false), or if this method is called again without any asynchronous dispatch (resulting from one of the PortletAsyncContext#dispatch methods), is called outside the scope of any such dispatch, or is called again within the scope of the same dispatch, or if the response has already been closed

Since:

3.0

See Also:

ServletRequest.startAsync(), AsyncContext, isAsyncStarted(), getDispatcherType(), ResourceFilter

startPortletAsync

PortletAsyncContext startPortletAsync(ResourceRequest request,
                                    ResourceResponse response)
                                      throws IllegalStateException

Puts this request into asynchronous mode and initializes the AsyncContext object.

Calling this method will cause committal of the associated response to be delayed until AsyncContext#complete is called on the returned AsyncContext, or the asynchronous operation has timed out.

This method clears the list of AsyncListener instances (if any) that were registered with the AsyncContext returned by the previous call to one of the startAsync methods, after calling each AsyncListener at its onStartAsync method.

The AsyncContext object can be used as described by the servlet specification. The ServletRequest and ServletResponse objects obtained from the AsyncContext will provide functionality appropriate for the portlet environment.

The ResourceRequest and ResourceResponse objects passed as arguments to this method will be made available as request attributes on the code>ServletRequest object obtained from the AsyncContext under the names javax.portlet.request and javax.portlet.response, respectively. The PortletConfig object will be made available on the ServletRequest under the name javax.portlet.config.

Subsequent invocations of this method, or its zero-argument variant, will return the same AsyncContext instance, reinitialized as appropriate. If a call to this method is followed by a call to its zero-argument variant, the specified (and possibly wrapped) ResourceRequest and ResourceResponse objects will remain available as request attributes on the ServletRequest object obtained from the AsyncContext.

The AsyncContext#dispatch() method will cause the portlet resource method to be invoked with the ResourceRequest and ResourceResponse objects available as attributes on the ServletRequest object obtained from the AsyncContext. In this case, the ResourceRequest#isAsyncStarted() method will return false and the ResourceRequest#getDispatcherType() method will return DispatcherType#ASYNC.

A portlet ResourceFilter that allocates resources and attaches them to the ResourceRequest or that wraps the ResourceRequest or ResourceResponse should not release resources in the outbound direction if asynchronous mode has been started. A portlet ResourceFilter can use the values provided by the ResourceRequest#isAsyncStarted() and the ResourceRequest#getDispatcherType() methods to determine when to allocate and release resources.

Returns:

the (re)initialized AsyncContext

Throws:

IllegalStateException - if this request is within the scope of a filter or servlet that does not support asynchronous operations (that is, isAsyncSupported() returns false), or if this method is called again without any asynchronous dispatch (resulting from one of the PortletAsyncContext#dispatch methods), is called outside the scope of any such dispatch, or is called again within the scope of the same dispatch, or if the response has already been closed

Since:

3.0

See Also:

ServletRequest.startAsync(), AsyncContext, isAsyncStarted(), getDispatcherType(), ResourceFilter

isAsyncStarted

boolean isAsyncStarted()

Checks if this request has been put into asynchronous mode.

A ResourceRequest is put into asynchronous mode by calling startAsync() or startAsync(ResourceRequest,ResourceResponse) on it.

This method returns false if this request was put into asynchronous mode, but has since been dispatched using one of the AsyncContext#dispatch methods or released from asynchronous mode via a call to AsyncContext#complete.

Returns:

true if asynchronous mode has been started

Since:

3.0

See Also:

startPortletAsync(), startPortletAsync(ResourceRequest, ResourceResponse)

isAsyncSupported

boolean isAsyncSupported()

Checks if this request supports asynchronous operation.

Asynchronous operation is disabled for this request if this request is within the scope of a filter or servlet that has not been annotated or flagged in the portlet configuration as being able to support asynchronous handling.

Returns:

true if this request supports asynchronous operation

Since:

3.0

getPortletAsyncContext

PortletAsyncContext getPortletAsyncContext()

Gets the AsyncContext that was created or reinitialized by the most recent invocation of startAsync() or startAsync(ResourceRequest,ResourceResponse) on this request.

Returns:

the AsyncContext (re)initialized by the most recent startAsync method invocation

Throws:

IllegalStateException - if this request is within the scope of a filter or servlet that does not support asynchronous operations (that is, isAsyncSupported() returns false), or if asynchronous processing has not yet been started.

Since:

3.0

See Also:

ServletRequest.startAsync(), AsyncContext

getDispatcherType

DispatcherType getDispatcherType()

Gets the dispatcher type of this request.

The initial dispatcher type of a request is defined as DispatcherType.REQUEST. The dispatcher type of a request dispatched via a RequestDispatcher is given as DispatcherType.FORWARD or DispatcherType.INCLUDE, while the dispatcher type of an asynchronous request dispatched via one of the AsyncContext#dispatch methods is given as DispatcherType.ASYNC.

Returns:

the dispatcher type of this request

Since:

3.0

See Also:

DispatcherType