Overview | Package | Class | Tree | Deprecated | Index | Help
| Portlet API 2
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.jetspeed.portlet
Interface Portlet

All Known Implementing Classes:
  SaxPortlet

public interface Portlet

The `Portlet` interface is used by the portlet container to invoke the portlet. However, a portlet cannot directly implement the `Portlet` interface directly. Instead, it has to extend one of the abstract portlet implementations, which indicates to the the portlet container the type of content (eg. content stream or SAX events) that the portlet will generate.

A portlet is a small Java program that runs within a portlet container. Portlets receive and respond to requests from the portlet container. There is ever only object instance of each portlet class, yet each user should be able to a have personalized view of that portlet instance. Therefore, the portlet session carries vital information for the portlet to create a personalized user experience. Portlet instance plus session create a virtual instance of the portlet. This is similar to the way a servlet relates to its servlet container. As a consequence, the portlet should not attempt to store the portlet session or any other user-related information as instance or class variabled. In fact, instance variables of a portlet can be considered to have similar behaviour as class variables, because there is ever only one instance which is shared by multiple threads. Therefore, any instance information has to be either read-only (as is the case for the portlet configuration), or carefully protected by the `synchronized` keyword.

As part of running within the portlet container each portlet has a life-cycle. The corresponding methods are called in the following sequence:

1. The portlet is constructed, then initialized with the `init()` method.
2. Any calls from the portlet container to the `service()` method are handled.
3. The portlet is taken out of service, then destroyed with the `destroy()` method, then garbage collected and finalized.

The virtual instance is created and destroyed with the `beginSession()` and `endSession()`methods, respectively. If a portlet provides personalized views these methods should be implemented so that the initialized portlet session is returned and later destroyed.

The portlet container loads and instantiates the portlet class. This can happen during startup of the portal server or later, but no later then when the first request to the portlet has to be serviced. Also, if a portlet is taken temporarily out of service, for example while administrating it, the portlet container may finish the life-cycle before taking the portlet out of service. When the administration is done, the portlet will be newly initialized.

Inner Class Summary
`static class` | `Portlet.Mode` The `Mode` class is a finite enumeration of the possible modes that a portlet can assume.

Method Summary
`void` | `beginSession(PortletSession session)` Called by the portlet container to ask the portlet to initialize the given portlet session.
`void` | `destroy()` Called by the portlet container to indicate to this portlet that it is taken out of service.
`void` | `endSession(PortletSession session)` Called by the portlet container to indicate to a virtual instance of the portlet is being removed.
`void` | `init(PortletConfig config)` Called by the portlet container to indicate to this portlet that it is put into service.
`void` | `service(PortletRequest request, PortletResponse response)` Called by the portlet container to ask this portlet to generate its markup using the given request/response pair.

Method Detail

### init

    public void init(PortletConfig config)
              throws UnavailableException

  Called by the portlet container to indicate to this portlet that it is put into service.

  The portlet container calls the `init()` method for the whole life-cycle of the portlet. The `init()` method must complete successfully before virtual instances are created through the `beginSession()` method.

  The portlet container cannot place the portlet into service if the `init()` method

  1. Throws a `PortletException`
  2. Does not return within a time period defined by the portlet container.
  Parameters:
    `config` - the portlet configuration
  Throws:
    `UnavailableException` - if an exception has occurrred that interferes with the portlet's normal initialization

### destroy

    public void destroy()

  Called by the portlet container to indicate to this portlet that it is taken out of service. This method is only called once all threads within the portlet's `service()` method have exited or after a timeout period has passed. After the portlet container calls this method, it will not call the `service()` method again on this portlet.

  This method gives the portlet an opportunity to clean up any resources that are being held (for example, memory, file handles, threads).

### beginSession

    public void beginSession(PortletSession session)
                      throws PortletException

  Called by the portlet container to ask the portlet to initialize the given portlet session. If the user is not logged on, the given portlet session is `null`. Before attempting to initialize the session the portlet should check for this condition.

  In addition to initializing the sessionThis method allows the portlet to initialize the virtual instance, for example, to register listeners or customize the portlet window. The portlet session which is passed as argued must not be stored by the portlet.

  Parameters:
    `session` - the portlet session

### endSession

    public void endSession(PortletSession session)

  Called by the portlet container to indicate to a virtual instance of the portlet is being removed. The given portlet session may be `null` if the virtual instance did not create a session during its life-time.

  This method gives the virtual instance of the portlet an opportunity to clean up any resources (for example, memory, file handles, threads), before it is removed. This may happen if the user logs off, or decides to remove this portlet from a page.

  Parameters:
    `session` - the portlet session

### service

    public void service(PortletRequest request,
                        PortletResponse response)
                 throws PortletException,
                        IOException

  Called by the portlet container to ask this portlet to generate its markup using the given request/response pair. Depending on the mode of the portlet and the requesting client device, the markup will be different. Also, the portlet can take language preferences and/or personalized settings into account.
  Parameters:
    `request` - the portlet request
    `response` - the portlet response
  Throws:
    `PortletException` - if the portlet has trouble fulfilling the rendering request
    `IOException` - if the streaming causes an I/O problem

Overview | Package | Class | Tree | Deprecated | Index | Help
| Portlet API 2
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD