Java Portlet API V3.0 3.0.1 · javax.portlet.PortletAsyncContext

Method Summary

Modifier and Type	Method and Description
public void	addListener(PortletAsyncListener the listener to be added listener) Registers the given `PortletAsyncListener` with the most recent asynchronous cycle that was started by a call to one of the `ResourceRequest.startAsync()` methods.
public void	addListener(PortletAsyncListener the listener to be added listener, ResourceRequest the request object to be included in the `PortletAsyncEvent` request, ResourceResponse the response object to be included in the `PortletAsyncEvent` response) Registers the given `PortletAsyncListener` with the most recent asynchronous cycle that was started by a call to one of the `ResourceRequest.startAsync()` methods.
public void	complete() Completes the `PortletAsynchronous` operation and closes the response associated with this `PortletAsyncContext` object.
public <T extends PortletAsyncListener> T	Returns: the instantiated class createPortletAsyncListener(Class<T> the class to be instantiated cls) Instantiates the given `PortletAsyncListener` class.
public void	dispatch() Dispatches the request and response objects of this `PortletAsyncContext` to the portlet container.
public void	dispatch(String the path of the dispatch target, scoped to the PortletContext from which this PortletAsyncContext was initialized path) Dispatches the request and response objects of this `PortletAsyncContext` to the given path within the `PortletContext`.
public ResourceRequest	Returns: The resource request object getResourceRequest() Gets the request that was used to initialize this `PortletAsyncContext` by calling `ResourceRequest.startAsync()` or `ResourceRequest.startAsync(ServletRequest, ServletResponse)`.
public ResourceResponse	Returns: The resource response object getResourceResponse() Gets the response that was used to initialize this `PortletAsyncContext` by calling `ResourceRequest.startAsync()` or `ResourceRequest.startAsync(ServletRequest, ServletResponse)`.
public long	Returns: the timeout in milliseconds getTimeout() Gets the timeout (in milliseconds) for this PortletAsyncContext.
public boolean	Returns: `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 hasOriginalRequestAndResponse() Checks if this `PortletAsyncContext` was initialized with the original or application-wrapped request and response objects.
public void	setTimeout(long the timeout in milliseconds time) Sets the timeout (in milliseconds) for this `PortletAsyncContext`.
public void	start(Runnable the asynchronous handler run) Causes the container to dispatch a thread, possibly from a managed thread pool, to run the specified `Runnable`.

Method Detail

addListener back to summary

addListener	back to summary
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. When one of the listener methods is invoked, the `PortletAsyncListener` `getSuppliedRequest()` and `getSuppliedResponse()` methods of the `PortletAsyncEvent` object will return `null`. Parameters listener:PortletAsyncListener the listener to be added Exceptions 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 See Also `PortletAsyncListener`, `PortletAsyncEvent`

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.

When one of the listener methods is invoked, the PortletAsyncListener getSuppliedRequest() and getSuppliedResponse() methods of the PortletAsyncEvent object will return null.

Parameters

listener:PortletAsyncListener: the listener to be added

Exceptions

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

addListener back to summary

addListener	back to summary
public void addListener(PortletAsyncListener listener, ResourceRequest request, ResourceResponse response) 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. Parameters listener:PortletAsyncListener the listener to be added request:ResourceRequest the request object to be included in the `PortletAsyncEvent` response:ResourceResponse the response object to be included in the `PortletAsyncEvent` Exceptions 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 See Also `PortletAsyncListener`, `PortletAsyncEvent`

public void addListener(PortletAsyncListener listener, ResourceRequest request, ResourceResponse response) 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.

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.

Parameters

listener:PortletAsyncListener: the listener to be added
request:ResourceRequest: the request object to be included in the PortletAsyncEvent
response:ResourceResponse: the response object to be included in the PortletAsyncEvent

Exceptions

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

complete back to summary

complete	back to summary
public void complete() 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. Exceptions 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

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.

Exceptions

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

createPortletAsyncListener back to summary

createPortletAsyncListener	back to summary
public <T extends PortletAsyncListener> T createPortletAsyncListener(Class<T> cls) throws PortletException 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. Parameters cls:Class<T> the class to be instantiated Returns:T the instantiated class Exceptions PortletException: if the given class cannot be instantiated

public <T extends PortletAsyncListener> T createPortletAsyncListener(Class<T> cls) throws PortletException

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.

Parameters

cls:Class<T>: the class to be instantiated

Returns:T

the instantiated class

Exceptions

PortletException:: if the given class cannot be instantiated

dispatch back to summary

dispatch	back to summary
public void dispatch() throws IllegalStateException 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. Exceptions 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 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.

Exceptions

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

dispatch back to summary

dispatch	back to summary
public void dispatch(String path) 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 `dispatch()` for additional details, including error handling. Parameters path:String the path of the dispatch target, scoped to the PortletContext from which this PortletAsyncContext was initialized Exceptions 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

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.

See dispatch() for additional details, including error handling.

Parameters

path:String: the path of the dispatch target, scoped to the PortletContext from which this PortletAsyncContext was initialized

Exceptions

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

getResourceRequest back to summary

getResourceRequest	back to summary
public ResourceRequest getResourceRequest() throws IllegalStateException Gets the request that was used to initialize this `PortletAsyncContext` by calling `ResourceRequest.startAsync()` or `ResourceRequest.startAsync(ServletRequest, ServletResponse)`. Returns:ResourceRequest The resource request object Exceptions 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 request that was used to initialize this PortletAsyncContext by calling ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse).

Returns:ResourceRequest

The resource request object

Exceptions

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

getResourceResponse back to summary

getResourceResponse	back to summary
public ResourceResponse getResourceResponse() throws IllegalStateException Gets the response that was used to initialize this `PortletAsyncContext` by calling `ResourceRequest.startAsync()` or `ResourceRequest.startAsync(ServletRequest, ServletResponse)`. Returns:ResourceResponse The resource response object Exceptions 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 response that was used to initialize this PortletAsyncContext by calling ResourceRequest.startAsync() or ResourceRequest.startAsync(ServletRequest, ServletResponse).

Returns:ResourceResponse

The resource response object

Exceptions

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

getTimeout back to summary

getTimeout	back to summary
public long getTimeout() 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. Returns:long the timeout in milliseconds

public long getTimeout()

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.

Returns:long: the timeout in milliseconds

hasOriginalRequestAndResponse back to summary

hasOriginalRequestAndResponse	back to summary
public boolean hasOriginalRequestAndResponse() 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. Returns:boolean `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()

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.

Returns:boolean: 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

setTimeout back to summary

setTimeout	back to summary
public void setTimeout(long time) 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. Parameters time:long the timeout in milliseconds

public void setTimeout(long time)

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.

Parameters

time:long: the timeout in milliseconds

start back to summary

start	back to summary
public void start(Runnable run) throws IllegalStateException 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`. Parameters run:Runnable the asynchronous handler Exceptions 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

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.

Parameters

run:Runnable: the asynchronous handler

Exceptions

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 Interface PortletAsyncContext

Method Summary

Method Detail