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:[EMAIL PROTECTED]";>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 [EMAIL PROTECTED] 734-615-1419 -------------------------------------------- -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
