GridSphere Portlet Reference Guide

Portlets are defined as visual components that can be assimilated into portal web pages. Portlets provide "mini-applications" that can either display informational content or provide access to other services. The GridSphere portal allows users to customize their workspace by adding and removing portlets as needed. In addition to standard window states like minimized or maximized, portlets can also provide various "modes" such as view, edit, configure and help. As an example, consider a stock quote portlet that allows users to customize their stock quote information. View mode would display a user's stock information. Help mode provides users with informational content about the stock quote portlet and how to use it. Edit mode allows users to change the list of stocks they are intersted in monitoring. Finally, configure mode allows portlet administrators to change persistent settings such as the stock quote service that is contacted.

As of GridSphere 2.0, two portlet development models are supported. The original portlet model was based upon the IBM WebSphere® Portlet API v4.1+ which means that existing WebSphere portlet applications can be easily ported for use within GridSphere. In addition, GridSphere provides an implementation of the JSR 168 Portlet API standard supported by IBM, Sun, Oracle, Plumtree, and many other application server vendors. The GridSphere framework is packaged as a web application that provides a portlet container for managing deployed portlets. GridSphere provides a collection of core portlets as well as a development environment for the creation of new portlet applications, both the WebSphere model and the JSR 168 standard.

GridSphere provides built-in support for role based access control. A group is defined by a name, description and a collection of portlets that a user has access to including role access rights on a per portlet basis. Users may belong to one or more groups (meaning they have access to one or more portlet web applications) and they have a role within each group. the four supported roles are GUEST, USER, ADMIN and SUPER. A user with the GUEST role will obtain a generic view of the portal suitable to guests while a user that has logged on, will have the USER role and may be able to see the portlet personalized with their settings. A user with the ADMIN role can have access to a portlet's CONFIGURE mode described earlier and presumably configure a portlet's initialization settings. A user possesing the SUPER role can essentially do anything they want to any portlet and is essentially equivalent to having root access in an operating system. A portlet application may provide an optional group descriptor file, group.xml, which defines an initial group and access rules for the portlet collection.

This document is intended as a reference guide on the GridSphere portal and does not cover too much portlet development. Please see the GridSphere tutorials for developing portlets within GridSphere or see Additional Portlet Resources for a useful set of web links offering more information.

The Portlet Services API described in Portlet Service Framework provides a very clean approach for the creation of reusable "services" that perform a set of tasks for a given portlet. Using the portlet API, a service instance can be obtained providing the portlet with additional functionality.

The Portlet Service Framework section is generally applicable to both WebSphere and JSR 168 developed portlets. The GridSphere portal container supports both APIs by using the WebSphere portlet API to bootstrap a special PortletServlet that is a WebSphere style portlet that is responsible for loading JSR 168 portlets. Please read the paper GridSphere: An Advanced Portal Framework for more technical details.

The portlet lifecycle extends the servlet lifecycle by offering more control over the event processing required of a and the presentation rendering. Just as servlets have init and destroy methods, the portlet lifecycle methods listed below are responsible for the initialization and shutdown of concrete and application portlets. For every request made by a user, the service method is invoked which is responsible for invoking the appropriate portlet action method if one exists followed by the appropriate portlet render method for all portlets that are currently displayed on the portal page. All lifecycle methods throw a PortletException

As discussed in the introduction, GridSphere provides a concept for portlet groups that a user may belong to. A group can be created via the "Group Manager Portlet" or a webapp can define a group descriptor used to create a portlet group upon loading the webapp.

Specifying a Group Descriptor

An external portlet web application specifies a group definition in an XML descriptor file found in WEB-INF/group.xml. An example illustration is shown:

<portlet-group>  
    <group-name>GridSphere</group-name> 
    <group-description>Core GridSphere Group</group-description> 
    <group-visibility>PUBLIC</group-visibility>  
    <portlet-role-info> 
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.user.ProfileManagerPortlet.1
        </portlet-class> 
        <required-role>USER</required-role>  
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.subscription.SubscriptionPortlet.1
        </portlet-class>
        <required-role>USER</required-role>
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.layout.UserLayoutPortlet.1
        </portlet-class>
        <required-role>USER</required-role>
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.admin.portlets.PortletApplicationManager.1
    </portlet-class>
        <required-role>SUPER</required-role>
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.admin.users.UserManagerPortlet.1
    </portlet-class>
        <required-role>SUPER</required-role>
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.admin.layout.LayoutManagerPortlet.1
    </portlet-class>
        <required-role>ADMIN</required-role>
    </portlet-role-info>
    <portlet-role-info>
        <portlet-class>
 org.gridlab.gridsphere.portlets.core.admin.groups.GroupManagerPortlet.1
    </portlet-class>
        <required-role>ADMIN</required-role>
    </portlet-role-info>
</portlet-group>

	Every group descriptor must begin with a portlet-group element
	A group must provide a group name
	The group definition should say something meaningful about this group. Users will see the group name and description.
	The group visibility specifies if any user can add themselves to this group or if it requires administrator approval. Valid values are "PUBLIC", where any user will see the group and have the ability to subscribe to it. If visibility is "PRIVATE", the user will see the group existence but requires administrator approval to add them. A group that is "HIDDEN" will not be displayed at all to users and requires an administrator to add members.
	A portlet-group may contain one or more portlet-role-info elements that defines a portlet and associated role information
	The portlet-class element defines the fully qualified portlet class name of this portlet (concrete portlet id) in the case of WebSphere style portlet application. In JSR 168 applications, it can be the fully qualified portlet class name or should specified as the webapp and the portlet name separated by a '#' e.g. jsrtutorial#ActionHelloPortlet
	The required-role element may be one of USER, ADMIN, or SUPER defining which role a user must have to view this portlet.

The layout descriptor specifies a custom configuration for the layout of your portlets in the portal using a nested tabbed pane approach.

	Important
	If you define a layout descriptor in the portlet webapp, you must also include a group descriptor

The Portal Layout components closely resemble the AWT/Swing components found in the standard Java classes. The reason for this is twofold: One, to provide a very close API to create web based visual components easily by anyone familiar with Java GUI development under AWT or Swing. The other reason is to follow the "Composite" design pattern which allows for maximal flexibility in developing new layouts composed of various changing components by composing objects, or portal components, into a tree based structure. GridSphere creates customized user layouts composed that are represented as XML layout descriptors.

The $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal/layouts/GuestUserLayout.xml layout descriptor specifies the layout for all non-logged in users. This is essentailly the public portal layout. Modify this file as needed for your own portal. This can also be done via the LayoutManagerPortlet from the portal when logged in as an administrator. This layout creates an entire portal page as evidenced by the <portlet-page> tags. The following sample shows the relevant sections of the GuestUserLayout.xml.

<page-layout title="GridSphere Portal" keywords="gridsphere" icon="images/favicon.ico" renderkit="classic" refresh="600"> 

<!-- Header components -->
<portlet-header> 
    <table-layout style="header">
        <row-layout>
            <column-layout width="70%">
                <portlet-content include="/WEB-INF/CustomPortal/layouts/html/pagehead.html"/>
            </column-layout>
            <column-layout width="30%">
                <portlet-frame transparent="true" outer-padding="0" label="locale">
                    <portlet-class>org.gridlab.gridsphere.portlets.core.locale.LocalePortlet.1</portlet-class>
                </portlet-frame>
            </column-layout>
        </row-layout>
    </table-layout>
</portlet-header>

<!-- Tabbed Panes -->
<portlet-tabbed-pane selected="0" style="menu">
...
</portlet-tabbed-pane>

<!-- Footer components (if any) -->
    <portlet-footer> 
        <table-layout style="footer">
            <row-layout>
                <column-layout>
                    <portlet-content include="/WEB-INF/CustomPortal/layouts/html/pagefooter.html"/>
                </column-layout>
            </row-layout>
        </table-layout>
    </portlet-footer>


</page-layout>
    

	The page element specifies various parameters that will be used in the resulting output including a title, keywords (placed in HTML meta tags), page refresh in seconds, a favicon if you have one and the renderkit to be used. Currently GridSphere supports two renderkits, classic and cssmodern. The classic renderkit uses a combination of nested tables stylesheets. We have been developing the css renderkit which uses only stylesheets and no nested tables for greater flexibility. You are urged to try both and see which one works for your needs.
	The header element can be used to define an appropriate portal header including a logo or banner and any portlets that should be displayed.
	The footer element can be used to define a portal footer including links, copyright informaation

Once a user has successfully logged in, the layout created is formed by taking the $CATALINA_HOME/webapps/gridsphere/WEB-INF/CustomPortal/layouts/TemplateLayout.xml which specifies the portal page header and footer and incorporating all the layouts defined for each group that a user has memberbership. The TemplateLayout.xml may also need to be modified in the same way as the GuestUserLayout.xml described previously.

