Developing JSR 168 Portlets for WebSphere Portal 6.0

Table of Contents

1. Introduction

This document will outline the process of developing JSR 168 Portlets and deploying it to WebSphere Portal 6.0 using MyEclipse Blue. Please note that WebSphere Portal 6.1 is also supported and the steps to develop for that version are very similar to this example. The portlet developed in the tutorial is just the default portlet that is created using the "New Portlet" wizard in MyEclipse Blue.

MyEclipse Blue also supports developing all types of J2EE applications including Web, EJB, and web services that can also be deployed to WebSphere Portal since it is running ontop of WebSphere AppServer.

2. System Requirements

This tutorial was created with MyEclipse Blue Edition and WebSphere Portal 6.0. The installation of WebSphere Portal 6.0 server was done using the typical installation type, which means that we not only installed WebSphere Portal server but installed a new copy of WebSphere AppServer to run the portal server. 

If you notice any portions of this tutorial looking different than the screens you are seeing, please let us know and we will make sure to resolve any inconsistencies.

3. Prerequisites 

Prior to going through this tutorial, you need to ensure that you have all the proper information that is needed from your WebSphere Portal 6.0 installation.  Namely the following values are needed to properly configure WebSphere Portal 6.0 in MyEclipse Blue.

• WebSphere AppServer install location
  
• WebSphere profile install location that is used for portal server
  
• WebSphere Portal Server install location
  

Here is a screenshot of the WebSphere Portal 6.0 installation summary that contains all the values that are needed.

Figure 3.1: WebSphere Portal 6.0 required installation details

4. Configuring WebSphere Portal 6.0 Connector

After successful installation of the portal server, the first step in using it in MyEclipse Blue is to configure the WebSphere Portal 6.0 connector.  Below are the step-by-step instructions for configuring the server.  For the purpose of this tutorial we will use the following values that were taken from our installed server.

• Portal server home: E:\wps6\PortalServer
• WebSphere AppServer home: E:\wps6\appserver
• WebSphere Portal profile: E:\ibm\WebSphere\profiles\wp_profile

Below are the steps to configuring WebSphere Portal 6.0 connector in MyEclipse Blue 6.5.

1. Go to: Window > Preferences > MyEclipse Blue Edition > WebSphere - Blue Connectors > WebSphere 6.0 Portal
2. Set the PortalServer home directory to the portal server installation directory created by the installer: E:\wps6\PortalServer
3. Set the WebSphere home directory to the websphere appserver install directory created by the installer: E:\wps6\appserver
4. Set the profile root directory to the specialized WebSphere_Portal server profile that was created by the installer: E:\ibm\WebSphere\profiles\wp_profile
   
   After setting the profile the rest of the fields wil be auto-populated, but you will need to change a few of the values that are specific to the WebSphere Portal server profile.
   
   
5. Change the server name to the server value used for the portal server: WebSphere_Portal
6. Change the SOAP port to: 10038
7. Change the Admin port to: 10027
8. Change the HTTP port to: 10038
   
   Note: if you change any of the defaults from the installer you may have to find out what the appropriate values for your installation are.
   
   
9. Open the WebSphere Portal 6.0 > Admin Security preference page and set them to the username/password settings that you used in the installation.
10. At the top of the pref page switch the radio button to "Enable".
    
11. Press OK and the server should be correctly configured and visible in your servers view.
    
    
    Figure 4.1: Servers view showing the configured portal server
    

5. Accessing the Portal server from within MyEclipse Blue

Now that the WebSphere portal server is in the servers view it will act as any other server in MyEclipse.  This section will show you how to start the portal server and access it from the embedded MyEclipse browser.

1. First start the server from servers view.  During the startup of the server you should see a printout that the WebSephere Portal server has started.  This means you have correctly configured the connector.  If you don't see these messages you likely have a misconfigured server connector.
   
   
   Figure 5.1: WebSphere Portal 6.0 running from within MyEclipse Blue
   
   
2. Once the server is started, access the portal home page to ensure the portal application is available.
   http://localhost:10038/wps/myportal
   
   You will need to login using the same username/password you provided with the Admin Security values:
   
   
   Figure 5.2: WebSphere Portal login page
   
   Once you are logged in your homepage should look like this:
   
   
   Figure 5.3: WebSphere Portal home page
   
   
3. Since the portal server runs on a WebSphere 6.0 Appserver, you can access the WebSphere Admin console using the Open Admin Console context menu action in the Servers view:
   
   
   Figure 5.4: Open Admin Console action
   
   
   Figure 5.5: WebSphere AppServer admin console home
   
   

6. Creating JSR 168 Portlet project for WebSphere Portal

In order to develop a JSR 168 Portlet to deploy to WebSphere Portal 6.0 you first need to create a webproject, add JSR 168 Portlet capabilities to it and then create your portlets before deploying it to the portal server.  This section will walk you through these tasks step-by-step.

