---

Visual Portlet Builder Functional Specification

---

---

Introduction

This functional specification covers the functionality in Visual Portlet Builder that allows the user to import Creator 2u1 JSF portlet projects and create new JSR-168 compliant portlet projects. This specification will not cover the details of JSR-168. Rather, the reader should familiarize themselves with JSR-168 (http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html) to help understand the driving forces behind many of the requirements and the functionality.

Requirements

The following requirements will be addressed for the NetBeans 6.x release.

• Import Creator 2u1 JSF portlet projects as NetBeans Visual JSF Web projects (J2EE 1.4 only)
• Create new NetBeans Visual JSF Web projects that are JSR-168 compliant (J2EE 1.4 and Java EE 5).
• Provide the ability to visually create the three portlet modes, View, Edit, and Help.
• Support multi-page navigation for each portlet mode, View, Edit, and Help.
• Support JSF 1.1 components for J2EE 1.4 portlet projects and JSF 1.2 components for Java EE 5 portlet projects.
• Support the JSR-168 life cycle for its application model.
• Support one-click deployment to
  • Sun Portal Server 7.x
  • Open Source Portlet Container
• Allow the user to export a WAR file for a portlet application. The bundled portlet application will comply with the JSR-168 portlet application specification (see JSR-168 - PLT.19 Portlet Applications). I.e., deploying without the IDE.

Terminology

The following table lists terms to be used in Visual Portlet Builder when referencing portals and portlets.

Term	Description
Portlet Page	This refers to the design view, JSP source, and backing Java source used to represent either a "View", "Help", or "Edit" page. This term is used in the same contexts the term "web page" would be used.
Portlet Deployment Descriptor	This term will be used for any reference to the file "portlet.xml".
View Page	This term refers to the Portlet Page that is used for the "View" mode according to the JSR-168 specification.
Edit Page	This term refers to the Portlet Page that is used for the "Edit" mode according to the JSR-168 specification.
Help Page	This term refers to the Portlet Page that is used for the "Help" mode according to the JSR-168 specification.

Functionality

This section will describe the functionality provided by Visual Portlet Builder to support portlet creation.

Project

• Creator 2u1 Portlet Project Import
  Importing Creator 2u1 portlet project is exactly the same as importing Creator 2u1 regular project in NetBeans except: users also need to change the target server to the following portlet container:
  • Sun Portal Server 7.x
  • Open Source Portlet Container
    You can change the server by right click on the Project node and select Properties. Inside the Project Properties window, select category "Run" and change the Server to "OpenPortal Portlet Container 1.0/2.0" or "Sun Portal Server 7.x".
    
• Project Creation
  When creating a new web project, select an available portlet container as the target server. Visual Portlet Builder will provide a "JSR-168 Portlet" checkbox option to the user. This project will be referred to from this point forward as the "Portlet project". There will be one and only one portlet created per project. The "Portlet" project will create a Portlet Page instead of the regular Visual Web JSF Page and contain the Portlet Deployment Descriptor in addition to the normal Visual Web JSF application project:
  • PortletPage1.jsp: a Portlet Page set as the initial VIEW Page shown under Web Pages in the Projects view
  • portlet.xml: the Portlet Deployment Descriptor shown under Configuration Files in the Projects view
    When the user creates a portlet project, the PortletPage1.jsp portlet page will be opened in the designer and displayed as the top tab. This web page will be the default initial "View" mode page.
    
• New File Template
  A new file template "Visual Web JSF Portlet Page" will allow users to add a new Portlet Page.
  
• Portlet Page Context Menu
  The context menu on the Portlet Page node will have the following choices:
  • "Set as Initial - VIEW Mode Page" - sets the selected Portlet page as the first page to be shown in the portal for View mode.
  • "Set as Initial - EDIT Mode Page" - sets the selected Portlet page as the first page to be shown in the portal for Edit mode.
  • "Set as Initial - HELP Mode Page" - sets the selected Portlet page as the first page to be shown in the portal for Help mode.
  • "Set as Initial - No Initial Page" - unsets the selected Portlet page.
    
• JSR-168 Portlet WAR Export
  The user will have the ability to create a war file that conforms to the JSR-168 specifications for a portlet application. The user will invoke this functionality from the project context menu "Build". Visual Portlet Builder will use the portlet deployment descriptor for the project as well as the web pages and resources to create a portlet application deployment file (WAR) under the "dist" subdirectory.
• One-Click Deployment
  The user will have the ability to deploy a portlet application to a configured NetBeans IDE server either Sun Portal Server 7.x or Open Source Portlet Container. This functionality is invoked from the project context menu or the toolbar button. Visual Portlet Builder will create a portlet application deployment file (WAR), deploy it to the portlet container, and insert the portlet onto a default display container.

Visual Web JSF Editor

The Design view will treat the "View", "Edit", and "Help" portlet pages just as it treats web pages in the regular Visual Web JSF project with the additions and exceptions listed below.

• Portlet Page JSP Source
  The designer and insync will create the portlet page JSP source without including any of the disallowed tags specified in JSR-168: PLT.B Markup Fragments.
• Portlet Page Size
  The designer background properties will show a "height" and "width" property that will allow the user to determine the portlet window size. The user can get to these properties by selecting the designer background.
  
• Page Navigation
  Select "Page Navigation" from the designer's context menu will bring up the Page Flow Editor based on file "faces-config.xml". The Page Flow Editor will come up with all pages defined under the Project->Web Pages showing. Double-click on either the new node "faces-config.xml" or the old node "navigation.xml" will both bring up the Page Flow Editor. Modification of the page flow rules will go into the file selected.