Specifying a layout within a portlet web application

An external portlet web application specifies the arrangement of portlets in an XML descriptor file found in WEB-INF/layout.xml. The layout descriptor specifies the organization of portlets within a double-tabbed pane. An example illustration is shown:

<portlet-tabbed-pane> 
    <portlet-tab>
        <title lang="en">Examples</title> 
        <portlet-tabbed-pane style="sub-menu">  
            <portlet-tab order="50"> 
                <title lang="en">Simple Examples</title>
                <table-layout>    
                    <row-layout>  
                        <column-layout width="50%> 
                            <portlet-frame> 
                                <portlet-class>
                org.myorg.portlets.examples.simpleone.1
                            </portlet-class>
                            </portlet-frame>
                        </column-layout width="50%>
                        <column-layout width="50%>
                            <portlet-frame label="simpletwo"> 
                                <portlet-class>
                org.myorg.portlets.examples.simpletwo.1
                                </portlet-class>
                            </portlet-frame>
                        </column-layout>
                    </row-layout>
                </table-layout>
            </portlet-tab>
            <portlet-tab>
                <title lang="en">Demos</title>
                <table-layout>
                    <row-layout>
                        <column-layout>
                            <portlet-frame>
                                <name>DemoPortlet</name>
                                <portlet-class>
                org.gridlab.gridsphere.portlets.examples.DemoPortlet.1
                                </portlet-class>
                            </portlet-frame>
                        </column-layout>
                    </row-layout>
                </table-layout>
            </portlet-tab>
            <portlet-tab url="http://www.google.com"> 
                <title lang="en">Google</title>
            </portlet-tab>
        </portlet-tabbed-pane>
    </portlet-tab>
</portlet-tabbed-pane>

	Every layout descriptor must begin with a portlet-tabbed-pane element
	The tab title is the title string that is presented in the portal layout. Multiple tab titles with different locales specified as two character ISO 639 values can be present for localization support.
	The tab order is a number generally between 0 and 100 that specifies the order of the tab in this tab pane. If the tab number is undefined it will have a default of 20 applied to it.
	Although not required, in general a tab contains either a sub-level tabbed pane or a portlet-panel
	The table layout lays out components into a table using nested row-layout and column-layouts.
	The row layout lays out components into a table row using nested column-layouts.
	The table layout lays out components into a column whose width is defined by the width attribute as a relative percentage.
	The portlet frame is specified as the concrete portlet id representing the portlet class. In the case of WebSphere style application, the concrete portlet id shoudl be used. For JSR 168 portlet applications, the webapp name and the portlet name (as expressed in <portlet-name> of portlet.xml) separated by a '#' should be used e.g. jsrportlets#WeatherPortlet. However, the portlet class name will also work, but does not guarantee uniqueness if multiple portlets with the same classname are declared in the portlet descriptor.
	Assigning a label to a component means that it can be linked to in the portal and made bookmarkable.
	Assigning a url to a tab allows the tab to link to an external web site and renders the specified url instead of creating a link that points back to the portal.

To learn more about possible attributes and component relationships, look at the layout-mapping.xml file in the GridSphere source. This defines the relationship between the portlet component classes and the XML descriptions.

GridSphere provides the concept of roles that are used to categorize users and the restrictions they have. A role can be created or edited via the "Role Manager Portlet" or a webapp can define a role descriptor used to create new portlet roles upon loading the webapp. A role is defined by a role name and a role level. The role name may be any useful descriptive name, but the role level must be one of four defined levels:

Specifying a Role Descriptor

An external portlet web application specifies a role definition in an XML descriptor file found in WEB-INF/role.xml. An example illustration is shown:

    <?xml version="1.0" encoding="UTF-8"?>
    <portlet-roles>
        <portlet-role>                            
            <role-name>employee</role-name> 
            <role-priority>USER</role-priority> 
        </portlet-role>
        <portlet-role>
            <role-name>manager</role-name>
            <role-priority>ADMIN</role-priority>
        </portlet-role>
    </portlet-roles>

	Every new role must begin with a portlet-role element
	A role must provide a descriptive role name that is displayed to users
	The role priority should be one of GUEST, USER, ADMIN, or SUPER.