1. Either create or select a new MyEclipse Web Project
2. Choose action " MyEclipse > Project Capabilities > Add JSR 168 Portlet Capabilities..."
   
   
   Figure 6.1 Adding JSR 168 Portlet Capabilities
   
   
3. Select "WebSphere Portal 6.0 JSR 168 API" in the combo box for selecting Portal runtime.
   
   
   Figure 6.2 Select Portal Runtime
   
   
4. Click next or select Finish to complete the wizard.  Once you complete it you will see the portlet resources that are added to the project as shown in Figure 6.3.
   
   
   Figure 6.3 Portlet project structure
   
   
5. Create a new JSR 168 portlet by using the "New Portlet" wizard from File > New... > MyEclipse > Web > Portlet
   
   
   Figure 6.4 New Portlet Wizard
   
   The first page of the portlet wizard looks much like a new Servlet wizard but with some new important fields to pay attention to, namely the Template to use and the doView(), doEdit(), type fields that the wizard can optional create as shown in Figure 6.5.
   
   
   Figure 6.5 Select Template
   
   The 2nd page of the portlet wizard allows you to specify several fields that will be added to the portlet.xml and also lets you optionally modify the file name of the generate JSP file.
   
   
   Figure 6.6 Configure Portlet properties
   
   
6. Click "Finish" to add the entry into the portlet.xml, create the portlet java file and also create the JSP view file.
   
   
   Figure 6.8 portlet.xml file
   
   

7. Developing Portlets on WebSphere Portal

Once you have created your portlets they are ready to be deployed to WebSphere Portal.  Deployment for portlets is identical to normal J2EE Web application deployment in MyEclipse.  When you deploy to WebSphere Portal MyEclipse Blue will detect that your project contains portlets and WebSphere Portal server specific deployment will happen automatically to make sure the project's portlets are correctly registered with the portal.

7.1 Portlet Deployment

Below are the steps for deploying the portlet application and then testing it in WebSphere Portal server.

1. Start the WebSphere Portal server in Debug mode:
   
   
   Figure 7.1 Debug server action
   
   
2. Right-click the WebSphere Portal 6.0 server in the Servers view and then choose "Add Deployment..." action.
3. In the New Deployment dialog, make sure that you select the "PortletTest" project and choose "Exploded deployment" so that MyEclipse hot-swap and hot-sync debugging facilities will be available.
   
   
   Figure 7.2 New Deployment dialog
   
   
4. The first thing the deployment job does is deploy the web application as a normal J2EE web application to the WebSphere Portal server, and then at the end it registers the WAR with the portal server including all the portlets contained in the application.
   
   
   Figure 7.3 Add Deployment
   
   
   Figure 7.4 Servers view showing the deployed project
   
   
5. Now that deployment worked, you need to add the portlet to your portal and test it
   
   Go to portal home page: http://localhost:10038/wps/myportal
   
   
6. Login to the portal application
7. Open the portlet pallette
   
   
   Figure 7.5 Portlets Palette
   
   
8. Search for your test portlet to display in the palette.
   
   
   Figure 7.6 Select the portlet we deployed
   
   
9. Now you can drag and drop the portlet onto a content location in your default home page.
   
   
   Figure 7.7 Drag n Drop the portlet
   
   
10. Now the portlet will be displayed and prints out the default message that was added to the JSP file when it was created by the portlet wizard.
    
    
    Figure 7.8 Console output
    
    

7.2 Testing/Debugging

Now that you have a properly working portlet application, you can test and debug it just like you would any other J2EE Web application that you have deployed to WebSphere AppServer.  Figure 7.9 and Figure 7.10 shows the MyEclipse Java/JSP debugger stopped at both the portlet class and the JSP in the view.


Figure 7.9: Debugging the Portlet class



Figure 7.10: Debugging the portlet JSP View

Notice that once we step through both Portlet and JSP files the updated view in the portal application shows that the portlet java and JSP where hot-synced to the WebSphere Portal.


Figure 7.11 Updated Portlet application view

7.3 Portlet Undeployment

Undeployment is very similar to deployment in that to correctly delete the portal app the server has to be running.  This time when you undeploy the portal configuration change happens first and then the j2ee application (WAR) is undeployed from the server. 


Figure 7.12 Undeploying the Portlet

8. Resources

In this section we want to provide you with additional links to resources that supplement the topics covered in this tutorial. While this is not an exhaustive list, we do make an effort to point to the more popular links that should provide you with diverse, high-quality information.

• How-to document on enabling additional JSR 168 Portlet APIs, e.g. Coop, and Struts
  
• MyEclipse Blue: WebSphere 5.x, 6.0 and 6.1 Tutorial
  
• How to make developing with WebSphere Portal 6.0 faster
  

9. Feedback

We would like to hear from you! If you liked this tutorial, has some suggestions or even some corrections for us please let us know. We track all user feedback about our learning material in our Documentation Forum.  Please be sure to let us know which piece of MyEclipse material you are commenting on so we can quickly pinpoint any issues that arise.