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

The javax.portlet.annotations package provides the annotations used for portlet configuration and portlet-specific dependency injection.

Overview

The annotation-oriented API provides new capabilities in several areas.

It allows portlet configuration declarations to be performed through use of annotations. The goal is to reduce or remove the need to write a portlet deployment descriptor in most instances.
The developer can choose between providing configuration data through annotations or through the portlet deployment descriptor. If the same type of information is provided through both annotations and the deployment descriptor, the information from the deployment descriptor has precedence.
It allows portlet lifecycle methods to be identified through use of annotations.
The possible portlet method annotations are: javax.portlet.annotations.InitMethod, javax.portlet.annotations.DestroyMethod, javax.portlet.annotations.ActionMethod, javax.portlet.annotations.EventMethod, javax.portlet.annotations.HeaderMethod, javax.portlet.annotations.RenderMethod, or javax.portlet.annotations.ServeResourceMethod.
Annotated portlet lifecycle methods can be contained in any valid CDI bean class. The class needs not implement any portlet-specific interface or extend a portlet class. However, each bean portlet method has method signature requirements that must be fulfilled. Please see the annotation descriptions.
It provides new custom scopes for portlet artifacts.
- Using the scope annotation javax.portlet.annotations.PortletSessionScoped associates the bean lifecycle with the portlet session.
- Using the scope annotation javax.portlet.annotations.PortletRequestScoped associates the bean lifecycle with the portlet request.
- Using the scope annotation javax.portlet.annotations.RenderStateScoped associates the bean lifecycle with the render state, which conceptually is stored on the URL. If you use RenderStateScoped beans, your bean state will be automatically stored as render parameters for the portlet setting the state.
It allows portlet artifacts such as portlet request filters, URL generation listeners, and preference validators to be identified through annotations.
Please see the following annotation descriptions: javax.portlet.annotations.PortletLifecycleFilter, javax.portlet.annotations.PortletListener, and javax.portlet.annotations.PortletPreferencesValidator.

Injectable Portlet Artifacts

Note: Most of these beans are dependent on the portlet request being executed, but some of them could not themselves be declared as @PortletRequestScoped due to technical limitations. These beans should be used within enclosing beans that are either @RenderStateScoped or @PortletRequestScoped to allow the portlet container to properly manage the lifecycle of the injected object. The required enclosing bean scope is noted in the table.

name	Description	Enclosing Bean Scope	Annotation Example
portletConfig	The PortletConfig object.	Any	@Inject private PortletConfig portletConfig;
portletRequest	The PortletRequest object.	Any	@Inject private PortletRequest request;
portletResponse	The PortletResponse object.	Any	@Inject private PortletResponse request;
actionRequest	The ActionRequest object.	Any	@Inject private ActionRequest request;
actionResponse	The ActionResponse object.	Any	@Inject private ActionResponse request;
headerRequest	The HeaderRequest object.	Any	@Inject private HeaderRequest request;
headerResponse	The HeaderResponse object.	Any	@Inject private HeaderResponse request;
renderRequest	The RenderRequest object.	Any	@Inject private RenderRequest request;
renderResponse	The RenderResponse object.	Any	@Inject private RenderResponse request;
eventRequest	The EventRequest object.	Any	@Inject private EventRequest request;
eventResponse	The EventResponse object.	Any	@Inject private EventResponse request;
resourceRequest	The ResourceRequest object.	Any	@Inject private ResourceRequest request;
resourceResponse	The ResourceResponse object.	Any	@Inject private ResourceResponse request;
clientDataRequest	The ClientDataRequest object.	Any	@Inject private ClientDataRequest request;
mimeResponse	The MimeResponse object.	Any	@Inject private MimeResponse request;
stateAwareResponse	The StateAwareResponse object.	Any	@Inject private StateAwareResponse request;
renderParams	The RenderParameters object.	Any	@Inject private RenderParameters renderParams;
mutableRenderParams	The MutableRenderParameters object.	Any	@Inject private MutableRenderParameters mutableRenderParams;
actionParams	The ActionParameters object.	Any	@Inject private ActionParameters actionParams;
resourceParams	The ResourceParameters object.	Any	@Inject private ResourceParameters resourceParams;
portletContext	The PortletContext object.	Any	@Inject private PortletContext portletContext;
portletPreferences	The PortletPreferences object.	Any	@Inject private PortletPreferences preferences;
portletSession	The PortletSession object.	Any	@Inject private PortletSession session;
portletMode	The PortletMode object.	Any	@Inject private PortletMode mode;
windowState	The WindowState object.	Any	@Inject private WindowState windowState;
cookies	An list of Cookie objects set for the portlet. See `getCookies`.	Any	@Inject private List<Cookie> cookies;
locales	An list of supported Locales for the portlet. See `getLocales`.	Any	@Inject private List<Locale> locales;
namespace	A `String` representing the unique name space for the portlet window. See `getNamespace`.	@PortletRequestScoped or @RenderStateScoped	@Inject private String namespace;
contextPath	A `String` representing the context path for the portlet application. See `getContextPath`.	@PortletRequestScoped or @RenderStateScoped	@Inject private String contextPath;
windowId	A `String` representing the unique window ID for the portlet window. See `getWindowID`.	@PortletRequestScoped or @RenderStateScoped	@Inject private String windowId;
portletName	A `String` representing the portlet name. See `getportletName`.	@PortletRequestScoped or @RenderStateScoped	@Inject private String portletName;