Portlet services encapsulate business or logic operations that can be re-used among portlets. The use of portlet services helps to minimize the amount of logic placed in a portlet and present it as a reusable library to other portlets. In addition, portlet services offer the following major advantages:

Persistence using built-in persistence framework makes it easy to serialize objects to a relational database

Method level security using built-in access control model makes it easy to provide "secure service" proxies that perform the proper operations based on the user's role

Integration with testing framework makes it easy to write JUnit tests

Portlet Service Architecture

We borrow from the IBM WebSphere service interface to build a services architecture that we believe will allow for future integration with a standardized Portlet API. The UML object diagram of the services framework is shown below:

Figure 6.1. Portlet Service Architecture UML

A PortletServiceFactory is responsible for creating, initializing and destroying portlet services. A PortletService defines a blank interface that is enhanced by the PortletServiceProvider interface which defines a lifecycle consisting of init() and destroy methods used when the service is initialized and shutdown. A portlet services descriptor is used to specify class information and initialization parameters that is accessed via the PortletServiceConfig.

Under the WebSphere portlet model, a portlet service can be obtained from a portlet using the PortletContext object. Because the method getService() returns a PortletService, it must be typecast to the approriate service instance:

ExampleService =
    (ExampleService)getPortletConfig().getContext().getService(ExampleService.class);
    

Notice that only the service interface is specified and the factory will use the appropriate service implementation specified in the services descriptor.

In JSR 168 portlet development, the ActionPortlet subclass of GenericPortlet must be used as it provides the necessary createPortletService method:

         ExampleService =
           (ExampleService)createPortletService(ExampleService.class);
        

A User Service provides two possibilities. In the first case, a service can provide logic appropriate for the user's request. For exaple, the method deleteUser(User user) in the UserManagerService requires that a user with the role SUPER requested the service instance. For any other service instance, the method will fail with a PortletServiceAuthorizationException. User services not only help provide a library that will "do the right thing" based on a client's role, but it makes the services much more robust and secure for other portlet developers to take advantage of. In the second case, a User Service simply provides a per user service instance. This can be useful for associating an independent service with a particular user.

Portlet Services Descriptor

The portlet services descriptor file located in WEB-INF/PortletServices.xml of the portlet web application specifies the services provided by this portlet web application. It is possible to specify multiple portlet service descriptors, as long as they are placed inside the WEB-INF/portlet-services directory of the portlet web application. GridSphere core services are defined in WEB-INF/GridSphereServices.xml of the gridsphere webapp. The following example shows service definitions for an example service.

       <portlet-services>  

           <service>   
               <name>Example Service</name>       
               <description>Provides Special Capabilities</description>   
               <interface>org.gridlab.gridsphere.services.core.example.ExampleService</interface>   
               <implementation>
                    org.gridlab.gridsphere.services.core.example.impl.ExampleServiceImpl
               </implementation>  
               <user-required>false</user-required>  
               <load-on-startup>false</load-on-startup>  
               <service-config>         
                   <param-name>some parameter</param-name>
                   <param-value>some value</param-value>
               </service-config>
           </service>

       </portlet-services>

  

	The portlet-services element delimits the start and end of a services descriptor
	The services element delimits the start and end of a portlet service
	The name of the portlet service. Not used currently, but could be used by tools, portlets, etc.
	The description of the portlet service. Not used currently, but could be used by tools, portlets, etc.
	The portlet service interface describing the services's methods
	The portlet service implementation class that implements the portlet service interface
	This must be set to true for user services, where a User object will be supplied to create the service instance. The default is false
	This should be set top true of the service should be initialized at startup time. Normally a service is initialized when it is first used. The default is false.
	Although not actually used in this service, any service can be configure with supplied initialization settings expressed as string key value pairs in the displayed form

Portlet Service Example

In the following example we illustrate the StockQuoteService with a single method getStockQuotes() : List which returns a list of stock quotes obtained from the quote.com service.

Create service definition

Create a services definition entry in the WEB-INF/PortletServices.xml of the portlet web application

        ...

        <service>
            <name>Stock Quote Service</name>
            <description>Provides Stock Quotes</description>
            <interface>org.myorg.services.StockQuoteService</interface>   
            <implementation>org.myorg.services.impl.StockQuoteServiceImpl</implementation>
            <service-config>
                <param-name>quote_service</param-name>
                <param-value>quote.com</param-value>
            </service-config>
        </service>

    

