javax.portlet

## Class GenericPortlet

- java.lang.Object
- - javax.portlet.GenericPortlet

All Implemented Interfaces:
  EventPortlet, Portlet, PortletConfig, ResourceServingPortlet

    public abstract class GenericPortlet
    extends Object
    implements Portlet, PortletConfig, EventPortlet, ResourceServingPortlet

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.

### Constructor Summary

Constructors
Constructor and Description
`GenericPortlet()` Does nothing.

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `destroy()` Called by the portlet container to indicate to a portlet that the portlet is being taken out of service.
`protected void` `doDispatch(RenderRequest request, RenderResponse response)` The default implementation of this method routes the render request to: method annotated with `@RenderMode</name> and the name of the portlet mode a set of helper methods depending on the current portlet mode the portlet is currently in.`
`protected void` `doEdit(RenderRequest request, RenderResponse response)` Helper method to serve up the `edit` mode.
`protected void` `doHeaders(RenderRequest request, RenderResponse response)` Used by the render method to set the response properties and headers.
`protected void` `doHelp(RenderRequest request, RenderResponse response)` Helper method to serve up the `help` mode.
`protected void` `doView(RenderRequest request, RenderResponse response)` Helper method to serve up the mandatory `view` mode.
`Map<String,String[]>` `getContainerRuntimeOptions()` Returns the container runtime options and values for this portlet.
`String` `getDefaultNamespace()` Returns the default namespace for events and public parameters.
`String` `getInitParameter(String name)` Returns a String containing the value of the named initialization * parameter, or null if the parameter does not exist.
`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.
`protected Collection<PortletMode>` `getNextPossiblePortletModes(RenderRequest request)` Used by the render method to set the next possible portlet modes.
`PortletConfig` `getPortletConfig()` Returns the PortletConfig object of this portlet.
`PortletContext` `getPortletContext()` Returns the `PortletContext` of the portlet application the portlet is in.
`String` `getPortletName()` Returns the name of this portlet.
`Enumeration<QName>` `getProcessingEventQNames()` 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.
`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.
`Enumeration<QName>` `getPublishingEventQNames()` 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.
`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.
`Enumeration<Locale>` `getSupportedLocales()` 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.
`protected String` `getTitle(RenderRequest request)` Used by the render method to get the title.
`void` `init()` A convenience method which can be overridden so that there's no need to call `super.init(config)`.
`void` `init(PortletConfig config)` Called by the portlet container to indicate to a portlet that the portlet is being placed into service.
`void` `processAction(ActionRequest request, ActionResponse response)` Called by the portlet container to allow the portlet to process an action request.
`void` `processEvent(EventRequest request, EventResponse response)` The default implementation tries to dispatch to a method annotated with `@ProcessEvent</name> that matches the event name or, if no such method is found just sets the current render parameters on the response. Note that the annotated methods needs to be public in order to be allowed to be called by `GenericPortlet`.`
`void` `render(RenderRequest request, RenderResponse response)` 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.
`void` `serveResource(ResourceRequest request, ResourceResponse response)` Default resource serving.

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

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

### 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</name> 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 fulfilling the request
  `UnavailableException` - if the portlet is unavailable to process the action at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of 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 fulfilling the request
  `UnavailableException` - if the portlet is unavailable to perform render at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of 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 'javax.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

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</name> 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 fulfilling the request
  `UnavailableException` - if the portlet is unavailable to perform render at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem
See Also:
  `doView(RenderRequest, RenderResponse)`, `doEdit(RenderRequest, RenderResponse)`, `doHelp(RenderRequest, RenderResponse)`

#### doView

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

Helper method to serve up the mandatory `view` mode.

The default implementation throws an exception.

Parameters:
  `request` - the portlet request
  `response` - the render response
Throws:
  `PortletException` - if the portlet cannot fulfilling the request
  `UnavailableException` - if the portlet is unavailable to perform render at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem

#### doEdit

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

Helper method to serve up the `edit` mode.

The default implementation throws an exception.

Parameters:
  `request` - the portlet request
  `response` - the render response
Throws:
  `PortletException` - if the portlet cannot fulfilling the request
  `UnavailableException` - if the portlet is unavailable to perform render at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem

#### doHelp

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

Helper method to serve up the `help` mode.

The default implementation throws an exception.

Parameters:
  `request` - the portlet request
  `response` - the render response
Throws:
  `PortletException` - if the portlet cannot fulfilling the request
  `UnavailableException` - if the portlet is unavailable to perform render at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem

#### 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`

#### getPortletName

    public String getPortletName()

Returns the name of this portlet.

Specified by:
  `getPortletName` in interface `PortletConfig`
Returns:
  the portlet name
See Also:
  `PortletConfig.getPortletName()`

#### getPortletContext

    public PortletContext getPortletContext()

Returns the `PortletContext` of the portlet application the portlet is in.

Specified by:
  `getPortletContext` in interface `PortletConfig`
Returns:
  the portlet application context
See Also:
  `PortletContext`

#### 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 implemention of this method is to call a RequestDispatcher.foward with 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 fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem
Since:
  2.0

#### processEvent

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

The default implementation tries to dispatch to a method annotated with `@ProcessEvent</name> that matches the event name or, if no such method is found just sets the current render parameters on the response.
Note that the annotated methods needs to be public in order to be allowed to be called by `GenericPortlet`.`

Specified by:
  `processEvent` in interface `EventPortlet`
Parameters:
  `request` - the event request
  `response` - the event response
Throws:
  `PortletException` - if the portlet has problems fulfilling the request
  `UnavailableException` - if the portlet is unavailable to process the event at this time
  `PortletSecurityException` - if the portlet cannot fullfill this request because of security reasons
  `IOException` - if the streaming causes an I/O problem
Since:
  2.0
See Also:
  `EventPortlet.processEvent(javax.portlet.EventRequest, javax.portlet.EventResponse)`

#### doHeaders

    protected void doHeaders(RenderRequest request,
                             RenderResponse response)

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
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`.

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()`