Using the @RenderStateScoped Annotation

The @RenderStateScoped Annotation allows portlet render parameters to be treated as beans. The bean state is stored as a portlet render parameter. The annotation documentation for RenderStateScoped describes the necessary prerequisites.

The paramName element in the annotation can be used to provide a parameter name for storing the bean. This element can also be left empty, in which case the portlet container will generate a parameter name.

When resource URLs are generated, @RenderStateScoped beans valid for the current request are automatically stored on the URL as render parameters. When creating render or action URLs, @RenderStateScoped beans can be automatically stored on the URL with the state valid for the current request by using the appropriate option with the MimeResponse createActionURL and createRenderURL methods.

However, you might want to set a modified @RenderStateScoped bean value on your URL. You can do this using the PortletURL interface setBeanParameter method. You can create a new bean, set the fields as desired, and use the setBeanParameter method to set the new bean on the URL.

Tip: It might be useful to provide your @RenderStateScoped bean with a copy constructor in addition to the required default constructor. You could then create a new @RenderStateScoped bean based on the current state of the injected bean and then update the fields on the new bean as required.

Modifier and Type	Interface and Description
public interface	PortletSerializable This interface must be implemented by `RenderStateScoped` beans in order to allow the bean portlet container to intialize the bean at the beginning of a request and passivate the bean at the end of the request.

Annotation Summary

Modifier and Type	Annotation and Description
public @interface	ActionMethod Designates a method corresponding to the portlet API processAction method.
public @interface	ContextPath Qualifier that specifies the context root for injection.
public @interface	CustomPortletMode This annotation is used within composite portlet configuration annotations to represent a custom portlet mode.
public @interface	CustomWindowState This annotation is used within composite portlet configuration annotations to represent a custom window state.
public @interface	Dependency This annotation is used within composite portlet configuration annotations to represent dependencies the portlet may have on external resources.
public @interface	DestroyMethod Designates a method corresponding to the portlet API destroy method.
public @interface	EventDefinition This annotation is used within composite portlet configuration annotations to represent a single event.
public @interface	EventMethod Designates a method corresponding to the portlet API processEvent method.
public @interface	HeaderMethod Designates a method corresponding to the renderHeaders method of the `HeaderPortlet` interface.
public @interface	InitMethod Designates a method corresponding to the portlet API init method.
public @interface	InitParameter This annotation is used within composite portlet configuration annotations to represent name-value pairs.
public @interface	LocaleString This annotation represents locale-specific strings used within composite portlet configuration annotations to represent information describing the portlet.
public @interface	Multipart This annotation is used within composite portlet configuration annotations to add multipart configuration information.
public @interface	Namespace Qualifier that specifies the namespace for injection.
public @interface	PortletApplication Annotation for the portlet application configuration.
public @interface	PortletConfiguration Annotation for the portlet configuration.
public @interface	PortletConfigurations Annotation for configuration of multiple portlets.
public @interface	PortletLifecycleFilter Designates a portlet request filter class.
public @interface	PortletListener Designates a portlet URL generation listener class.
public @interface	PortletName Qualifier that specifies the portlet name for injection.
public @interface	PortletPreferencesValidator Designates a preferences validator class.
public @interface	PortletQName This annotation is used within composite portlet configuration annotations to represent a QName for use in portlet event and public render parameter definitions.
public @interface	PortletRequestScoped Provides a CDI custom scope for the portlet request.
public @interface	PortletSessionScoped Provides a CDI custom scope that is scoped to the portlet session rather than to the servlet session.
public @interface	Preference This annotation is used within composite portlet configuration annotations to represent a single portlet preference.
public @interface	PublicRenderParameterDefinition This annotation is used within composite portlet configuration annotations to represent a single public render parameter.
public @interface	RenderMethod Designates a method corresponding to the portlet API render method.
public @interface	RenderStateScoped Provides a CDI custom scope that is scoped to the render state.
public @interface	RuntimeOption This annotation is used within composite portlet configuration annotations to represent portlet container runtime option name-value pairs.
public @interface	SecurityRoleRef This annotation is used within composite portlet configuration annotations to represent a single security role reference.
public @interface	ServeResourceMethod Designates a method corresponding to the portlet API serveResource method.
public @interface	Supports This annotation is used within composite portlet configuration annotations to specify the supported portlet modes and window states for a given content type.
public @interface	UserAttribute This annotation is used within composite portlet configuration annotations to represent a single user attribute.
public @interface	WindowId Qualifier that specifies the window ID for injection.

Package javax.portlet.annotations

Overview

Injectable Portlet Artifacts

Using the @RenderStateScoped Annotation

Interface Summary

Annotation Summary