The class files should be named accordingly and must be located in any directory called services in the src directory in order for the template project build script to handle them properly.

Create service interface

Create a services interface as shown:

    package org.myorg.services.StockQuoteService;

    import org.gridlab.gridsphere.portlet.service;
    import java.util.List;

    public interface StockQuoteService extends PortletService { 

        public List getStockQuotes();  

    }
    

	The StockQuoteService must subclass from PortletService
	Single method getStockQuotes defined in the body

Create service implementation

Create a stock quote service implementation as shown:

    package org.myorg.services.impl.StockQuoteServiceImpl;

    import org.myorg.services.StockQuoteService;
    import org.gridlab.gridsphere.portlet.service.*;
    import org.gridlab.gridsphere.portlet.service.spi.PortletServiceProvider;
    import java.util.List;

    public class StockQuoteServiceImpl implements PortletServiceProvider, StockQuoteService { 

        public void init(PortletServiceConfig config)       
                    throws PortletServiceUnavailableException {
            // Place optional startup routines e.g. loading data from database
        }

        public void destroy() {                       
            // Place optional shutdown routines here e.g. saving data to database
        }

        public List getStockQuotes() {
            // hypothetical code to return stock quotes
        }

    }
    

	The StockQuoteServiceImpl must provide implementations for the StockQuoteService and the lifecycle routines from the PortletServiceProvider
	The destroy() method provides a service with the ability to perform any initialization tasks before it used. The PortletServiceConfig object provides any initialization data required.
	The destroy() method provides a service with the ability to perform any cleanup tasks before it is shutdown such as freeing database connections, etc.

Access service from portlet

The following skeleton portlet code demonstrates how to obtain a stock quote service:

    package org.myorg.portlets.StockQuotePortlet;

    // imports omitted

    public class StockQuotePortlet extends AbstractPortlet {

        public void actionPerformed(ActionEvent event) {
            PortletContext ctx = getPortletConfi().getContext();
            StockQuoteService quoteService = null;
            try {
                StockQuoteService quoteService = (StockQuoteService)ctx.getService(StockQuoteService.class);
            } catch (PortletServiceException e) {
                getPortletLog().error("Couldn't get quote service instance", e);
                return;
            }

            // get quotes and place in request
            List quotes = quoteService.getStockQuotes();
            req.setAttribute("stocks", quotes);
        }

        public void doView(PortletRequest req, PortletResponse res) {

            // display stock quotes
            List quotes = req.getAttribute("stocks");
            ...
        }

    }
    

User Portlet Service Example

Continuing with the stock quote example, assume we want to allow portal administrators the ability to configure the quote service that it gets stock information from. In this case, the StockQuoteService will become a user service.

Create user service definition

The only addition to the service definition is to set the user-required element to be true

        ...

        <service>
            <name>Stock Quote Service</name>
            <user-required>true</user-required>
            <description>Provides Stock Quotes</description>
            <interface>org.myorg.services.StockQuoteService</interface>   
            <implementation>org.myorg.services.impl.StockQuoteServiceImpl</implementation>
            <service-config>
                <param-name>quote_service</param-name>
                <param-value>quote.com</param-value>
            </service-config>
        </service>

    

Important Must set <user-required>true</user-required>

Edit service interface

Add the administrator required method below:

        ...

        setQuoteService(String quoteService);

        ....
    

Create user service implementation

Now an additional class is created that handles all authorization decisions and passes control to the original class. One useful approach is to copy the original implementation into a singleton as follows and provide implementations of all service methods.

    package org.myorg.services.impl.StockQuoteServiceFactory;

    import org.myorg.services.StockQuoteService;
    import org.gridlab.gridsphere.portlet.service.*;
    import org.gridlab.gridsphere.portlet.service.spi.PortletServiceProvider;
    import java.util.List;

    public class StockQuoteServiceFactory implements PortletServiceProvider, StockQuoteService {

        // create single instance
        private instance = new StockQuoteFactory();

        private StockQuoteServiceFactory() {}              

        public static StockQuoteServiceFactory getInstance() {
            return instance;
        }

        public void init(PortletServiceConfig config)
                throws PortletServiceUnavailableException {
            // Place optional startup routines e.g. loading data from database
        }

        public void destroy() {
            // Place optional shutdown routines here e.g. saving data to database
        }

        public List getStockQuotes() {
            // hypothetical code to return stock quotes
        }

        public void setStockQuoteService(String quoteService) {
            // sets the quote service to be used for stock information
        }

    }
    

