portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Glenn Golden <ggol...@umich.edu>
Subject Portlet API re-implementation
Date Fri, 10 May 2002 03:31:41 GMT
Here is an annotated version of:

org\apache\jetspeed\portal\Portlet.java

our "portlet API".  In this annotation, I identify:

A) things that belong to the portal page definition, not the portlet
B) things that belong to the portlet registry, not the portlet
C) things that the real portlet class need to know / do
D) things that I don't think belong in this API at all!

Terms:

[there may be more accepted terms for these concepts, please comment on this
and I'll update]

Portlet - a java .class that can be instantiated into an object which is
called upon to provide the content to aggregate into the portal page.  These
are objects that implement the jetspeed.portal.Portlet API.  A Portlet class
object is multi-use (multi-thread), can have no instance variables (they
would be shared by all threads using it), and is used to provide output
wherever the portlet is used in various pages and under various
configurations.

Portlet Registration - an entry in the portlet registry which identifies a
portlet class and provides other parameter information.  This is not usually
modified at runtime - only initialized from the registry files.

Portlet Instance - an Entry in a PSML portal page description which
references a portlet registration (and thus a portlet class and parameters)
and additionally provides parameter, layout, and display information.  This
can be modified at runtime, needs to be stored back to the psml store (file
or db), and once modified must be used as modified by all users and uses
from then on.

The overriding idea I'm proposing and working out here is:

1) The Portlet is always called upon with a particular Portlet Instance in
mind.

2) The Portlet API provides some information that is not owned by the
Portlet; it provides information from the Portlet, the Portlet Registration
and the Portlet Instance.

3) We introduce a new concept, "the burrito", which has reference to all
three
- Portlet
- Portlet Registration
- Portlet Instance

