Package jakarta.portlet.annotations

The jakarta.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.

Injectable Portlet Artifacts
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