[wsrp][interfaces]: Portal Usage Scenario

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