Portlets feel a lot like Servlets. Heck, even the name ends the same way. The method and class signatures are similar, and the overall goal of producing HTML markup, feels the same. However, there are several key differences that must be considered when developing Portlets. New Portlet developers can avoid common mistakes during development of their first Portlet application if they are aware of these differences before they begin development.
HTML/Page Markup
First we need to consider the purpose of a Portlet. A Portlet is designed to generate the content for a specific area of a page rendered in a Portal. The page is owned and rendered by the Portal. The Portlet only generates a portion of page content. So right off the start, you can not have a Servlet based web application and Portlet use EXACTLY the same HTML. In the "web application" case, you must be a good web developer and define the proper <html> <head> <title> and <body> tags. As well as meta data about the page, caching restrictions and more. In the Portlet world most of these "page" oriented tags are forbidden. The job of writing those tags falls to the Portal and NOT the Portlet. The JSR 168 Portlet specification outlines all of the disallowed tags in section PLT.B (the previous tag list plus, <frame>, <iframe>, and <frameset>).
In addition to limiting which tags a Portlet produces, the Portlet developer should consider the other aspects of a page the Portal will take care of. Typically portals include navigation and menus. Anything a Portal takes care of should most likely not be done by the Portlet itself. There are exceptions to this rule, especially in the area of maximizing a portlet.
URLs
Another difference encountered by the Portal owning the page generation, is portal also owns the process of receiving incoming portal requests. This has the effect of owning the URL generation process. As a result, Portlets can not directly create URLs and must instead go through the Portlet API objects to create their URLs. The URLs created by the Portlet API are often tokenized representations, which the Portal will then go back and replace with dynamic data.
Not being able to create URLs directly means that existing paradigms much change. In the past, URLs would simply be part of the HTML markup in some template language (JSP, Velocity template, freemarker, XSL stylesheet) with dynamic parts. Now, however, in a Portlet application, the URL must be a completely abstract object. If JSPs are used, the JSP has a portlet tag library available for creating these Portlet URLs. If another template system is used one of three approaches is typically used for URLs.
- The URLs are pre-generated by the Portlet code and passed into the template along with all the other model data. This approach is simplest, but least efficient, especially when loops/tables are involved.
- The Portlet API objects are passed in as part of the model data, and the URLs are requested from the model data. The URLs are generated by the Portlet API objects dynamically when the template renders.
- Create the equivalent of a Portlet Tag Library for the template system used. This style has seen recent use with XSL and the uPortal 3.0 project. XSL callbacks were written that create URLs from the Portlet API objects. These XSL callbacks are then made available as simple XSL templates.
The difference in URL handling is another reason why existing Servlet based web applications can not be directly made into Portlets.
Action/Render Lifecycle
Servlets have one ongoing lifecycle method that is called repeatedly as the Servlet handles user requests, service. A Portlet has two methods, processAction and render. Two fully appreciate the difference between Portlets and Servlets, we must look again at a point made above. "The Portal also owns the process of receiving incoming portal requests." In the Servlet world a Servlet owns the process of receiving an entire web request and rendering output at the same time. In the Portlet world, the Portal receives the web request then makes separate calls to individual portlets. This separation allows for a different lifecycle method to be introduced in Portlets.
The render lifecycle method of a Portlet operates similar to a Servlet, where the responsibility of the method is to generate HTML output intended to be consumed by a user's browser. As mentioned above, only a portion of an HTML page is generated, but otherwise this process is nominally equivalent to the end result of a Servlet's service call.
The processAction lifecycle method, however, is quite different. This method is called any time the user "interacts" with the portlet. This is where all the 'processing' (thus the name) should be done by a Portlet. The render method should only be used to render (again, thus the name) the current state of the Portlet. Conceptually these make sense. However, the Servlet world has mixed us all up. Developers are in the bad habit of doing both of these things at the same time, because that what Servlets made you do.
Portlets have a major reason to need this distinction. Portlets may be asked to render, even when the user is not interacting with them. A sample Portal page may contain 2, 3 or even half a dozen Portlets. The user can only interact with one Portlet at a time. The other Portlets on the page, have no 'additional' work to do, but they will still need to render, the same thing they rendered the last time they were called. The JSR 168 specification does allow a Portal to cache the rendered Portlet content, but the caching rules are minimal to say the least. It's a much better idea, to simply optimize your Portlet's render method to simply render the current state of the Portlet.
This means all state changing, action oriented, processing, behavior code for a Portlet goes into the processAction method. All code dealing with producing HTML markup goes into the Portlet's render method. In practice this makes total sense, but it's a very big change from the way things were done in the Servlet based web application world.
Well Designed Applications
Although there are several challenges to reusing Servlet based web applications in a Portlet, reuse is still possible for well designed applications. Consider the two lifecycle methods for Portlets. A Servlet may be coded to do all "processing" at the beginning of the service method and all rendering at the end of the method (or better yet, abstracting both of those to their own methods). This Servlet would then be very easy to convert to the Portlet lifecycle.
Another example of a well designed application is one that uses header and footer templates to define the beginning and end of the HTML markup. If the main template does not contain any of the forbidden Portlet tags, the templates are much easier to modify for Portlets by simply changing the header and footer templates.
Summary
Many new Portlet developers have already programmed Servlet based web applications before they start to create their first Portlet. There are several key differences that make programming Portlets different then Servlets. Portlets should only generate their portion of an HTML page instead of the whole page like a Servlet does. URLs must only be created by using the Portlet API. Servlets had the flexibility to hand craft URLs while Portlets must delegate all URL creation to the Portal container. When creating a Portlet application, special attention needs to be given to the two lifecylce methods. The logic performed previously in the Servlet service (or doGet/doPost methods) must be broken up into the Portlet processAction and render methods. While many differences exist between Servlets and Portlets, it is possible to reuse some portions of Servlet web applications if they are well designed, separating out the processing/rendering logic and the header/footer HTML templates. Understanding the differences between Portlets and Servlets will help new Portlet developers avoid common mistakes when they develop a new Portlet application.
---- Cris J H
