Developing portlet applications with WDT and Liberty profile

A quick introduction to using Eclipse with WebSphere Application Server Developer Tools (WDT) to develop portlet applications on Liberty profile with the Portlet Container feature. It provides a simple step-by-step description about how to create a simple new portlet application.

Some notes about portlet applications

A portlet application is a logical collection of portlets. It is packaged in a web application archive. These portlet applications must comply to one of the portlet specifications, of the Java Community Process, for example Portlet Specification 2.0 (JSR 286). Portlet applications contain a portlet deployment descriptor file called portlet.xml, analogous to the web.xml file for web applications.


This section covers the required prerequisites for developing portlet applications by using Eclipse and Liberty. It includes a brief description about how to set up a Liberty server instance with the required features and its integration in Eclipse.

  1. Download and install an Eclipse IDE for Java EE Developers, for example Juno SR2 or Kepler SR1.
  2. Install WebSphere Application Server Developer Tools for Eclipse using the Eclipse Marketplace (Help > Eclipse Marketplace…). Search for IBM WebSphere Application Server Liberty Profile Developer Tools for Eclipse and select the appropriate version for your Eclipse installation. Alternatively, you can download it manually from the WASdev download site. Either way, you will need to restart Eclipse to make these changes work.
  3. In Eclipse, use File > New > Other… (or Ctrl+N) to open the New wizard.
  4. To define a new server instance, search for Server > Server. Click Next.
  5. Select IBM > WebSphere Application Server V8.5 Liberty Profile and provide a suitable server runtime name. The server instance name is defined in the next step.
  6. Select download or install at the next screen.NewServer Developing portlet applications with WDT and Liberty profile
  7. Download and install a new runtime and select the latest stable IBM WebSphere Application Server Liberty Profile option provided.InstallRuntimeEnvironmentSelection Developing portlet applications with WDT and Liberty profile
  8. At the Add-ons selection, search and select both, Portlet Container feature and Portlet Serving feature in the list of add-ons. To provide a clear separation, Portlet Container and Portlet Serving functionality are two features. The container serves as the runtime environment for portlet applications. This way, a serving functionality such as URL addressability, which is common for development scenarios can be deactivated explicitly in production environments.InstallRuntimeEnvironmentAddOns Developing portlet applications with WDT and Liberty profile
  9. Carefully read the license agreement. To continue further, accept it using the check box and click Next.
  10. Fill in a target installation directory. Click Finish.
  11. To continue with the server instance setup, click Next
  12. If you want, you can specify a server name for your new instance, for example DevelopmentServer.
  13. To complete the New Server wizard, click Finish.
  14. To display the Servers view with your new server instance, select Window > Show View > Servers.
  15. Open the server configuration. To do so, double-click the Server Configuration [server.xml] entry in the Servers view or by using the Server Configurations context menu option called Open.EclipseServersView Developing portlet applications with WDT and Liberty profile
  16. Make sure you are in the Design tab of the editor. Select the Feature Manager entry of the Server Configuration editor.
  17. To extend the server configuration with the portlet related features, click Add….FeatureManagerSectionInServerXML Developing portlet applications with WDT and Liberty profile
  18. Select Portlet Container and Portlet Serving feature. Click OK.AddFeatures Developing portlet applications with WDT and Liberty profile
  19. You can now start developing your first portlet application by using Eclipse and WDT.

You can simplify portlet application development by using an additional Eclipse plug-in, which is hosted at Lotus Greenhouse. Visit the IBM Portlet Container Tools for WebSphere Application Server Liberty Profile site and download the required plug-in archive. To add the plug-in site archive to your list of software sources, use Help > Install New Software…. After this, you can install the new plug-in. For detailed information about this step, read the enclosed documentation of the plug-in.

Create new portlet application project

The following section explains the creation of a new portlet application project with the assistance of the IBM Portlet Container Tools plug-in. If you do not wish to use this tool, you need to write the portlet.xml yourself. As stated earlier, portlet applications are bundled as web application archives (WAR file). Therefore, you can use the Dynamic Web Project nature of Eclipse for portlet applications. The IBM Portlet Container Tools plug-in introduces a new project nature called Portlet Project. It will be used in the following steps.

  1. Click File > New > Other… to get an overview of wizards.
  2. Search for Portlet Project, select it and click Next to continue.
  3. Fill in a name for your new project and for the first portlet of your new portlet application.NewPortletProject Developing portlet applications with WDT and Liberty profile
  4. Click Modify… in the Portlet settings area to select JSR 286 Portlet as the Portlet API that you want to use. Click OK to return to the New Portlet Project dialog.ModifyPortletSpecVersion Developing portlet applications with WDT and Liberty profile
  5. Click Finish to complete the wizard.
  6. Right-click your new portlet project and select New > Other…, search for Web Page and click Next.
  7. Enter view.jsp as the name of the new JSP file and fill in a new sub-directory name for the JSP file, for example /SamplePortletApplication/WebContent/jsp.NewWebPage Developing portlet applications with WDT and Liberty profile
  8. To create the file, click Finish.
  9. Open the SamplePortlet Java class and modify the source code to use the request dispatcher and include the newly created JSP file for rendering. Here is an example code snippet.
    import javax.portlet.*;
    public class SamplePortlet extends GenericPortlet {
      public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {
        getPortletContext().getRequestDispatcher("/jsp/view.jsp").include(request, response);
  10. Right-click your portlet project and select Run As > Run On Server. Make sure your Liberty server runtime is selected and click Finish. Eclipse opens a browser for you.
  11. You should see the content of the rendered view.jsp.

You successfully set up a simple and light-weight development environment for portlet applications. For more details about developing portlets, visit the WebSphere Portal Server Information Center.

  • mda

    Matthias, great stuff!
    I try repeat all steps but have some trouble :(
    1) I get error marker in portlet.xml. “cvc-elt.1: can’t find declaration of ‘portlet-app’”
    2) I get NullPointerException in function doView of portlet class (PortletRequestDispatcher is null). Sources of portlet was generated by IDE

    • Matthias Diester

      Hi! Your first issue does sound like a setup problem. Eclipse is either unable to find the Portlet Spec XML Schema, or its location is misspelled. Are you sure that the portlet features are installed correctly and that you have the correct server instance configured in your IDE?

      Regarding your second question, the portlet class source template is just a hint. You will need to write custom code to get a functional portlet. The code snippet of step 9 gives you a good idea.
      I would suggest to precisely follow the steps of this article to create a first sample portlet application to work with. If there are still issues, consider to ask a question in the WASdev forum.

      Kind regards, Matthias

  • g00glen00b

    Nice, is it also possible to easily switch between portlet modes? We know that WebSphere Portal offers built-in tools to switch to view/edit/help/config, but I don’t know if there’s something similar for liberty.

    • Matthias Diester

      Excellent question … the portlet container supports portlet modes as described by the JSR. By default this is view, edit, and help as far as I know. However, it depends on the exploiter of the portlet container API on how to use them.

      The portlet serving feature uses an URL based approach to switch between modes. You can try it out yourself by adding mode=X to the URL. For instance, you can use http://host:port/ContextRoot/PortletName/default/ver=2.0/mode=edit to display the respective portlet in Edit mode. Hope this helps.

  • Poonam

    Hi Guys..
    I followed exactly the same steps but i am unable to get option for creating New Portlet Project. Please help me out why i am unable to proceed..