[ I'm open to a better term here! ]

The burrito satisfies the Portlet API for the Portlet class, and for all
users of the Portlet classes, while preserving the multi-user nature of all
three of the ingredients.  The same Portlet class object can be in multiple
burritos at the same time, will not be modified an any way by any one.  In
each burrito, the Portlet class object will have different instance and
registration information.

In the same way, the Portlet Registration objects and the Portlet Instance
objects might as well be kept around and used over and over again, rather
that re-built for each request.

All three are essentially read-only, except for the Portlet Instance which
support updates, then the update is used from then on.

My comments start ">grg>"

* * * * * * * * * *

package org.apache.jetspeed.portal;

/**
A portlet is an implementation of a small control (usually rendered in HTML)
that is available to a client application.  Portlets were designed to be
extensible so that 3rd parties implement their own Portlets.

@author <a href="mailto:burton@apache.org">Kevin A. Burton</a>
@version $Id: Portlet.java,v 1.43 2002/03/29 20:12:32 taylor Exp $
*/

public interface Portlet
{

    public int PORTLET_NORMAL = 0;
    public int PORTLET_MINIMIZED = 1;
    public int PORTLET_MAXIMIZED = 2;

>grg> this information is really part of the portal page session state, not
the portlet...

    /**
    Returns a name for this portlet.  This is used by PSML to identify a
Portlet
    within the PortletRegistry
    */
    public String getName();

    /**
    Sets the name on this Portlet.

    @see #getName()
    */
    public void setName(String name);

>grg> the name belongs to the Portlet Instance PSML Entry, and would be a
cover to that object

    /**
    <p>
    Allows a Portlet to define its title.  This can be used by a
PortletControl
    for rendering its content.
    </p>

    <p>
    In order to define a default title you should not override this but
should
    call setTitle() within your init() method
    </p>

    <p>
    This should return null if not specified.
    </p>
    */
    public String getTitle();

    /**
    Set the title for this Portlet
    */
    public void setTitle( String title );

>grg> the title belongs to the Portlet Instance PSML Entry, and would be a
cover to that object 

   /**
    <p>
    Returns a description of this portlet.  This should describe what the
    capabilities of the portlet and how it can help the user.
    </p>

    <p>
    In order to define a default title you should not override (in the
    AbstractPortlet implementation) this but should call setDescription()
    within your init() method
    </p>

    <p>
    This should return null if not specified.
    </p>
    */
    public String getDescription();

    /**
    Set the description for this Portlet
    */
    public void setDescription( String description );

>grg> the description belongs to the Portlet Instance PSML Entry, and would
be a cover to that object (might be transient in the Portlet Instance
object)

    /**
    Returns an HTML representation of this portlet.  Usually a Portlet would
    initialized itself within init() and then when getContent is called it
    would return its presentation.
    */
    public ConcreteElement getContent(RunData rundata);

>grg> Ah, getContent is something that the Portlet itself is responsible
for!

    /**
    All initialization should be performed here.  If your Portlet wants to
    do any work it should be done here.  You are not guaranteed that any
    particular order of method call will happen just that init() will happen
    first. Therefore if you have to calculate things like a title, a
    description, etc it should happen here.
    */
    public void init( ) throws PortletException;

>grg> init might just be called once per server run... Or should we
guarantee that it's called each time we pack a burrito up so it can look at
all the info and set stuff like description...  Can't really do much in
init.

    /**
    Set's the configuration of this servlet.
    */
    public void setPortletConfig(PortletConfig pc);

>grg> THIS HAS TO GO!  No need for it - the config is "set" by the burrito

    /**
    Get the config of this servlet.
    */
    public PortletConfig getPortletConfig();

>grg> This is a cover to (I'm not sure) the Portlet Instance (PSML Entry)?
The Registry information?  Both?  Whatever - it's a cover, and read only for
our portlet at that.

    /**
    <p>Return true if this portlet is allowed to be edited in the rundata's
context .</p>

    <p>Note:  PortletControl implementations should pay attention to this so
    that they don't allow this option if it returns false.</p>
    */
    public boolean getAllowEdit( RunData rundata );

>grg> I guess getAllowEdit() is also a Portlet responsibility!  Always
called in the burrito context, so that all that information is available to
the portlet to make the decision.

    /**
    <p>Return true if this portlets is allowed to be maximized.</p>

    <p>Note:  PortletControl implementations should pay attention to this so
    that they don't allow this option if it returns false.</p>
    */
    public boolean getAllowMaximize( RunData rundata );

>grg> I guess getAllowMaximize() is also a Portlet responsibility!  Always
called in the burrito context, so that all that information is available to
the portlet to make the decision.

    /**
    Get the creation time for this Portlet
    */
    public long getCreationTime();
    
    /**
    Set the creation time for this Portlet
    */
    public void setCreationTime( long creationTime );
    
>grg> I know, creation time if for our caching - but hey - a portlet never
ages!  It is read-only, right?  It's being used all over the place for
different instances, so we can't mess with it.  I suggest we drop this and
drop the time issue from caching, if we cache.

    /**
    Returns true portlet is able to output content for given mimetype
    */
    public boolean supportsType( MimeType mimeType );

>grg> supportsType() is more good old fashioned Portlet class
responsibility.

    /**
    Retrieve a portlet attribute from persistent storage

    @param attrName The attribute to retrieve
    @parm attrDefValue The value if the attr doesn't exists
    @param rundata A RunData object
    @return The attribute value
    */
    public String getAttribute( String attrName, String attrDefValue,
RunData rundata );

>grg> getAttribute() covers either the Portlet Instance or the Registry info
or both.

    /**
    Retrieve a unique portlet id 
    */
    public String getID();

>grg> (my favorite) getID() covers the Portlet Instance's getId().  And why
ID() vs. Id()?

    public void setID(String id);

>grg> Bad Bad Bad!  Drop setID()

    /**
    * @return true if the portlet does its own customization
    */
    public boolean providesCustomization();

>grg> providesCustomization() a Portlet class thing.

}

* * * * * * * * * * * * * * * * * * * * * *

Next: identify the places where these burritos might be created, make sure
they all go through the same service, and modify it to pull the ingredients
together from some other service which are responsible for locating, loading
and caching (or whatever) the three parts.

- Glenn

--------------------------------------------
Glenn R. Golden, Systems Research Programmer 
University of Michigan School of Information
ggolden@umich.edu               734-615-1419
--------------------------------------------

--
To unsubscribe, e-mail:   <mailto:jetspeed-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:jetspeed-dev-help@jakarta.apache.org>


Mime
View raw message