javax.portlet.ResourceRequest Maven / Gradle / Ivy
Show all versions of portlet-api Show documentation
/* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
/*
* This source code implements specifications defined by the Java
* Community Process. In order to remain compliant with the specification
* DO NOT add / change / or delete method signatures!
*/
package javax.portlet;
import javax.servlet.DispatcherType;
/**
* 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.
*
* @see ClientDataRequest
* @see ResourceServingPortlet
* @since 2.0
*/
public interface ResourceRequest extends ClientDataRequest {
/**
* 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 ".
*/
public static final String ETAG = "portlet.ETag";
/**
* 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).
*
* @return the validation tag if the portlet container
* has a cached response for this validation tag, or
* null if no cached response exists.
*/
public String getETag();
/**
* Returns the resource ID set on the ResourceURL or null
* if no resource ID was set on the URL.
*
* @return the resource ID set on the ResourceURL,or null
* if no resource ID was set on the URL.
*/
public String getResourceID();
/**
* 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.
*
* @return 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[]).
*
* @deprecated As of version 3.0. Use {@link PortletRequest#getRenderParameters()} instead.
*/
@Deprecated
public java.util.Map getPrivateRenderParameterMap();
/**
*
* 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.
*
* {@link PortletParameters} provides a description of the parameter concept.
*
*
* @return an immutable ResourceParameters object representing
* the resource parameters
* @since 3.0
* @see PortletParameters
* @see MutableResourceParameters
* @see ResourceURL
*/
public ResourceParameters getResourceParameters();
/**
* 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.
*
* @return preferred content type of the response
*/
public String getResponseContentType();
/**
* 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.
*
* @return ordered list of content types for the response
*/
public java.util.Enumeration getResponseContentTypes();
/**
* Returns the cache level of this resource request.
*
* Possible return values are:
* ResourceURL.FULL, ResourceURL.PORTLET
* or ResourceURL.PAGE.
*
* @return the cache level of this resource request.
*/
public String getCacheability();
/**
* 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.
*
*
* @return the portlet mode.
*
* The portlet mode UNDEFINED will be returned if the cache level is
* set to ResourceURL.FULL.
*
*/
public PortletMode getPortletMode ();
/**
* 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.
*
*
* @return the window state.
*
* The window state UNDEFINED will be returned if the cache level is
* set to ResourceURL.FULL.
*
*/
public WindowState getWindowState ();
/**
*
* 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.
*
*
* @return 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 javax.servlet.ServletRequest#startAsync()
* @see javax.servlet.AsyncContext
* @see #isAsyncStarted()
* @see #getDispatcherType()
* @see javax.portlet.filter.ResourceFilter
*/
public 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.
*
* 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.
*
*
* @return 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 javax.servlet.ServletRequest#startAsync()
* @see javax.servlet.AsyncContext
* @see #isAsyncStarted()
* @see #getDispatcherType()
* @see javax.portlet.filter.ResourceFilter
*/
public PortletAsyncContext startPortletAsync(ResourceRequest request, ResourceResponse response) throws IllegalStateException;
/**
*
* 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.
*
*
* @return true if asynchronous mode has been started
* @since 3.0
* @see #startPortletAsync()
* @see #startPortletAsync(ResourceRequest, ResourceResponse)
*/
public boolean isAsyncStarted();
/**
*
* 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.
*
*
* @return true if this request supports asynchronous operation
* @since 3.0
*/
public boolean isAsyncSupported();
/**
*
* Gets the AsyncContext that was created or reinitialized by the most
* recent invocation of startAsync() or
* startAsync(ResourceRequest,ResourceResponse) on this request.
*
*
* @return 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 javax.servlet.ServletRequest#startAsync()
* @see javax.servlet.AsyncContext
*/
public PortletAsyncContext getPortletAsyncContext();
/**
*
* 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.
*
*
* @return the dispatcher type of this request
* @since 3.0
* @see javax.servlet.DispatcherType
*/
public DispatcherType getDispatcherType();
}