Integrated Portal Server

Portal Pack will provide an integrated portal server to be used by the developer for iterative development. The portal server will be referenced as the "Portlet Container". The portlet container will depend completely on the deployment server.

• Deployment
  The user will have the ability to deploy the portlet to the portlet test environment and see immediate design results. The user will be able to do the deployment through same mechanisms currently provided by Web Project; the "Run->Run Main Project" menu item, the green arrow toolbar (Run Main Project), and the "Run" and "Undeploy and Deploy" context menu items of the project node.
• Debugging
  Visual Portlet Builder will allow the user the same debugging functionality that currently exists for debugging a web application.

Use Cases

There are 3 parts of tasks for this integration. The first part is to install and configure the Portlet Container for the NetBeans IDE. This is an one time only setup needed for NetBeans developers to use the open source software OpenPortal Project to develop and test their portlets. The second part is to import Creator 2u1 JSR-168 portlet projects from NetBeans 6.0 and deploy it on the OpenPortal portlet container. The last part is to create a Visual Web JSF JSR-168 portlet project from NetBeans 6.0 by using the Visual Portlet Builder.

Install and Configure the OpenPortal Portal Server

1. Install GlassFish Application Server:
   GlassFish is an open source enterprise application server. There is no need to install separate GlassFish Application Server for portlet deployment if you have already installed it standalone or bundled by NetBeans.
2. Install OpenPortal Portlet Container on GlassFish Application Server:
   The OpenPortal Portlet Container is an enterprise-class Portlet Container which is part of the overall OpenPortal Project. To install OpenPortal Portlet Container on the GlassFish Application Server, download the latest binary first and then follow the installation instructions in the Download page.
   
   java -jar portlet-container-configurator.jar
   
   
3. Install the Visual Portlet Builder Kit on NetBeans 6.0:
   The Visual Portlet Builder Kit is a plug-in for NetBeans IDE; it provides supports to create JSR-168 portlet and the deployment of portlets from the NetBeans IDE. The Functional Components include:
   • NetBeans 6 Visual Web update
   • Base PSFramework - Base framework library for portal server integration.
   • OpenSource PC - Plug-in to integrate OpenPortal Portlet Container
   • JSF Portlet Bridge Library - An integration library to allow JSF applications to run within a Portlet environment
4. Add OpenPortal Portlet Container on NetBeans 6.0:
   Steps to add the portlet container server in the NetBeans IDE:
   1. Select Tools -> Servers
   2. Click on "Add Server..."
   3. Select "OpenPortal Portlet Container 1.0" from the list of available servers
   4. Select "GlassFish" from the dropdown
   5. Enter "GlassFish Home" and "Password" fields (Default password for GlassFish is "adminadmin";)
      
   6. Click on "Next" and then "Finish" to accept all default values.
      

Import Creator 2u1 JSR-168 Portlet Project into NetBeans 6.0

1. Prepare your Creator 2u1 Portlet Project:
   For testing, either create a simple Creator 2u1 portlet project by just adding few components, or use the Creator 2 tutorial Developing a Portlet Application to test more functionalities. Before importing into NetBeans 6.0, remember to right click on the project node and select "Clean Project" to remove the Creator 2u1 bundled files that may conflict later migration. Then copy the whole project to a new location.
2. Open the Portlet Project from NetBeans 6.0:
   After opening the portlet project, right click on the Project node and select Properties. Inside the Project Properties window, select category "Run" and change the Server to "OpenPortal Portlet Container 1.0/2.0".
   Be careful to not use JDK 6 for "Source/Binary Format" under the category Sources. It will not work for most current servers!
3. Deploy the Portlet Project on OpenPortal Portlet Container:
   Now we have the final project ready to deploy. Click on the green arrow button "Run Main Project (F6)" to deploy the portlet project on OpenPortal Portlet Container.
   You will see your portlet project deployed on your browser! If the server does not show, you can expand the Servers node under NetBeans IDE's Services tab until you see your portlet under the server OpenPortal Portlet Container 1.0/2.0. Right click on your portlet and select "Show Portlet". Or you can type the following URL in your browser to see all portlets that are currently deployed to the Portlet Container.
   
   http://localhost:8080/portletdriver/dt
   
   

Create new JSR-168 Portlet Project from NetBeans 6.0

1. Create New Portlet Project:
   For testing, either create a simple Visual Web JSF portlet project by just adding few components, or use the Creator 2 tutorial Developing a Portlet Application to test more functionalities.
   • Project Types:
     • J2EE 1.4 / JSF 1.1
     • Java EE 5 / JSF 1.2
   • Project Features:
     • Database
     • EJB
     • Web Services
   • JSF Components
     When working on the test spec, there is an old Creator article Differences Developing Portlets - Action Methods that should be helpful for writing the test sceipts.
   • Application Model Life Cycle
   • Initial Portlet Page Mode:
     • View
     • Edit
     • Help
   • Page Flow
   • Portlet Containers:
     • Sun Portal Server 7.x
     • Open Source Portlet Container
   • Debugging
   • Multiple Portlet Projects Deployment
     Deploy multiple portlet projects on the portlet container, one portlet per project.
   • Export WAR File Deployment
2. Deploy the Portlet Project on OpenPortal Portlet Container:
   Now we have the final project ready to deploy. Click on the green arrow button "Run Main Project (F6)" to deploy the portlet project on OpenPortal Portlet Container.

References

• Portal Pack
• Open Source Portlet Container
• Sun Java System Portal Server
• Po-Ting's Blog
• Satya's Blog

Attachments