Package javax.portlet.annotations

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

See: Description

Interface Summary

Interface	Description
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 Types Summary

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

Package javax.portlet.annotations Description

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: InitMethod, DestroyMethod, ActionMethod, EventMethod, HeaderMethod, RenderMethod, or 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 PortletSessionScoped associates the bean lifecycle with the portlet session.
  • Using the scope annotation PortletRequestScoped associates the bean lifecycle with the portlet request.
  • Using the scope annotation 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: PortletLifecycleFilter, PortletListener, and 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.

Since:

3.0