Portlet Developers Notes:

Note:  This document is meant to detail the design goals for a Portlet API that
has not officially been release yet.  There may be some incorrect implementation
details.

Definition:  

A Portlet (see org.apache.jetspeed.portal) is an object which runs within a 
servlet and represents a small subset of the full document.  A Portlet is 
similar to an Applet running within a web page except Portlets are generated on 
the server and display their GUI with HTML.

Goals:  Porlets were designed to be:

- Easily choosen by the user so that custom page generation is very easy.  They 
  are very similar to Turbine Screens except that you can have muliple Portlets
  within any given screen.

- Fast with a caching subsystem.  This allows even complex Portlets that use
  databases to render HTML fast.
  
- Easily developed and doesn't require the developer to know the implementation
  details of the Engine (JetSpeed) that his Portlet is running under.
  
- Portlets allow other types of content renderers.  A portlet could use the
  facilities of a database via JDBC or complex XML -> XSL -> HTML rendering via 
  something like Cocoon.

- Portlets allow themselves to be skinned so that the user can change the 
  background color or the width of the Portlet or the color of the title bar.
 
- Portlets are managed by a PortletController.  This controller is 
  implementation specific and can be changed by a developer to provide custom
  rendering.
  
- Portlets are rendered and held by a PortletControl.  A PortletControl adds
  the skin to the Portlet and then returns it's content.
  
- Category based subscription.  The XML subscription framework within JetSpeed
  will allow portlets (via Portlet Markup Language) to be organized into 
  categories.  This allows easy management of portlets.

- Portlets are passed a PortletConfig object which includes a URL and a 
  hashtable of parameters.  This way a Portlet can adapt its configuration 
  during runtime by observing its PortletConfig.
  
- Easy to write as an AbstractPortlet defines most of it's behavior in most
  situations.
  
Current Portlets:

    - org.apache.jetspeed.portal.portlets.RSSPortlet:
        - This is the major implementation of Portlets so far.  It takes a URL
          to an RSS (RDF Site Summary (my.netscape.com/publish)) and renders
          it as a Portlet.
    
Future Portlets:

    - A Portlet which holds a Turbine Screen would be excellent.
    - A CocoonPortlet which allows you to use XML/XSL is something on the 
      horizon it is really essential to getting exceptance.