To make a singleton, the constructor must be kept protected or private so that the getInstance() is used to return the single reference to this class.

The next step is to add the required security checks into the existing StockQuoteServiceImpl and configure it to use the StockQuoteServiceFactory just created.

    package org.myorg.services.impl.StockQuoteServiceImpl;

    import org.myorg.services.StockQuoteService;
    import org.gridlab.gridsphere.portlet.services.*;
    import org.gridlab.gridsphere.portlet.services.spi.PortletServiceProvider;
    import java.util.List;

    public class StockQuoteServiceImpl implements PortletServiceProvider, StockQuoteService {

        private StockQuoteServiceFactory quoteServiceFactory = null;

        private PortletServiceAuthorizer authorizer = null;

        public UserManagerServiceImpl(PortletServiceAuthorizer authorizer) { 
           this.authorizer = authorizer;
        }

        public void init(PortletServiceConfig config)
                    throws PortletServiceUnavailableException {
            // Configure it to use StockQuoteServiceFactory
            quoteServiceFactory = StockQuoteServiceFactory.getInstance();
            quoteServiceFactory.init();
        }

        public void destroy() {
            // Place optional shutdown routines here e.g. saving data to database
            quoteServiceFactory.destroy();
        }

        public List getStockQuotes() {
            quoteServiceFactory.getStockQuotes();
        }

        public void setStockQuoteService(String quoteService) {     
            // sets the quote service to be used for stock information

            // checks to see that the user invoking this method has super privilege or it will throw
            // a runtime AccessDenied Exception
            authorizer.authorizeSuperUser();

            quoteServiceFactory.setStockQuoteService(quoteService);
        }

    }
    

	Important The constructor of a user service implementation as defined in the descriptor file must require a PortletServiceAuthorizer object to be passed in. This is done by the PortletServiceFactory is created allowing for service methods to make authorization checks using the PortletServiceAuthorizer
	The PortletServiceAuthorizer provides various authorization check methods that will throw a runtime AccessDeniedException in the event they fail. If the check succeeds the underlying StockQuoteServiceFactory method is invoked.

Access the user service from a portlet

The only difference from the previous example is passing in the User object to the getService() method.

        ...

        public void actionPerformed(ActionEvent event) {
            PortletContext ctx = getPortletConfig().getContext();
            PortletRequest req = event.getPortletRequest();
            User user = req.getUser();
            StockQuoteService quoteService = null;
            try {
                StockQuoteService quoteService = (StockQuoteService)ctx.getService(StockQuoteService.class, user);
            } catch (PortletServiceException e) {
                getPortletLog().error("Couldn't get quote service instance", e);
                return;
            }

            // get quotes and place in request
            List quotes = quoteService.getStockQuotes();
            req.setAttribute("stocks", quotes);
        }


        ....
    

GridSphere provides a persistence framework implemented using Hibernate Persistence Layer. It provides methods to store objects to a SQL based database and supports many database types.

                    PortletData pd = request.getData();
                    pd.setAttribute("key", value);
                    try {
                    pd.store();
                    } catch (IOException e) {
                    // something went wrong while storing the data!
                    }
                

                    PortletData pd = request.getData();
                    String value = pd.getAttribute("key");
                

                            PortletPreferences prefs = request.getPreferences();
                            prefs.setValue("key", value);
                            try {
                            prefs.store();
                            } catch (IOException e) {
                            // something went wrong while storing the data!
                            }
                

                            PortletPreferences prefs = request.getPreferences();
                            String value = prefs.getValue("key");
                

                    PersistenceManagerRdbms pm =
                    PersistenceManagerFactory.createPersistenceManagerRdbms("webappname");

                    data.setName("test");

                    // store persistent data
                    pm.store(data);

                    // now retrieve it
                    PMData testdata = (PMData)pm.restore("from PMData where name='test'");

                    // modify it
                    testdata.setName("test2");

                    // update
                    pm.update(testdata);

                

                    ...
                    private String useroid = null;

                    public String getUseroid() {
                        return useroid;
                    }

                    public void setUseroid(String useroid) {
                        this.useroid = useroid;
                    }
                    ...
                

                    property name="Useroid" type="string" column="userid"/
                

                    User user = request.getUser();
                    result = (MyClass)pm.restore("from "+MyClass.class.getName()+" as sub where sub.Useroid='"+user.getID()+"'");
                

