In my last article, "Understanding the Java Portlet Specification," I introduced to the main concepts behind the Java Portlet Specification, JSR-168. This article will walk through the development of a simple portlet application to demonstrate the inner workings of a compliant portlet. The application will highlight only the more important areas of the specification. We will review terminology as it comes up. However, if you are new to the specification, I recommend you read the introductory article first.
Query Portlet
QueryPortlet is a simple portlet that displays the contents of a database query. Each user can modify the default query, saving their new query so it executes each time they begin a portal session.
As I mentioned in my previous article, there are several commercial and open-source vendors currently supporting the Java Portlet Specification. I have chosen to use Liferay for deploying my portlet. Liferay is an open-source portal that comes bundled with numerous portlet applications. I downloaded the Jboss-Tomcat binaries from Liferay's download page and had it installed within minutes. Then, I followed the instructions here to hot deploy custom portlet applications into Liferay. To run QueryPortlet, you will also need a database and its JDBC driver. I used the MySQL database.
Viewing the QueryPortlet
Recall that each portlet application has two types of state managed by the portlet container: portlet mode and window state. The standard portlet modes are view, edit, and help (although additional ones may be added). The possible window states are minimized, normal, and maximized. Portlet mode determines which content a portlet will generate and window state determines just how much screen real estate the portlet is allowed.
Figure 1 shows our main portal window when we first log in. One of the portlets that appears is QueryPortlet; it presents data in tabular fashion and a title for that data. For each of QueryPortlet's screens, I've added text in the upper right-hand corner to display the current mode and window state. As you can see, we are currently viewing QueryPortlet in view mode with a normal window state.
Click here for a larger image.
Figure 1. Main Portal Window
QueryPortlet, and all compliant portlets, define four lifecycle methods: init, render, processAction, and destroy. These methods are invoked by the portlet container as needed. On startup, the portlet container receives a request for QueryPortlet's content from the portal application. Because the portlet has not been instantiated, the init lifecycle method is invoked. QueryPortlet.java extends GenericPortlet, a convenience class provided by the implementation that implements the render lifecycle method for you. Here is the init method in QueryPortlet.java:
/**Executed one time, upon portlet instantiation.*/
public void init(PortletConfig config)
throws PortletException {
log.info("Executing QueryPortlet's init method.");
super.init(config);
viewUrl = config.getInitParameter("view_url");
editUrl = config.getInitParameter("edit_url");
helpUrl = config.getInitParameter("help_url");
}
The init method passes in an instance of PortletConfig. PortletConfig provides access to initialization parameters in our descriptor file, portlet.xml . We assign values to instance variables that hold QueryPortlet's URLs. Here are those values in portlet.xml:
<init-param>
<name>view_url</name>
<value>/templates/view.jsp</value>
</init-param>
<init-param>
<name>edit_url</name>
<value>/templates/edit.jsp</value>
</init-param>
<init-param>
<name>help_url</name>
<value>/templates/help.jsp</value>
</init-param>
After invoking init, the container calls the render lifecycle method. Render will call QueryPortlet's doView method because we are in view mode at startup. QueryPortlet's raison d'être is to display database data, so we need to execute a query. QueryPortlet retrieves a default title and query from PortletPreferences, an object that contains persisted user information associated with a portlet. PortletPreferences reads these default values from portlet.xml.
<portlet-preferences>
<preference>
<name>sql</name>
<value>SELECT * FROM emp</value>
</preference>
<preference>
<name>title</name>
<value>Employees</value>
</preference>
<preferences-validator>QueryPreferencesValidator
</preferences-validator>
</portlet-preferences>
In QueryPortlet's doView method, we obtain these default preferences:
PortletPreferences preferences = request.getPreferences();
String sql = preferences.getValue("sql","BAD SQL");
String title = preferences.getValue("title,"My Query");
The getValue method specifies the name of the preference and also a default value if it should be unable to obtain one otherwise.
We pass the SQL string to a JavaBean called QueryBean to perform the actual query:
PortletSession session = request.getPortletSession(true);
if((session.getAttribute("queryColumns") == null) ||
(session.getAttribute("queryData") == null) ) {
QueryBean qb = new QueryBean();
qb.executeQuery(sql);
//Get headings/data and assign them to session attributes.
String[] queryColumns = (String [])qb.getQueryColumns();
List queryData = (List)qb.getQueryData();
session.setAttribute("title",title,PortletSession.PORTLET_SCOPE);
session.setAttribute("queryColumns",queryColumns,
PortletSession.PORTLET_SCOPE);
session.setAttribute("queryData",queryData,
PortletSession.PORTLET_SCOPE);
}
IE 7
Firefox 2.0
