Package jakarta.portlet

Class GenericPortlet

  • All Implemented Interfaces:
    EventPortlet, HeaderPortlet, Portlet, PortletConfig, ResourceServingPortlet
    public abstract class GenericPortlet
extends Object
implements Portlet, PortletConfig, EventPortlet, ResourceServingPortlet, HeaderPortlet
    The GenericPortlet class provides a default implementation for the Portlet interface.

    It provides an abstract class to be subclassed to create portlets. A subclass of GenericPortlet should either use one of the following annotations:

    • @ProcessAction
    • @ProcessEvent
    • @RenderMode
    or override at least one method, usually one of the following:
    • processAction, to handle action requests
    • doView, to handle render requests when in VIEW mode
    • doEdit, to handle render requests when in EDIT mode
    • doHelp, to handle render request when in HELP mode
    • init and destroy, to manage resources that are held for the life of the servlet

    Normally there is no need to override the render or the doDispatch methods. Render handles render requests setting the title of the portlet in the response and invoking doDispatch. doDispatch dispatches the request to one of the doView, doEdit or doHelp method depending on the portlet mode indicated in the request.

    Portlets typically run on multithreaded servers, so please note that a portlet must handle concurrent requests and be careful to synchronize access to shared resources. Shared resources include in-memory data such as instance or class variables and external objects such as files, database connections, and network connections.

    • Field Detail

      • AUTOMATIC_RESOURCE_DISPATCH

        public static final String AUTOMATIC_RESOURCE_DISPATCH
        This property is set by the container if the container has a cached response for the given validation tag. The property can be retrieved using the getProperty method.

        The value is "jakarta.portlet.automaticResourceDispatching".

        Since:
        3.0
        See Also:
        Constant Field Values

    • Constructor Detail

      • GenericPortlet

        public GenericPortlet()
        Does nothing.

    • Method Detail

      • init

        public void init​(PortletConfig config)
          throws PortletException
        Called by the portlet container to indicate to a portlet that the portlet is being placed into service.

        The default implementation stores the PortletConfig object and checks for annotated methods with the annotations

        • @ProcessAction
        • @ProcessEvent
        • @RenderMode
        and stores these in a hashmap for later dispatching.

        The portlet container calls the init method exactly once after instantiating the portlet. The init method must complete successfully before the portlet can receive any requests.

        The portlet container cannot place the portlet into service if the init method does one of the following:

        1. it throws a PortletException
        2. it does not return within a time period defined by the Web server
        Specified by:
        init in interface Portlet
        Parameters:
        config - a PortletConfig object containing the portlet configuration and initialization parameters
        Throws:
        PortletException - if an exception has occurred that interferes with the portlet normal operation.
        UnavailableException - if the portlet cannot perform the initialization at this time.

      • init

        public void init()
          throws PortletException
        A convenience method which can be overridden so that there's no need to call super.init(config).

        Instead of overriding init(PortletConfig), simply override this method and it will be called by GenericPortlet.init(PortletConfig config). The PortletConfig object can still be retrieved via getPortletConfig().

        Throws:
        PortletException - if an exception has occurred that interferes with the portlet normal operation.
        UnavailableException - if the portlet is unavailable to perform init

      • processAction

        public void processAction​(ActionRequest request,
                          ActionResponse response)
                   throws PortletException,
                          IOException
        Called by the portlet container to allow the portlet to process an action request. This method is called if the client request was originated by a URL created (by the portlet) with the RenderResponse.createActionURL() method.

        The default implementation tries to dispatch to a method annotated with @ProcessAction that matches the action parameter value ActionRequest.ACTION_NAME or, if no such method is found throws a PortletException.
        Note that the annotated methods needs to be public in order to be allowed to be called by GenericPortlet.

        Specified by:
        processAction in interface Portlet
        Parameters:
        request - the action request
        response - the action response
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to process the action at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem

      • renderHeaders

        public void renderHeaders​(HeaderRequest request,
                          HeaderResponse response)
                   throws PortletException,
                          IOException
        V3 method implementing the headers stage within the render phase. The default implementation does nothing.

        Version 3 portlets should override this method to set HTTP headers, cookies, and to provide markup for the overall document HEAD section.

        Specified by:
        renderHeaders in interface HeaderPortlet
        Parameters:
        request - the header request
        response - the header response
        Throws:
        PortletException - if the portlet has problems fulfilling the request
        UnavailableException - if the portlet is unavailable to process the request at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem

      • render

        public void render​(RenderRequest request,
                   RenderResponse response)
            throws PortletException,
                   IOException
        The default implementation of this method sets the headers using the doHeaders method, sets the title using the getTitle method and invokes the doDispatch method.

        It also evaluates the RENDER_PART request attribute and if set calls the doHeaders, getNextPossiblePortletModes and getTitle methods for the RENDER_HEADERS part and the doDispatch method for the RENDER_MARKUP part.
        If the RENDER_PART request attribute is not set all of the above methods will be called.

        Specified by:
        render in interface Portlet
        Parameters:
        request - the render request
        response - the render response
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to perform render at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem

      • getTitle

        protected String getTitle​(RenderRequest request)
        Used by the render method to get the title.

        The default implementation gets the title from the ResourceBundle of the PortletConfig of the portlet. The title is retrieved using the 'jakarta.portlet.title' resource name.

        Portlets can overwrite this method to provide dynamic titles (e.g. based on locale, client, and session information). Examples are:

        • language-dependent titles for multi-lingual portals
        • shorter titles for WAP phones
        • the number of messages in a mailbox portlet
        Parameters:
        request - the render request
        Returns:
        the portlet title for this window
        Throws:
        IllegalStateException - if no portlet config object is available

      • doDispatch

        protected void doDispatch​(RenderRequest request,
                          RenderResponse response)
                   throws PortletException,
                          IOException
        The default implementation of this method routes the render request to:
        1. method annotated with @RenderMode and the name of the portlet mode
        2. a set of helper methods depending on the current portlet mode the portlet is currently in. These methods are:
          • doView for handling view requests
          • doEdit for handling edit requests
          • doHelp for handling help requests

        If the window state of this portlet is minimized, this method does not invoke any of the portlet mode rendering methods.

        For handling custom portlet modes the portlet should either use the @RenderMode annotation or override this method. Note that the annotated methods needs to be public in order to be allowed to be called by GenericPortlet.

        Parameters:
        request - the render request
        response - the render response
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to perform render at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        See Also:
        doView(RenderRequest, RenderResponse), doEdit(RenderRequest, RenderResponse), doHelp(RenderRequest, RenderResponse)

      • getPortletConfig

        public PortletConfig getPortletConfig()
        Returns the PortletConfig object of this portlet.
        Returns:
        the PortletConfig object of this portlet

      • destroy

        public void destroy()
        Called by the portlet container to indicate to a portlet that the portlet is being taken out of service.

        The default implementation does nothing.

        Specified by:
        destroy in interface Portlet

      • getResourceBundle

        public ResourceBundle getResourceBundle​(Locale locale)
        Gets the resource bundle for the given locale based on the resource bundle defined in the deployment descriptor with resource-bundle tag or the inlined resources defined in the deployment descriptor.
        Specified by:
        getResourceBundle in interface PortletConfig
        Parameters:
        locale - the locale for which to retrieve the resource bundle
        Returns:
        the resource bundle for the given locale

      • getInitParameter

        public String getInitParameter​(String name)
        Returns a String containing the value of the named initialization * parameter, or null if the parameter does not exist.
        Specified by:
        getInitParameter in interface PortletConfig
        Parameters:
        name - a String specifying the name of the initialization parameter
        Returns:
        a String containing the value of the initialization parameter
        Throws:
        IllegalArgumentException - if name is null.

      • getInitParameterNames

        public Enumeration<String> getInitParameterNames()
        Returns the names of the portlet initialization parameters as an Enumeration of String objects, or an empty Enumeration if the portlet has no initialization parameters.
        Specified by:
        getInitParameterNames in interface PortletConfig
        Returns:
        an Enumeration of String objects containing the names of the portlet initialization parameters, or an empty Enumeration if the portlet has no initialization parameters.

      • getProcessingEventQNames

        public Enumeration<QName> getProcessingEventQNames()
        Description copied from interface: PortletConfig
        Returns the QNames of the processing events supported by the portlet as an Enumeration of QName objects, or an empty Enumeration if the portlet has not defined any processing events.

        Processing events are defined in the portlet deployment descriptor with the supported-processing-event element.

        If the event was defined using the name element instead of the qname element the defined default namespace is added as namespace for the returned QName.

        Specified by:
        getProcessingEventQNames in interface PortletConfig
        Returns:
        an Enumeration of QName objects containing the names of the processing events, or an empty Enumeration if the portlet has not defined any support for processing events in the deployment descriptor.

      • getPublishingEventQNames

        public Enumeration<QName> getPublishingEventQNames()
        Description copied from interface: PortletConfig
        Returns the QNames of the publishing events supported by the portlet as an Enumeration of QName objects, or an empty Enumeration if the portlet has not defined any publishing events.

        Publishing events are defined in the portlet deployment descriptor with the supported-publishing-event element.

        Note that this call does not return any events published that have not been declared in the deployment descriptor as supported.

        If the event was defined using the name element instead of the qname element the defined default namespace is added as namespace for the returned QName.

        Specified by:
        getPublishingEventQNames in interface PortletConfig
        Returns:
        an Enumeration of QName objects containing the names of the publishing events, or an empty Enumeration if the portlet has not defined any support for publishing events in the deployment descriptor.

      • getSupportedLocales

        public Enumeration<Locale> getSupportedLocales()
        Description copied from interface: PortletConfig
        Returns the locales supported by the portlet as an Enumeration of Locale objects, or an empty Enumeration if the portlet has not defined any supported locales.

        Supported locales are defined in the portlet deployment descriptor with the supported-locale element.

        Specified by:
        getSupportedLocales in interface PortletConfig
        Returns:
        an Enumeration of Locale objects containing the supported locales, or an empty Enumeration if the portlet has not defined any supported locales in the deployment descriptor.

      • getContainerRuntimeOptions

        public Map<String,​String[]> getContainerRuntimeOptions()
        Description copied from interface: PortletConfig
        Returns the container runtime options and values for this portlet.

        The portlet can set container runtime options in the portlet.xml via the container-runtime-option element with a name and a value on the application and portlet level.
        If a container runtime option is set on the portlet application level and on the portlet level with the same name the setting on the portlet level takes precedence and overwrites the one set on the portal application level.

        The map returned from this method will provide the subset the portlet container supports of the options the portlet has specified in the portlet.xml. Options that the portlet container does not support will not be returned in this map.

        The map will contain name of the runtime option as key of type String and the runtime options as values of type String array (String[]) with the values specified in the portlet.xml deployment descriptor.

        Specified by:
        getContainerRuntimeOptions in interface PortletConfig
        Returns:
        an immutable Map containing portlet container runtime options names as keys and the container runtime values as map values, or an empty Map if no portlet container runtime options are set in the portlet.xml or supported by this portlet container. The keys in the map are of type String. The values in the map are of type String array (String[]).

      • serveResource

        public void serveResource​(ResourceRequest request,
                          ResourceResponse response)
                   throws PortletException,
                          IOException
        Default resource serving.

        The default implementation of this method does nothing.

        However, if the reserved portlet initialization parameter AUTOMATIC_RESOURCE_DISPATCH (= "jakarta.portlet.automaticResourceDispatching") is set to true, the default implementation will perform a PortletRequestDispatcher.forward to the location designated by the ResourceID of the ResourceRequest. If no ResourceID is set on the resource URL the default implementation does nothing.

        Specified by:
        serveResource in interface ResourceServingPortlet
        Parameters:
        request - the resource request
        response - the resource response
        Throws:
        PortletException - if the portlet has problems fulfilling the rendering request
        UnavailableException - if the portlet is unavailable to perform render at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        Since:
        2.0

      • doHeaders

        protected void doHeaders​(RenderRequest request,
                         RenderResponse response)
                  throws PortletException,
                         IOException
        Used by the render method to set the response properties and headers.

        The portlet should override this method and set its response header using this method in order to ensure that they are set before anything is written to the output stream.

        The default implemention of this method is emtpy.

        Parameters:
        request - the render request
        response - the render response
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to perform render at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        Since:
        2.0

      • getNextPossiblePortletModes

        protected Collection<PortletMode> getNextPossiblePortletModes​(RenderRequest request)
        Used by the render method to set the next possible portlet modes.

        The portlet should override this method and set the next possible portlet modes using this method in order to ensure that they are set before anything is written to the output stream.

        The default implemention of this method returns null.

        Parameters:
        request - the render request
        Returns:
        the next possible portlet modes
        Since:
        2.0

      • getPublicRenderParameterNames

        public Enumeration<String> getPublicRenderParameterNames()
        Returns the names of the public render parameters supported by the portlet as an Enumeration of String objects, or an empty Enumeration if the portlet has no public render parameters.
        Specified by:
        getPublicRenderParameterNames in interface PortletConfig
        Returns:
        an Enumeration of String objects containing the names of the public render parameters, or an empty Enumeration if the portlet does not define any public render parameters.
        See Also:
        PortletConfig.getPublicRenderParameterNames()

      • getDefaultNamespace

        public String getDefaultNamespace()
        Returns the default namespace for events and public parameters. This namespace is defined in the portlet deployment descriptor with the default-namespace element.

        If no default namespace is defined in the portlet deployment descriptor this methods returns the XML default namespace XMLConstants.NULL_NS_URI.

        Specified by:
        getDefaultNamespace in interface PortletConfig
        Returns:
        the default namespace defined in the portlet deployment descriptor, or XMLConstants.NULL_NS_URI is non is defined.
        See Also:
        PortletConfig.getDefaultNamespace()

      • getPublicRenderParameterDefinitions

        public Map<String,​QName> getPublicRenderParameterDefinitions()
        Returns a Map of public render parameter names to their qualified names. The names are the values returned by the PortletConfig.getPublicRenderParameterNames() method. The values are the QName values associated with the public render parameter.

        If the public render parameter is specified in the portlet descriptor using the <name> tag rather than the <qname> tag, the QName is built from the default namespace from the deployment descriptor together with the value from the <name> tag.

        Specified by:
        getPublicRenderParameterDefinitions in interface PortletConfig
        Returns:
        an Map of String to QName
        Since:
        3.0
        See Also:
        PortletConfig.getPublicRenderParameterNames()

      • dispatchAnnotatedActionMethod

        protected boolean dispatchAnnotatedActionMethod​(String name,
                                                ActionRequest request,
                                                ActionResponse response)
                                         throws PortletException,
                                                IOException
        Dispatches an action request to an annotated action method.

        Retrieves an action method annotated with the provided name and invokes it. Returns true if the method could be successfully located and invoked, and false if no annotated action method by that name could be found.

        This method allows a portlet to extend annotation processing for the action method.

        Parameters:
        name - Annotation name
        request - Action request
        response - Action response
        Returns:
        true, if the request was dispatched, false, if no annotated method matching the specified action method name could be found.
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to process the action at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        Since:
        3.0
        See Also:
        processAction(ActionRequest, ActionResponse)

      • dispatchAnnotatedEventMethod

        protected boolean dispatchAnnotatedEventMethod​(String name,
                                               EventRequest request,
                                               EventResponse response)
                                        throws PortletException,
                                               IOException
        Dispatches an event request to an annotated event method.

        Retrieves an action method annotated with the provided name and invokes it. Returns true if the method could be successfully located and invoked, and false if no annotated event method by that name could be found.

        This method allows a portlet to extend annotation processing for portlet events.

        Parameters:
        name - Annotation name
        request - Event request
        response - Event response
        Returns:
        true, if the request was dispatched, false, if no annotated method matching the specified event method name could be found.
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to process the action at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        Since:
        3.0
        See Also:
        processEvent(EventRequest, EventResponse)

      • dispatchAnnotatedRenderMethod

        protected boolean dispatchAnnotatedRenderMethod​(String name,
                                                RenderRequest request,
                                                RenderResponse response)
                                         throws PortletException,
                                                IOException
        Dispatches an render request to an annotated render method.

        Retrieves an render method annotated with the provided name and invokes it. Returns true if the method could be successfully located and invoked, and false if no annotated render method by that name could be found.

        This method allows a portlet to extend annotation processing for the render methods.

        Parameters:
        name - Annotation name
        request - Render request
        response - Render response
        Returns:
        true, if the request was dispatched, false, if no annotated method matching the specified render method name could be found.
        Throws:
        PortletException - if the portlet cannot fulfill the request
        UnavailableException - if the portlet is unavailable to process the render at this time
        PortletSecurityException - if the portlet cannot fulfill this request due to security reasons
        IOException - if the streaming causes an I/O problem
        Since:
        3.0
        See Also:
        doDispatch(RenderRequest, RenderResponse)