Generic Portal

The Generic Portal is an implementation of the basic functionality of a portal, released with an Apache open source license. It provides the basic building blocks for a portal that runs within a servlet container.

The portlet specification has a well defined interface for Portlets. However, portlets are not usable on their own, and need a supporting environment (a Portal). Since the functionality provided by a Portal is largely unspecified, developers that wish to leverage the advantages of Portlets may need to make a significant commitment to a particular, proprietary, Portal implementation.

The Generic Portal package addresses these problems in the following way:

it has an Apache open source license
it provides the classes necessary to use portlets in any servlet container
configuration information is represented by a small number of classes with simple implementations. They can be used on their own, or easily specialized to provide an interface to particular portal implementations.

Portlets as Servlets
Configuration and portlets.xml
Customizing Portal behaviour
1. GenericPortalContext

Portlets as Servlets

The generic portal classes, at their simplest, can be used to deploy portlets like servlets. Functionality for pages is programmed in a Portlet, which provides a flexible and general programming pattern. Using components of the generic portal, a servlet does a simple dispatch to the portlet class.

This approach is valuable for developers that wish to take advantage of the well defined pattern that portlets provide without a full commitment to a comprehensive portal implementation .

The generic portal includes class com.caucho.portal.generic.PortaletServlet . A number of tutorials demonstrate the use of PortalServlet.

Configuration and portlets.xml

The portlet specification indicates the portlets.xml file as the source of configuration information. The generic portal implementation does not read the XML files, but does provide two classes that are used to completely represent the configuration.

Users that wish to use the generic portal package in application servers other than Resin will be most interested in this section.

GenericPortletContext

The class javax.portlet.PortletContext interface is the interface between the portal and the servlet container or application server (Resin, for example). It's API is similar to the familiar class javax.servlet.ServletContext , and it is roughly analgous to a web application.

class com.caucho.portal.GenericPortletContext is an abstract implementation of PortletContext. It provides an implementation of methods for storing and retrieving GenericPortletConfig objects. It corresponds to the <portlet> elements within portlets.xml.

HttpPortletContext

HttpPortletContext extends GenericPortletContext and completes the PortletContext interface requirements by providing a wrapper around a ServletContext.

GenericPortletConfig

The class javax.portlet.PortletConfig interface is the configuration of a portlet. It is roughly analgous to ServletConfig. The GenericPortletConfig class implements the functionality of PortletConfig and adds methods to handle the full range of configuration that is possible in a <portlet> configuration in portlets.xml.

JNDI

The Generic Portal implementation uses JNDI to store and retrieve the GenericPortletContext. Resin is easily configured to read the portlets.xml and store the results in JNDI. For other application servers, or for greater portability, the GenericPortletContext class can be configured directly and then stored in JNDI.

This configuration could take place in the init() of a load-on-startup servlet. It might provide the ability to read the portlets.xml file, or it can be configured programmatically without the use of the xml file.

The default JNDI name is "java:comp/env/PortletContext".

Example - using the API to configure

The following example shows how the generic portal API is used to create a configuration for a portal. If this code were placed in the init() of a load-on-startup servlet then it would provide configuration within being dependent on any particular application server.

Using the API to configure a portal

import javax.naming.InitialContext; import javax.naming.NamingException; ... private servletContext ... public void init(ServletConfig config) throws ServletException { super.init(config); HttpPortletContext portletContext = new HttpPortletContext(); portletContext.setServletContext(config.getServletContext()); portletContext.addCustomMode(new PortletMode("goodbye")); GenericPortletConfig helloConfig = new GenericPortletConfig(portletContext); helloConfig.setPortletName("HelloWorldPortlet"); helloConfig.setPortletClass("com.caucho.portal.generic.example.HelloWorldPortlet"); helloConfig.addSupports("text/html",PortletMode.VIEW); helloConfig.addSupports("text/html",PortletMode.EDIT); helloConfig.setResourceBundle("com.caucho.portal.generic.example.HelloWorldPortlet"); portletContext.addPortletConfig(_helloConfig); // bind in jndi String jndiName = "java:comp/env/PortletContext"; if (log.isLoggable(Level.FINE)) log.fine("binding with jndi name `" + jndiName + "'"); try { InitialContext ic = new InitialContext(); ic.bind(jndiName,this); } catch (NamingException ex) { throw new ServletException(ex); } } ...

The API of GenericPortletContext closely matches the format of a portlets.xml file. "portlet-name" in the xml file is "setPortletName" in the api; "supports" in the xml file is "addSupports" in the api. The following is an example of a portlets.xml file that corresponds to the configuration above:

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0"> <portlet> <portlet-name>HelloWorldPortlet</portlet-name> <portlet-class>com.caucho.portal.generic.example.HelloWorldPortlet</portlet-class> <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> <portlet-mode>edit</portlet-mode> </supports> </portlet> <custom-portlet-mode> <portlet-mode>goodbye</portlet-mode> </custom-portlet-mode> </portlet-app>

Customizing Portal behaviour

GenericPortalContext

The class javax.portlet.PortalContext interface is a means for the Portal to provide information about it's capabilities. When using the generic portal implementation, you are creating a portal. You can use the PortalContext to publish the capabilities of your portal.

class com.caucho.portal.GenericPortalContext is an abstract implementation of PortalContext. It provides setters to match the getters defined by PortalContext. Many portal's can simply instantiate a GenericPortalContext.

Portlets

Tutorials