GridSphere provides a pluggable way to specify "authetication modules" used for authenticating users to the portal. The model is very similar to the PAM (Pluggable Authentication Modules) approach used in Unix in that modules may be "stackable" such that each module that is selected as active also has a priority associated with it. This makes it possible for instance to default to the GridSphere password based authentication module if some other module with a higher priority fails at first.

The following major design parameters were used to develop the authentication modules approach.

Below is the authmodules.xml descriptor that is bundled in GridSphere and defines the default PasswordAuthModule.

      <auth-modules>
          <auth-module> 
              <name>PasswordAuth</name>  
              <description lang="en">Hashed password based authentication using GridSphere database</description> 
              <implementation>org.gridlab.gridsphere.services.core.security.auth.modules.impl.PasswordAuthModule</implementation> 
              <active>true</active> 
              <priority>100</priority> 
              <auth-config> 
                  <param-name>aname</param-name>
                  <param-value>avalue</param-value>
              </auth-config>
              <error key="key1" lang="en">Password is not provided</error> 
              <error key="key2" lang="en">Incorrect password provided</error>
          </auth-module>
      </auth-modules>
    

	Every authentication module must begin with a auth-module element.
	A name for this authentication module.
	A human understandable description of the authentication module that will be displayed in the Login configuration portlets for administrators to see. To support additional locales, just add additional description elements.
	Every authentication module must specify an implementation class of the LoginAuthModule interface
	If active is true, this module will be executed with the priority assigned to it.
	Every authentication module must specify a priority. The core GS PasswordAuthModule has a priority of 100, so a priority number that higher will be executed after the password authentication module. One that is lower will be performed beforehand.
	Configuration parameters may be used to provide some parametrization to the module. For instance to specify some third-party authentication service or to pass in additional variables that you don't wish to hardcode in the implementation class itself.
	Error messages can be localized and displayed to users when authentication is unsuccessful. An AuthenticationException constructed with the key attribute value should be thrown that will result in the proper locale dependent error message being displayed.

Developing a new authentication module is pretty straightforward. You would first create or add new entry to authmodules.xml describing the authentication module as explained above. The real work is the implementation of the LoginAuthModule interface. For convenience, it is recommended to subclass from org.gridlab.gridsphere.services.core.security.auth.modules.impl.BaseAuthModule which provides additional help for handling auth module configuration attributes. For additional examples, please look at the PasswordAuthModule.java class that is found in the GridSphere source code or the CredAuthModule.java source in the gridportlets codebase which handles authentication using grid certificates and the MyProxy service.

            <auth-module>
                <name>GridSphere JAAS Integration</name>
                <description lang="en">Integration with JAAS-based Authentication of the container</description>
                <implementation>org.gridlab.gridsphere.services.core.security.auth.modules.impl.JaasAuthModule</implementation>
                <active>true</active>
                <priority>50</priority>
                <auth-config>
                    <param-name>contextName</param-name>
                    <param-value>Gridsphere</param-value>
                </auth-config>
            </auth-module>
       

            Gridsphere {
                org.jboss.security.auth.spi.LdapLoginModule required
                    java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"
                    java.naming.provider.url="ldap://ldap.gridsphere.org:389/"
                    java.naming.security.authentication="simple"
                    java.naming.security.protocol="plain"
                    principalDNPrefix="uid="
                    principalDNSuffix=",ou=users,dc=gridsphere,dc=org"
                    rolesCtxDN="ou=roles,dc=gridsphere,dc=org"
                    uidAttributeID="uid"
                    roleAttributeID="memberUid"
                    roleAttributeIsDN="true"
                    roleNameAttributeID="cn"
                ;
            };
        

            set JAVA_OPTS=%JAVA_OPTS% -Djava.security.auth.login.config=%CATALINA_HOME%/conf/jaas.config
        

The following shows the directory layout of the deployed gridsphere web application located in $CATALINA_HOME/webapps/gridsphere:

Many resources exist on both the WebSphere portlet model and the JSR 168 Portlet API standard. The following lists websites useful for both models as well as generic portlet and web application sites.

JSR 168 portlet API and model

WebSphere portlet development information

The architecture of GridSphere and API definitions of key portlet concepts matches the portlet API provided by IBM WebSphere to a large extent. An excellent source of more information on portlets and portlet development is the IBM WebSphere Portal Zone and the following IBM WebSphere documents: