[wsrp][interfaces]: Portal Usage Scenario

[Michael Freedman <Michael.Freedman@oracle.com>]

I have attached a short document describing a portal's possible usage pattern
for portlets using the terms we discussed last week.  Please comment/annotate
with new operations or suggested operations to remove.  Please don't
annotate with questions intended to clarify the behavior of the operation,
send these separately. The goal for this Thursday's meeting is to see if
we can agree on a preliminary usage pattern and collection of operations.
Hopefully we can then move into enumerating the questions we need to answer. 
In our discussion on Thursday, I expect we will need to classify at least
the operational aspects of the usage scenario along two axes:

Axis 1:  Is this a valid Portal operation?

• Yes, we all agree this a valid operation
• No, we all agree this is not a valid operation
• Maybe, there is debate whether this is a valid operation.
• Don't know, we need more information and discussion to understand the operation before classifying it.

Axis 2: Should this operation be covered/enabled by our spec?

• Yes, we all agree.
• Yes, but it should be addressed in a later revision.
• No, we all agree.
• Maybe, there is debate whether we should address this.
• Don't know, we need more information to decide.

It might be useful if each of you did your own classification (assuming
of course the usage scenario isn't grossly controversial).

    -Mike-
 
 

 

>  





During our last conference call we defined some terms representing (potentially
logical) entities the portal communciates to bind and operate on a "producer",
aka a portlet.  This identification was meant to be the first step
in describing how a portal interacts with a portlet.  Though we haven't
reached full closure on the definitions I would like to take a stab at
describing how a portal operates on/with these.  I.e. a portal usage
pattern of a portlet.  The intent is to provide a strawman description
from which discussion can ensue until its refined suitably to satisfy us. 
I have tried to keep the terminolgy abstract as its not my intent to define
the way a mechanism is specifically provided.

Terms:
 

portlet service: the web service component that implements WSRP.  From the portal's perspective this is the registration entity.  I.e. the entity it binds to in order to expose a specific portlet capability.

portlet template: the design entity representing a (potentially customized) portlet service used to create portlet instances.  From the portal's perspective, once its bound to a portlet service, it will expose a representation of this service, often in a portlet toolbox, which allows users to create specific instances  (on a page).

portlet instance: a portlet on a page; or more generically a portlet in the portal layout structure.  From a portal's perspective, the portlet instance is the  realization of the portlet in the runtime layout structure.  A portlet instance is derived from a portlet template.  e.g. when adding a portlet to a page, the  user chooses a portlet template (from the toolbox).  The template is used to "type" the instance being created.

personalization data: a set of customized data settings for a portlet instance. There is an 1 to N relationship between personalization data and portlet instances.  1 set of personalizations may be shared between multiple instances.

portlet template settings: a set of customized data settings for a portlet template.

State 0:  Portlet Service Unknown

> The portal has no knowledge that a portlet service exists.

State 1:  Portlet Service becomes known

The binding stage occurs once.  That is once a portlet service is bound into a portal its is not rebound unless/until it goes back to "State 0: Portlet Unknown".   It is possible to have multiple binding to the same portlet service from the same portal.  Each binding however is seen distinct from the other.

The bind process is begun by making the location of the portlet service known to the portal.  Where/how this location is introduced is undefined. For example, it might be via browsing an UDDI or some other registry, direct registration via URL, local deployment, etc.

Once knowing the location of the portlet service, the portal can activate the service, acquire meta information about the service, and ultimately communicate with it to provide the defined portlet function.  During the "binding" phase, the portal will acquire the meta information it needs to properly operate the service in an efficient manner.  During the "binding" phase, it also registers itself with the portlet service.  Registration is intended to among other things to allow portlets to :

• establish the portal's identity
• establish a trusted relationship with the portal (that can be maintained in all subsequent calls)
• initialize/adapt themselves properly to work with this specific portal
• complete a subscription process

The end result of this stage is that the portal is set up and ready to communicate with the portlet service to provide the portlet's function.  The portlet service is set up and ready to receive communication from this specific portal and provide the function.  I.e. from the portals perspective the portlet is active and online.

At this point the portal [may] expose the bound portlet service to (a subset of) its users by creating an initial portlet template in its toolbox.
 

State 2: Portlet Service Active

"Active" implies being "online".  That is not only is the portal ready to operate the portlet service, but the portlet service is also available to receive these requests.  If at some point during the portal's operation the portlet service becomes unavailable or the portal decides to suspend communciation, the portlet is considered "Inactive" or offline [see State 3].

While a portlet service is active, the portal exposes the full functional breadth of the portlet.  For purposes of clarity the function description is segmented to differentiate between the function supported on the portlet template and the function supported on the portlet instance.

The portal allows one to operate on a portlet template as follows:

• You can use a portlet template to create a portlet instance.  The portlet template defines the initial settings of the portlet instance.
• You can modify the portlet template's settings to change its default/defined behavior.  Such changes only impact future portlet instances created from this template.  Prior instances are unaffected.
•  You can copy a portlet template.  By copy it is meant that a second portlet template comes into being (within the toolbox) with its settings being a duplicate of the template it was copied from (vs. the initial default settings defined by the portlet service).
• You can delete the portlet template.
• You can migrate a portlet template.  By migrate it is meant that controlling portal can transfer the portlet template to another portal.
• You can upgrade a portlet template to a new version.

The portal allows one to operate on a portlet instance as follows:

• You can modify the portlet instance's settings to personalize its behavior.  There are an arbitrary set of personalization levels defined by the particular portal.  The levels are hierarchical.  The deepest personalization level that has any overriding values controls the user's view.  
• You can copy a portlet instance.  By copy it is meant that a second portlet instance comes into being with its personalization data being a duplicate of the instance it was copied from.
• You can clone a portlet instance.  By close it is meant that a second portlet instance comes into being with its personalization data being shared with the portlet it was cloned from.
• You can convert a portlet instance into a portlet template.
• You can migrate a portlet instance.  By migrate it is meant that controlling portal can transfer the portlet instance to another portal.
• You can upgrade a portlet instance to a new version.
• You can delete a portlet instance.
• You can request a portlet instance render its portlet content.
• You can request a portlet instance render a link reference to itself.
• You can request a portlet instance render help information.
• You can request a portlet instance render "about" information.
• You can request a portlet instance render its personalization screen.
• You can perform "actions" on a portlet instance.  [Mike -- this is a placeholder until I understand better what folks want/expect actions to be and do]
• You can send an event to a portlet instance.

State 3: Portlet Service Inactive
> During the lifecycle of a portlet service being bound
> with a  portal either the portlet service may become [temporarily]
> unavailable or the portal may choose to suspend communication with the
> portlet service.  When this occurs the portlet service is said
> to be inactive or offline.  In this state all operations described
> above are unavailable.  The only operation available is to request
> the service be made active again.
Random state: Portlet Service upgraded

During the lifecycle of a portlet service it may come to pass that the portlet meta-data that describes the portlet and how it wishes to be managed by the portal may change.  The portlet service is said to be upgraded.  The portal defines a [currently undefined] mechanism for detecting an upgrade has occurred.  Upon detection it is expected to:

• update meta-data caches (if any).
• honor the new settings where appropriate for existing anf new portlet templates and instances.  [Note: the Metadata group should define the effect of changing each value defined in the core meta data.]