javax.portlet.PortletAsyncContext 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.
*/
package javax.portlet;
/**
*
* Class representing the execution context for an asynchronous operation that was
* initiated on a ResourceRequest.
*
* Portlet asynchronous support is modeled after servlet asynchronous support, and in
* general, the portlet async methods behave in the same manner as their
* AsyncContext analog.
*
* A PortletAsyncContext is created and initialized by a call to
* ResourceRequest#startAsync() or
* ResourceRequest#startAsync(ServletRequest, ServletResponse).
* Repeated invocations of these methods will return the same
* PortletAsyncContext instance, reinitialized as appropriate.
*
* In the event that an asynchronous operation times out, the container will
* invoke the onTimeout method of all PortletAsyncListener instances registered
* with the PortletAsyncContext on which the asynchronous operation was initiated.
* If none of the listeners call complete() or any of the
* dispatch() methods, the portlet container will
* complete the request on behalf of the application and may respond with error information.
*
*
* @see javax.servlet.AsyncContext
* @see PortletAsyncListener
* @see PortletAsyncEvent
*
* @since 3.0
*/
public interface PortletAsyncContext {
/**
*
* Registers the given PortletAsyncListener with the most recent
* asynchronous cycle that was started by a call to one of the
* ResourceRequest.startAsync() methods.
*
* The given PortletAsyncListener will receive an
* PortletAsyncEvent when the
* asynchronous cycle completes successfully, times out, results in an error, or a
* new asynchronous cycle is being initiated via one of the
* ResourceRequest.startAsync() methods.
*
* PortletAsyncListener instances will be notified in the order in
* which they were added.
*
* When one of the listener methods is invoked, the
* PortletAsyncListener getSuppliedRequest() and
* getSuppliedResponse() methods of the
* PortletAsyncEvent object will return null.
*
*
* @see PortletAsyncListener
* @see PortletAsyncEvent
*
* @since 3.0
*
* @param listener the listener to be added
* @throws IllegalStateException
* if this method is called after the container-initiated dispatch, during which
* one of the ResourceRequest.startAsync() methods was called, has
* returned to the container
*
*/
public void addListener(PortletAsyncListener listener) throws IllegalStateException;
/**
*
* Registers the given PortletAsyncListener with the most recent
* asynchronous cycle that was started by a call to one of the
* ResourceRequest.startAsync() methods.
*
* The given PortletAsyncListener will receive an
* PortletAsyncEvent when the
* asynchronous cycle completes successfully, times out, results in an error, or a
* new asynchronous cycle is being initiated via one of the
* ResourceRequest.startAsync() methods.
*
* PortletAsyncListener instances will be notified in the order in
* which they were added.
*
* The given ResourceRequest and ResourceResponse objects will be made
* available to the given PortletAsyncListener via the
* getSuppliedRequest and
* getSuppliedResponse methods, respectively, of the
* PortletAsyncEvent delivered to
* it. These objects should not be read from or written to at the
* time the PortletAsyncEvent is delivered, because additional wrapping
* may have
* occurred since the given PortletAsyncListener was registered.
* However, they may be used to release any resources associated with them.
*
*
* @see PortletAsyncListener
* @see PortletAsyncEvent
*
* @since 3.0
*
* @param listener the listener to be added
* @param request the request object to be included in the PortletAsyncEvent
* @param response the response object to be included in the PortletAsyncEvent
* @throws IllegalStateException
* if this method is called after the container-initiated dispatch, during which
* one of the ResourceRequest.startAsync() methods was called, has
* returned to the container
*
*/
public void addListener(PortletAsyncListener listener, ResourceRequest request, ResourceResponse response) throws IllegalStateException;
/**
*
* Completes the PortletAsynchronous operation
* and closes the response associated with this PortletAsyncContext object.
*
* The onComplete method of any registered listeners that were registered
* with the PortletAsyncContext object for this asynchronous cycle
* will be invoked.
*
* It is legal to call this method any time after a call to
* ResourceRequest#startAsync() or
* ResourceRequest#startAsync(ResourceRequest, ResourceResponse),
* and before a call to one of the dispatch methods of this
* class. If this method is called before the container-initiated dispatch that
* called startAsync has returned to the container, then the call will
* not take effect (and any invocations of
* PortletAsyncListener#onComplete(PortletAsyncEvent) will
* be delayed) until after the container-initiated dispatch has returned to the
* container.
*
*
* @since 3.0
*
* @throws IllegalStateException
* if this method is called before an asynchronous processing cycle was started,
* after it has already been completed, or after a call to
* one of the dispatch() methods
*
*/
public void complete() throws IllegalStateException;
/**
*
* Instantiates the given PortletAsyncListener class.
*
* The returned PortletAsyncListener instance may be further customized before it is
* registered with this PortletAsyncContext via a call to one of the addListener methods.
*
* The given PortletAsyncListener class must define a zero argument constructor, which is
* used to instantiate it.
*
* This method supports resource injection if contextual support is available, and if
* the given class represents a Managed
* Bean. See the Java EE platform and JSR 299 specifications for additional details
* about Managed Beans and resource injection.
*
*
* @since 3.0
*
* @param cls the class to be instantiated
* @return the instantiated class
* @throws PortletException if the given class cannot be instantiated
*/
public T createPortletAsyncListener(Class cls) throws PortletException;
/**
*
* Dispatches the request and response objects of this PortletAsyncContext to
* the portlet container.
*
* The portlet container will dispatch the the request and response to the
* portlet resource method in which the first asynchronous processing cycle was
* initiated.
*
* This method returns immediately after passing the request and response
* objects to a container managed thread which will perform the dispatch
* operation. If this method is called before the container-initiated dispatch
* that called startAsync has returned to the container, the dispatch operation
* will be delayed until after the container-initiated dispatch has returned to
* the container.
*
* The dispatcher type of the request is set to DispatcherType.ASYNC. Unlike
* forward dispatches, the response buffer and headers will not be reset, and
* it is legal to dispatch even if the response has already been committed.
*
* Control over the request and response is delegated to the dispatch target,
* and the response will be closed when the dispatch target has completed
* execution, unless ResourceRequest#startAsync() or
* ResourceRequest#startAsync(ResourceRequest, ResourceResponse) are called.
*
* Any errors or exceptions that may occur during the execution of this method
* must be caught and handled by the container as follows:
*
* -
* Invoke the
onError method of all PortletAsyncListener
* instances registered with this PortletAsyncContext and
* make the caught Throwable available via
* PortletAsyncEvent#getThrowable.
*
* -
* If none of the listeners called
complete() or any of the dispatch()
* methods, set the status code equal to
* HttpResourceResponse.SC_INTERNAL_SERVER_ERROR, make the
* Throwable leading to the error available as the value of the
* RequestDispatcher.ERROR_EXCEPTION request attribute, and perform
* an error dispatch to generate a platform-specific error message.
*
* -
* Complete the asynchronous processing cycle by calling
complete().
*
*
*
* There can be at most one asynchronous dispatch operation per asynchronous
* cycle, which is started by a call to one of the ResourceRequest#startAsync
* methods. Any attempt to perform an additional asynchronous dispatch
* operation within the same asynchronous cycle will result in an
* IllegalStateException. When the container performs the dispatch operation,
* startAsync() may be invoked on the dispatched request to initiate a new
* asynchronous processing cycle, after which any of the dispatch methods or the
* complete() method may be called.
*
*
* @since 3.0
*
* @throws IllegalStateException
* if called before an asynchronous processing cycle has been started,
* if one of the dispatch methods has been called but the startAsync method has not
* been called during the resulting dispatch, or if complete() was called
*/
public void dispatch() throws IllegalStateException;
/**
*
* Dispatches the request and response objects of this PortletAsyncContext to
* the given path within the PortletContext.
*
* The path parameter is interpreted in the same way as in
* PortletContext#getRequestDispatcher(String) scoped to
* the current portlet context.
*
* There can be at most one asynchronous dispatch operation per asynchronous
* cycle, which is started by a call to one of the ResourceRequest#startAsync
* methods. Any attempt to perform an additional asynchronous dispatch
* operation within the same asynchronous cycle will result in an
* IllegalStateException. When the container performs the dispatch operation,
* startAsync() may be invoked on the dispatched request to initiate a new
* asynchronous processing cycle, after which any of the dispatch methods or the
* complete() method may be called.
*
* See {@link #dispatch()} for additional details, including error handling.
*
*
* @since 3.0
*
* @param path the path of the dispatch target, scoped to the PortletContext from which
* this PortletAsyncContext was initialized
* @throws IllegalStateException
* if called before an asynchronous processing cycle has been started,
* if one of the dispatch methods has been called but the startAsync method has not
* been called during the resulting dispatch, or if complete() was called
*/
public void dispatch(String path) throws IllegalStateException;
/**
*
* Gets the request that was used to initialize this PortletAsyncContext by calling
* ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse).
*
*
* @since 3.0
*
* @return The resource request object
* @throws IllegalStateException
* if one of the dispatch methods has been called but the startAsync method has not
* been called during the resulting dispatch, or if complete() was called
*/
public ResourceRequest getResourceRequest() throws IllegalStateException;
/**
*
* Gets the response that was used to initialize this PortletAsyncContext by calling
* ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse).
*
*
* @since 3.0
*
* @return The resource response object
* @throws IllegalStateException
* if one of the dispatch methods has been called but the startAsync method has not
* been called during the resulting dispatch, or if complete() was called
*/
public ResourceResponse getResourceResponse() throws IllegalStateException;
/**
*
* Gets the timeout (in milliseconds) for this PortletAsyncContext.
*
* This method returns the container's default timeout for asynchronous operations,
* or the timeout value passed to the most recent invocation of
* setTimeout(long).
*
* A timeout value of zero or less indicates no timeout.
*
*
* @since 3.0
*
* @return the timeout in milliseconds
*/
public long getTimeout();
/**
*
* Checks if this PortletAsyncContext was initialized with the original or
* application-wrapped request and response objects.
*
* This information may be used by filters invoked in the outbound direction, after
* a request was put into asynchronous mode, to determine whether any request
* and/or response wrappers that they added during their inbound invocation need to
* be preserved for the duration of the asynchronous operation, or may be released.
*
*
* @since 3.0
*
* @return
* true if this PortletAsyncContext was initialized with the original
* request and response objects by calling ResourceRequest.startAsync(),
* or if it was initialized by calling
* ResourceRequest.startAsync(ResourceRequest, ResourceResponse), and neither
* the ResourceRequest nor ResourceResponse arguments carried any
* application-provided wrappers; false otherwise
*/
public boolean hasOriginalRequestAndResponse();
/**
*
* Sets the timeout (in milliseconds) for this PortletAsyncContext.
*
* The timeout applies to this PortletAsyncContext once the
* container-initiated dispatch
* during which one of the ResourceRequest.startAsync() methods was
* called has returned to the container.
*
* The timeout will expire if neither the complete() method nor any of
* the dispatch
* methods are called. A timeout value of zero or less indicates no timeout.
*
* If setTimeout(long) is not called, then the container's default timeout,
* which is available via a call to getTimeout(), will apply.
*
* The default value is 30000 ms.
*
*
* @since 3.0
*
* @param time the timeout in milliseconds
*/
public void setTimeout(long time);
/**
*
* Causes the container to dispatch a thread, possibly from a managed thread pool,
* to run the specified Runnable. The container may propagate appropriate
* contextual information to the Runnable.
*
*
* @since 3.0
*
* @param run the asynchronous handler
* @throws IllegalStateException
* if this method is called before an asynchronous processing cycle was started,
* after it has already been completed, or after a call to
* one of the dispatch() methods
*
**/
public void start(Runnable run) throws IllegalStateException;
}