FrameworkPortlet (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.portlet

## Class FrameworkPortlet

- java.lang.Object
- - javax.portlet.GenericPortlet
  - - org.springframework.web.portlet.GenericPortletBean
    - - org.springframework.web.portlet.FrameworkPortlet

- All Implemented Interfaces:
    EventListener, EventPortlet, Portlet, PortletConfig, ResourceServingPortlet, Aware, ApplicationListener<ContextRefreshedEvent>, EnvironmentAware, EnvironmentCapable
  Direct Known Subclasses:
    DispatcherPortlet

      public abstract class FrameworkPortlet
      extends GenericPortletBean
      implements ApplicationListener<ContextRefreshedEvent>

  Base portlet for Spring's portlet framework. Provides integration with a Spring application context, in a JavaBean-based overall solution.

  This class offers the following functionality:

  - Manages a Portlet `ApplicationContext` instance per portlet. The portlet's configuration is determined by beans in the portlet's namespace.
  - Publishes events on request processing, whether or not a request is successfully handled.

  Subclasses must implement `doActionService(javax.portlet.ActionRequest, javax.portlet.ActionResponse)` and `doRenderService(javax.portlet.RenderRequest, javax.portlet.RenderResponse)` to handle action and render requests. Because this extends `GenericPortletBean` rather than Portlet directly, bean properties are mapped onto it. Subclasses can override `initFrameworkPortlet()` for custom initialization.

  Regards a "contextClass" parameter at the portlet init-param level, falling back to the default context class (`XmlPortletApplicationContext`) if not found. Note that, with the default FrameworkPortlet, a context class needs to implement the `ConfigurablePortletApplicationContext` SPI.

  Passes a "contextConfigLocation" portlet init-param to the context instance, parsing it into potentially multiple file paths which can be separated by any number of commas and spaces, like "test-portlet.xml, myPortlet.xml". If not explicitly specified, the context implementation is supposed to build a default location from the namespace of the portlet.

  Note: In case of multiple config locations, later bean definitions will override ones defined in earlier loaded files, at least when using one of Spring's default ApplicationContext implementations. This can be leveraged to deliberately override certain bean definitions via an extra XML file.

  The default namespace is "'portlet-name'-portlet", e.g. "test-portlet" for a portlet-name "test" (leading to a "/WEB-INF/test-portlet.xml" default location with XmlPortletApplicationContext). The namespace can also be set explicitly via the "namespace" portlet init-param.

  Since:
    2.0
  Author:
    William G. Thompson, Jr., John A. Lewis, Juergen Hoeller
  See Also:
    `doActionService(javax.portlet.ActionRequest, javax.portlet.ActionResponse)`, `doRenderService(javax.portlet.RenderRequest, javax.portlet.RenderResponse)`, `setContextClass(java.lang.Class)`, `setContextConfigLocation(java.lang.String)`, `setNamespace(java.lang.String)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Class` | `DEFAULT_CONTEXT_CLASS` Default context class for FrameworkPortlet.
    `static String` | `DEFAULT_NAMESPACE_SUFFIX` Suffix for Portlet ApplicationContext namespaces.
    `static String[]` | `DEFAULT_USERINFO_ATTRIBUTE_NAMES` Default USER_INFO attribute names to search for the current username: "user.login.id", "user.name".
    `static String` | `PORTLET_CONTEXT_PREFIX` Prefix for the PortletContext attribute for the Portlet ApplicationContext.

    - ### Fields inherited from class org.springframework.web.portlet.GenericPortletBean

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FrameworkPortlet()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected LocaleContext` | `buildLocaleContext(PortletRequest request)` Build a LocaleContext for the given request, exposing the request's primary locale as current locale.
    `protected ApplicationContext` | `createPortletApplicationContext(ApplicationContext parent)` Instantiate the Portlet ApplicationContext for this portlet, either a default XmlPortletApplicationContext or a custom context class if set.
    `void` | `destroy()` Close the ApplicationContext of this portlet.
    `protected abstract void` | `doActionService(ActionRequest request, ActionResponse response)` Subclasses must implement this method to do the work of action request handling.
    `protected void` | `doDispatch(RenderRequest request, RenderResponse response)` Delegate render requests to processRequest/doRenderService.
    `protected abstract void` | `doEventService(EventRequest request, EventResponse response)` Subclasses must implement this method to do the work of event request handling.
    `protected abstract void` | `doRenderService(RenderRequest request, RenderResponse response)` Subclasses must implement this method to do the work of render request handling.
    `protected abstract void` | `doResourceService(ResourceRequest request, ResourceResponse response)` Subclasses must implement this method to do the work of resource request handling.
    `Class` | `getContextClass()` Return the custom context class.
    `String` | `getContextConfigLocation()` Return the explicit context config location, if any.
    `String` | `getNamespace()` Return the namespace for this portlet, falling back to default scheme if no custom namespace was set.
    `ApplicationContext` | `getPortletApplicationContext()` Return this portlet's ApplicationContext.
    `String` | `getPortletContextAttributeName()` Return the PortletContext attribute name for this portlets's ApplicationContext.
    `protected String` | `getTitle(RenderRequest renderRequest)` Overridden for friendlier behavior in unit tests.
    `protected String` | `getUsernameForRequest(PortletRequest request)` Determine the username for the given request.
    `protected void` | `initFrameworkPortlet()` This method will be invoked after any bean properties have been set and the ApplicationContext has been loaded.
    `protected ApplicationContext` | `initPortletApplicationContext()` Initialize and publish the Portlet ApplicationContext for this portlet.
    `protected void` | `initPortletBean()` Overridden method of GenericPortletBean, invoked after any bean properties have been set.
    `void` | `onApplicationEvent(ContextRefreshedEvent event)` ApplicationListener endpoint that receives events from this servlet's WebApplicationContext.
    `protected void` | `onRefresh(ApplicationContext context)` Template method which can be overridden to add portlet-specific refresh work.
    `protected void` | `postProcessPortletApplicationContext(ConfigurableApplicationContext pac)` Post-process the given Portlet ApplicationContext before it is refreshed and activated as context for this portlet.
    `void` | `processAction(ActionRequest request, ActionResponse response)` Delegate action requests to processRequest/doActionService.
    `void` | `processEvent(EventRequest request, EventResponse response)`
    `protected void` | `processRequest(PortletRequest request, PortletResponse response)` Process this request, publishing an event regardless of the outcome.
    `void` | `refresh()` Refresh this portlet's application context, as well as the dependent state of the portlet.
    `void` | `serveResource(ResourceRequest request, ResourceResponse response)`
    `void` | `setContextClass(Class contextClass)` Set a custom context class.
    `void` | `setContextConfigLocation(String contextConfigLocation)` Set the context config location explicitly, instead of relying on the default location built from the namespace.
    `void` | `setNamespace(String namespace)` Set a custom namespace for this portlet, to be used for building a default context config location.
    `void` | `setPublishContext(boolean publishContext)` Set whether to publish this portlet's context as a PortletContext attribute, available to all objects in the web container.
    `void` | `setPublishEvents(boolean publishEvents)` Set whether this portlet should publish a PortletRequestHandledEvent at the end of each request.
    `void` | `setThreadContextInheritable(boolean threadContextInheritable)` Set whether to expose the LocaleContext and RequestAttributes as inheritable for child threads (using an `InheritableThreadLocal`).
    `void` | `setUserinfoUsernameAttributes(String[] userinfoUsernameAttributes)` Set the list of attributes to search in the USER_INFO map when trying to find the username of the current user.

    - ### Methods inherited from class org.springframework.web.portlet.GenericPortletBean

      `addRequiredProperty, createEnvironment, getEnvironment, getPortletContext, getPortletName, init, initBeanWrapper, setEnvironment`

    - ### Methods inherited from class javax.portlet.GenericPortlet

      `doEdit, doHeaders, doHelp, doView, getContainerRuntimeOptions, getDefaultNamespace, getInitParameter, getInitParameterNames, getNextPossiblePortletModes, getPortletConfig, getProcessingEventQNames, getPublicRenderParameterNames, getPublishingEventQNames, getResourceBundle, getSupportedLocales, init, render`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_CONTEXT_CLASS

          public static final Class DEFAULT_CONTEXT_CLASS

      Default context class for FrameworkPortlet.
      See Also:
        `XmlPortletApplicationContext`

    - #### DEFAULT_NAMESPACE_SUFFIX

          public static final String DEFAULT_NAMESPACE_SUFFIX

      Suffix for Portlet ApplicationContext namespaces. If a portlet of this class is given the name "test" in a context, the namespace used by the portlet will resolve to "test-portlet".
      See Also:
        Constant Field Values

    - #### PORTLET_CONTEXT_PREFIX

          public static final String PORTLET_CONTEXT_PREFIX

      Prefix for the PortletContext attribute for the Portlet ApplicationContext. The completion is the portlet name.

    - #### DEFAULT_USERINFO_ATTRIBUTE_NAMES

          public static final String[] DEFAULT_USERINFO_ATTRIBUTE_NAMES

      Default USER_INFO attribute names to search for the current username: "user.login.id", "user.name".

  - ### Constructor Detail

    - #### FrameworkPortlet

          public FrameworkPortlet()

  - ### Method Detail

    - #### setContextClass

          public void setContextClass(Class contextClass)

      Set a custom context class. This class must be of type ApplicationContext; when using the default FrameworkPortlet implementation, the context class must also implement ConfigurablePortletApplicationContext.
      See Also:
        `createPortletApplicationContext(org.springframework.context.ApplicationContext)`

    - #### getContextClass

          public Class getContextClass()

      Return the custom context class.

    - #### setNamespace

          public void setNamespace(String namespace)

      Set a custom namespace for this portlet, to be used for building a default context config location.

    - #### getNamespace

          public String getNamespace()

      Return the namespace for this portlet, falling back to default scheme if no custom namespace was set. (e.g. "test-portlet" for a portlet named "test")

    - #### setContextConfigLocation

          public void setContextConfigLocation(String contextConfigLocation)

      Set the context config location explicitly, instead of relying on the default location built from the namespace. This location string can consist of multiple locations separated by any number of commas and spaces.

    - #### getContextConfigLocation

          public String getContextConfigLocation()

      Return the explicit context config location, if any.

    - #### setPublishContext

          public void setPublishContext(boolean publishContext)

      Set whether to publish this portlet's context as a PortletContext attribute, available to all objects in the web container. Default is true.

      This is especially handy during testing, although it is debatable whether it's good practice to let other application objects access the context this way.

    - #### setPublishEvents

          public void setPublishEvents(boolean publishEvents)

      Set whether this portlet should publish a PortletRequestHandledEvent at the end of each request. Default is true; can be turned off for a slight performance improvement, provided that no ApplicationListeners rely on such events.
      See Also:
        `PortletRequestHandledEvent`

    - #### setThreadContextInheritable

          public void setThreadContextInheritable(boolean threadContextInheritable)

      Set whether to expose the LocaleContext and RequestAttributes as inheritable for child threads (using an `InheritableThreadLocal`).

      Default is "false", to avoid side effects on spawned background threads. Switch this to "true" to enable inheritance for custom child threads which are spawned during request processing and only used for this request (that is, ending after their initial task, without reuse of the thread).

      WARNING: Do not use inheritance for child threads if you are accessing a thread pool which is configured to potentially add new threads on demand (e.g. a JDK `ThreadPoolExecutor`), since this will expose the inherited context to such a pooled thread.

    - #### setUserinfoUsernameAttributes

          public void setUserinfoUsernameAttributes(String[] userinfoUsernameAttributes)

      Set the list of attributes to search in the USER_INFO map when trying to find the username of the current user.
      See Also:
        `getUsernameForRequest(javax.portlet.PortletRequest)`

    - #### initPortletBean

          protected final void initPortletBean()
                                        throws PortletException

      Overridden method of GenericPortletBean, invoked after any bean properties have been set. Creates this portlet's ApplicationContext.
      Overrides:
        `initPortletBean` in class `GenericPortletBean`
      Throws:
        `PortletException` - if subclass initialization fails

    - #### initPortletApplicationContext

          protected ApplicationContext initPortletApplicationContext()

      Initialize and publish the Portlet ApplicationContext for this portlet.

      Delegates to `createPortletApplicationContext(org.springframework.context.ApplicationContext)` for actual creation. Can be overridden in subclasses.

      Returns:
        the ApplicationContext for this portlet

    - #### createPortletApplicationContext

          protected ApplicationContext createPortletApplicationContext(ApplicationContext parent)

      Instantiate the Portlet ApplicationContext for this portlet, either a default XmlPortletApplicationContext or a custom context class if set.

      This implementation expects custom contexts to implement ConfigurablePortletApplicationContext. Can be overridden in subclasses.

      Parameters:
        `parent` - the parent ApplicationContext to use, or null if none
      Returns:
        the Portlet ApplicationContext for this portlet
      See Also:
        `setContextClass(java.lang.Class)`, `XmlPortletApplicationContext`

    - #### postProcessPortletApplicationContext

          protected void postProcessPortletApplicationContext(ConfigurableApplicationContext pac)

      Post-process the given Portlet ApplicationContext before it is refreshed and activated as context for this portlet.

      The default implementation is empty. `refresh()` will be called automatically after this method returns.

      Parameters:
        `pac` - the configured Portlet ApplicationContext (not refreshed yet)
      See Also:
        `createPortletApplicationContext(org.springframework.context.ApplicationContext)`, `ConfigurableApplicationContext.refresh()`

    - #### getPortletContextAttributeName

          public String getPortletContextAttributeName()

      Return the PortletContext attribute name for this portlets's ApplicationContext.

      The default implementation returns PORTLET_CONTEXT_PREFIX + portlet name.

      See Also:
        `PORTLET_CONTEXT_PREFIX`, `GenericPortletBean.getPortletName()`

    - #### getPortletApplicationContext

          public final ApplicationContext getPortletApplicationContext()

      Return this portlet's ApplicationContext.

    - #### initFrameworkPortlet

          protected void initFrameworkPortlet()
                                       throws PortletException

      This method will be invoked after any bean properties have been set and the ApplicationContext has been loaded.

      The default implementation is empty; subclasses may override this method to perform any initialization they require.

      Throws:
        `PortletException` - in case of an initialization exception

    - #### refresh

          public void refresh()

      Refresh this portlet's application context, as well as the dependent state of the portlet.
      See Also:
        `getPortletApplicationContext()`, `ConfigurableApplicationContext.refresh()`

    - #### onApplicationEvent

          public void onApplicationEvent(ContextRefreshedEvent event)

      ApplicationListener endpoint that receives events from this servlet's WebApplicationContext.

      The default implementation calls `onRefresh(org.springframework.context.ApplicationContext)` in case of a `ContextRefreshedEvent`, triggering a refresh of this servlet's context-dependent state.

      Specified by:
        `onApplicationEvent` in interface `ApplicationListener<ContextRefreshedEvent>`
      Parameters:
        `event` - the incoming ApplicationContext event

    - #### onRefresh

          protected void onRefresh(ApplicationContext context)

      Template method which can be overridden to add portlet-specific refresh work. Called after successful context refresh.

      This implementation is empty.

      Parameters:
        `context` - the current Portlet ApplicationContext
      See Also:
        `refresh()`

    - #### getTitle

          protected String getTitle(RenderRequest renderRequest)

      Overridden for friendlier behavior in unit tests.
      Overrides:
        `getTitle` in class `GenericPortlet`

    - #### processAction

          public final void processAction(ActionRequest request,
                           ActionResponse response)
                                   throws PortletException,
                                          IOException

      Delegate action requests to processRequest/doActionService.
      Specified by:
        `processAction` in interface `Portlet`
      Overrides:
        `processAction` in class `GenericPortlet`
      Throws:
        `PortletException`
        `IOException`

    - #### doDispatch

          protected final void doDispatch(RenderRequest request,
                        RenderResponse response)
                                   throws PortletException,
                                          IOException

      Delegate render requests to processRequest/doRenderService.
      Overrides:
        `doDispatch` in class `GenericPortlet`
      Throws:
        `PortletException`
        `IOException`

    - #### serveResource

          public void serveResource(ResourceRequest request,
                           ResourceResponse response)
                             throws PortletException,
                                    IOException

      Specified by:
        `serveResource` in interface `ResourceServingPortlet`
      Overrides:
        `serveResource` in class `GenericPortlet`
      Throws:
        `PortletException`
        `IOException`

    - #### processEvent

          public void processEvent(EventRequest request,
                          EventResponse response)
                            throws PortletException,
                                   IOException

      Specified by:
        `processEvent` in interface `EventPortlet`
      Overrides:
        `processEvent` in class `GenericPortlet`
      Throws:
        `PortletException`
        `IOException`

    - #### processRequest

          protected final void processRequest(PortletRequest request,
                            PortletResponse response)
                                       throws PortletException,
                                              IOException

      Process this request, publishing an event regardless of the outcome. The actual event handling is performed by the abstract `doActionService()` and `doRenderService()` template methods.
      Throws:
        `PortletException`
        `IOException`
      See Also:
        `doActionService(javax.portlet.ActionRequest, javax.portlet.ActionResponse)`, `doRenderService(javax.portlet.RenderRequest, javax.portlet.RenderResponse)`

    - #### buildLocaleContext

          protected LocaleContext buildLocaleContext(PortletRequest request)

      Build a LocaleContext for the given request, exposing the request's primary locale as current locale.
      Parameters:
        `request` - current HTTP request
      Returns:
        the corresponding LocaleContext

    - #### getUsernameForRequest

          protected String getUsernameForRequest(PortletRequest request)

      Determine the username for the given request.

      The default implementation first tries the UserPrincipal. If that does not exist, then it checks the USER_INFO map. Can be overridden in subclasses.

      Parameters:
        `request` - current portlet request
      Returns:
        the username, or `null` if none found
      See Also:
        `PortletRequest.getUserPrincipal()`, `PortletRequest.getRemoteUser()`, `PortletRequest.USER_INFO`, `setUserinfoUsernameAttributes(java.lang.String[])`

    - #### doActionService

          protected abstract void doActionService(ActionRequest request,
                             ActionResponse response)
                                           throws Exception

      Subclasses must implement this method to do the work of action request handling.

      The contract is essentially the same as that for the `processAction` method of GenericPortlet.

      This class intercepts calls to ensure that exception handling and event publication takes place.

      Parameters:
        `request` - current action request
        `response` - current action response
      Throws:
        `Exception` - in case of any kind of processing failure
      See Also:
        `GenericPortlet.processAction(javax.portlet.ActionRequest, javax.portlet.ActionResponse)`

    - #### doRenderService

          protected abstract void doRenderService(RenderRequest request,
                             RenderResponse response)
                                           throws Exception

      Subclasses must implement this method to do the work of render request handling.

      The contract is essentially the same as that for the `doDispatch` method of GenericPortlet.

      This class intercepts calls to ensure that exception handling and event publication takes place.

      Parameters:
        `request` - current render request
        `response` - current render response
      Throws:
        `Exception` - in case of any kind of processing failure
      See Also:
        `GenericPortlet.doDispatch(javax.portlet.RenderRequest, javax.portlet.RenderResponse)`

    - #### doResourceService

          protected abstract void doResourceService(ResourceRequest request,
                               ResourceResponse response)
                                             throws Exception

      Subclasses must implement this method to do the work of resource request handling.

      The contract is essentially the same as that for the `serveResource` method of GenericPortlet.

      This class intercepts calls to ensure that exception handling and event publication takes place.

      Parameters:
        `request` - current resource request
        `response` - current resource response
      Throws:
        `Exception` - in case of any kind of processing failure
      See Also:
        `GenericPortlet.serveResource(javax.portlet.ResourceRequest, javax.portlet.ResourceResponse)`

    - #### doEventService

          protected abstract void doEventService(EventRequest request,
                            EventResponse response)
                                          throws Exception

      Subclasses must implement this method to do the work of event request handling.

      The contract is essentially the same as that for the `processEvent` method of GenericPortlet.

      This class intercepts calls to ensure that exception handling and event publication takes place.

      Parameters:
        `request` - current event request
        `response` - current event response
      Throws:
        `Exception` - in case of any kind of processing failure
      See Also:
        `GenericPortlet.processEvent(javax.portlet.EventRequest, javax.portlet.EventResponse)`

    - #### destroy

          public void destroy()

      Close the ApplicationContext of this portlet.
      Specified by:
        `destroy` in interface `Portlet`
      Overrides:
        `destroy` in class `GenericPortlet`
      See Also:
        `ConfigurableApplicationContext.close()`