Persistence Service Proposal
============================

GOAL: This proposal aims to establish a flexible mechanism to retrieve, access, and store
      user-specific attributes that belong to a particular portlet.


Services
--------

At the moment it is not clear to us how Jetspeed internal services can be added to 
the framework. We can think of the Persistence Service and a Location Service (determining
the user's current location through wireless network). Others are likely and possible.
We need a mechanism to register and retrieve these services.


Background
----------

The user PSML allows parameters to be stored with each portlet. These parameters consist
of pairs of names and values. Today, these attributes can neither be read nor written.
To enable portlets that render content based on user-specific customization (eg. a POP3-portlet
requires server and account settings) these parameters have to be made accessible to the
portlet in some way.


Persistence Service
-------------------

The idea of the Persistence Service to be minimally intrunsive to the exisiting Portlet API.
The service has to be fed with the current RunData object and a reference to the portlet
that uses the Persistence Service. Everything else is derived from that.

The service provides access to the pages that a portlet appears on. At the moment, this is
just one, but in the future one can think of a user having multiple pages (eg. one for 
sport news, one for jokes, one for work), or a user having different devices (eg. a PC browser
and a WAP phone). The Persistence Service grants access to all these pages where the given
portlet appears on. This way, the portlet can configure itself on all these pages at the same
time. This may not always be necessary or desirable, but there are cases where it is, for example,
to configure a portlet for a WAP phone - given the awkward input methods for WAP phones, the 
configuration is more likely being done on the PC browser.

The service tracks all updates to the attributes on each page during the session. Only when
the store() method is called, the attributes are persistently stored in the respectively
PSML files. If the reset() method is called before the store() method, the attributes are
reset to the values that are stored in the PSML file(s). If the reset() method is called after
the store() method, the attributes are reset to values they had at the last store(). (Very much
like commit and rollback - however, we didn't want to use these names because they may tempt
people to think there was any kind of data integrity behind all this, which may or may not be
the case)

Note: The configuration we are talking about here, is different from the configuration stored
      for the portlet in the portlet registration. That configuration is the same of every 
      instance of the portlet, no matter what the user and page. It is available through
      the PortletConfig object and cannot be changed through the API. It is up to the 
      portal administrator to change to that configuration

Pages
-----

A page is the portlet's view of its configuration data on a particular page. It offers functions
to retrieve, add, and remove attributes to the set of attributes that concern the portlet. An
attribute is a pair of name and value, both being of type string.

If the portlet wishes to store to store than one value for a particular name, it can use a
vector to store all values. An attribute with only one value equals a vector with only
one element. The elements of the vector have to be strings too.