A portal is a web page that contains individual and customizable web applications. For example, My Yahoo is a portal page. The portal provides value-added services, such as single sign-on, customization, content aggregation, and localization.

Individual web applications that are added to the portal page are called portlets. A portlet is a Java technology web component that is based on the JSR 168 specification and JSR 286, which includes Web Service for Remote Portlets (WSRP). Portlets are managed by portlet containers that supply dynamic content. Portals employ portlets as pluggable user-interface components that provide users with desired content such as RSS feeds, mashups of services such as the current weather in a given area, or even static content such as a group of hyperlinks.

In the past, creating portlets was a complex process. Now, you can quickly and easily create and test portlets using the NetBeans IDE 6.0 and the OpenPortal Portlet Container 2.0 Beta 2. Deploying the portlets onto the server is also simple.

This article shows you how to create portlets and provide dynamic content through drag-and-drop widgets in the NetBeans IDE. The example portlet in this article uses the jMaki Tabbed View widget, pulls in RSS feeds, and uses static links from the New to Java Programming Center.

What You Need to Get Started

To create and test portlets, you need the following software installed on your computer:

• Java SE 6 or later
• NetBeans IDE 6.0 or later
• OpenPortal Portlet Container 2.0 Beta 2, dated 2 January 2008. This is a separate download from the NetBeans IDE.
• GlassFish application server. This is bundled with the NetBeans IDE 6.0 or later, so you don't need to download it separately.

For instructions on installing the OpenPortal Portlet Container 2.0 Beta 2, see the installation page. You must download and install the OpenPortal Portlet Container before you follow the next steps.

The portlet container works similarly to servlet containers. A portlet container does the following:

• Provides the runtime environment for portlets
• Manages the life cycle of portlets
• Provides persistent storage for storing portlet preferences
• Caches the portlets
• Receives requests from the portal to execute requests on the portlet

Once you have installed the necessary software, start the NetBeans IDE. Next, install the portlet and portlet container plug-ins by following these steps:

1. Go to Tools in the main menu.
2. Select Plug-ins.
3. Click on the Available Plug-ins tab.
4. Check the boxes for Portlets, the OpenPortal Portlet Container, and jMaki Ajax Support.
5. Click the Install button and follow the directions from there. You may need to accept a few licenses before the installation process can complete.

Lastly, add the OpenPortal Portlet Container server:

1. Go to Tools in the main menu.
2. Select Servers.
3. Click on Add Server.
4. Select OpenPortal Portlet Container 2.0 from the list.
5. Click Next.
6. Use Browse to set the location in which to install the GlassFish application server. You may need to search your system separately to discover where the NetBeans IDE installed the GlassFish application server.
7. Click OK.

You are now ready to create a portlet.

Creating a Portlet Project

As you do whenever you create an application in the NetBeans IDE, go to File > New Project, and choose Web > Web Application, then click Next. For the name of this project, type New2JavaPortlet. In the Server drop-down menu, choose OpenPortal Portlet Container 2.0 Beta, then click Next. In the next screen, check the jMaki Ajax Framework box. In the lower half of the pane, you get a selection of layouts. Scroll to the bottom, and choose No CSS Style.

Lastly, at the top of the screen, check the Portlets Support box. Use the Portlet Version drop-down menu and select 2.0, then check the Create Portlet box. In Portlet Class Name, type New2JavaPortlet. Note that the project name and the portlet name must be the same. The other fields are filled in automatically. Click Finish.

Because of the way that portlets are set up within the container, you will not need the displayed index.jsp page. On the left side of the screen, under the Projects tab, you see index.jsp listed. Right-click on index.jsp and select Delete. The file you are going to work on is named New2JavaPortlet_view.jsp. You can find that file by expanding the WEB-INF directory, then the jsp directory. Double-click the file name New2JavaPortlet_view.jsp The file now opens in the workspace.

How the Java Portlet Works

Even though all you've done is create a portlet project, the NetBeans IDE has already written an essential class for you. From the Projects tab, expand the Source Packages. Then expand com.text, and open the file New2JavaPortlet.java by double-clicking the file name.

The New2JavaPortlet extends a GenericPortlet class, which is provided, that implements the render() method and delegates the call to more specific methods to display the portlet based on its mode. Developers can extend GenericPortlet and implement as many of the following specialized render methods as are necessary for their portlet:

• doView() Called by render() when the portlet is in View mode. Intended to contain logic that displays the View page for the portlet.
• doEdit() Called by render() when the portlet is in Edit mode. Intended to contain logic that displays the Edit page for the portlet.
• doHelp() Called by render() when the portlet is in Help mode. Intended to contain logic that displays the Help page for the portlet.

Notice that the New2JavaPortlet calls these methods, locating the pages for each. In this article, you will put the content of the portlet in the View page through drag-and-drop widgets and some HTML code. But you can extend this GenericPortlet class for other portlets. You can also go back later and modify the Edit or Help page. Once you have had a good look at the New2JavaPortlet class, you can close it.

When you build and run the portlet, the browser will display the New2JavaPortlet_view.jsp. Currently, this page contains only the static text: New2JavaPortlet - VIEW MODE. Because it is a JavaServer Pages (JSP) technology page, you can add any scripts or JSP tag libraries that you wish, and treat it like any other JSP page.

Test your portlet environment now before adding more content: From the main menu, click Build and select Build Main Project. Once the build is successfully completed, go to the main menu and click Run. Select Run Main Project. This takes a little longer as the application server is started, the portlet container is started, and a browser window is opened.

Notice that the portlet project name is the same as the portlet itself. Once you see that your development and testing environments are working properly, you can add content to replace the static text on the New2JavaPortlet_view.jsp page. To see the changes that you make to your portlet, you undeploy and deploy the portlet, as explained in the next section.

Adding Dynamic and Static Content to the Portlet

Because this portlet will contain several kinds of content, organize the content for a small area on a web page by using tabbed panes. You can choose other types of layouts, of course, but for this example, use the jMaki widget named Tabbed View. On the right side of your screen, notice that you have many available widgets to drag and drop. Check to be sure that the jMaki Yahoo widgets list is expanded .

Within the workspace page, delete the static text that says New2JavaPortlet - VIEW MODE. Also, delete the surrounding HTML code for bold: <b></b>. Now drag and drop the Tabbed View widget, shown highlighted in white , from the palette onto the page, exactly where you have just deleted text. Once you have dropped the Tabbed View widget onto the page, the following code appears on the page:

<a:widget name="yahoo.tabbedview" value="{items:[ {label : 'My Tab', content : 'Some Content'}, {id : 'bar', label : 'My Tab 2', include : 'test.jsp ', lazyLoad : true }, {label : 'My Tab 3', content : 'More Content', selected : true} ] }" />

The action of dragging and dropping a jMaki widget onto the page causes the creation in the resources directory of all the files necessary to build that widget.

To get an idea for how this widget works, save the file. Next, right-click the project name in the Projects pane and select Undeploy and Deploy. Once it is built, run the project: Go to the main menu, click Run, and select Run Main Project. When the project runs, your changes appear in the browser window. Click on each of the tabs in the Tabbed View pane. Notice on the tab named My Tab 2 that the file test.jsp was not loaded. This is only because a test.jsp had not been created, but it does demonstrate how you call a JSP page to appear in the pane.

For the New2JavaPortlet, you are going to create new JSP pages that the widget will call. Each of these pages provides the content for each of the tabs. On the New2JavaPortlet_view.jsp page, replace the code shown earlier with the following code:

<a:widget name="yahoo.tabbedview" value="{items:[ {id : 'bar', label : 'Popular & New', include : '/New2JavaPortlet/whatsnew.jsp ', selected : true }, { label : 'Java Fundamentals', include : '/New2JavaPortlet/fundamentals.jsp ', lazyLoad : true }, { label : 'Downloads', include : '/New2JavaPortlet/downloads.jsp ', lazyLoad : true }, ] }" />

This code calls three JSP pages: whatsnew.jsp, fundamentals.jsp, and downloads.jsp.

The next step is to create those pages. In the Projects pane, right-click on Web Pages. Then select New, and lastly JSP. Notice that you are saving these pages into the Web Pages directory, not the jsp directory that the portlet container created for the New2JavaPortlet_view.jsp. Any JSP pages that you create must go into the Web Pages

Create three JSP pages in this manner, naming them whatsnew, fundamentals, and downloads. The NetBeans IDE automatically adds the .jsp extension, so don't include that in the file name.

Next, run Undeploy and Deploy again. Then click on the Run menu, and select Run Main Project. This time, note that the tab names have changed. As you click on each tab name, you get the JSP pages that you just created because of the code you replaced. Open each of these JSP pages — downloads.jsp, fundamentals.jsp, and whatsnew.jsp — and add content as described in the following subsections.

The downloads.jsp Page

This page contains simple static content, a title, and a list of links. Do not change the first two lines of code that appear at the top of the page:

<%@page contentType="text/html"%> <%@page pageEncoding="UTF-8"%>

But replace all of the HTML code with the following:

<h3>Downloads for New Developers</h3> <ul> <li><a href="http://java.sun.com/javase/downloads/i">Java SE (JDK)</a> <li><a href="http://www.netbeans.org/">NetBeans IDE</a> <li><a href="http://www.mysql.com">MySQL Database</a> </ul>

The fundamentals.jsp Page

This page will provide dynamic content, pulling in an RSS feed. Again, leave the first two lines of code alone, and remove all of the HTML code. Next, from the jMaki Widgets palette on the right side of the display, drag and drop the Block List widget onto the page.

The following code should appear on your page:

<a:widget name="jmaki.blockList" value="[ {title : 'jMaki Project Home', link : 'https://ajax.dev.java.net', description : 'Where to go for the latest jMaki.' }, {title : 'jMaki Widgets Home', link : 'https://widgets.dev.java.net', description : 'The source for the latest jMaki widgets.' }, {title : 'jMaki-Charting Home', link : 'https://jmaki-charting.dev.java.net', description : 'Enables complex charts rendered on the client in any modern browser.' } ]" />

The widget provides placeholder text only. Replace everything with the following code:

<h3>Java Technology Fundamentals</h3> <a:widget name="jmaki.blockList" service="/xhp?id=rss" />

In order to populate the widget with data from an external service, such as an RSS feed, you must replace the value attribute with service="/xhp?id=rss". If any page consists of a jMaki widget, then the jMaki runtime is bundled with the application. The runtime consists of jmaki.xhp.XmlHttpProxyServlet class that maps to the /xhp URL pattern within the application context.

The identifier or ID specified in the URL, rss, is configured in a configuration file named xhp.json. This file consists of a list of default external services that the widgets in a page can access. You can specify each entry in the xhp.json file by using up to five different parameters:

• ID: This required parameter is a unique identifier for the entry.
• URL: This required parameter gives the location of the external service.
• Parameters: These optional parameters specify the default values passed to the URL.
• API key: This is an optional parameter to invoke the service with a specific key.
• Stylesheet: This is an optional parameter to process the response.

Next, you must change the xhp.json file. Go to the Projects tab and expand the resources directory. Double-click the file xhp.json, and scroll to the bottom of that page. Search for this code in the xhp.json file:

{"id": "rss", "url":"http://weblogs.java.net/blog/ludo/index.rdf", "xslStyleSheet": "rss.xsl" }

The tag and the default entry tell the jMaki runtime to fetch the RSS feed from http://weblogs.java.net/blog/ludo/index.rdf, apply the rss.xsl stylesheet — which understands the multiple RSS/Atom formats — to the received response, and convert the data into a common JavaScript Object Notation (JSON) data format of the type "dataType" : "jMakiRSS". The jMaki Block List widget can convert jmakiRSS data to its specific data model.

But the intention of this article is not to pull in Ludovic Champenois's blog. So change the URL of http://weblogs.java.net/blog/ludo/index.rdf to http://blogs.sun.com/JavaFundamentals/feed/entries/rss.

Additionally, you will pull in another feed on the whatsnew.jsp page, so change the URL in the code as shown in the following code snippet. The new URL is highlighted in red.

{"id": "rss2", "url":"http://blogs.sun.com/new2javaUpdates/feed/entries/rss", "xslStyleSheet": "rss.xsl" }

Notice that the ID for the second RSS feed to pull in is named rss2. Notice also that the URL pulls in the blogs from the "What's New" section of the New to Java Programming Center. Save the xhp.json file. Because you've added another block of code to pull in the second feed, you must separate the two with a comma after the closing curly bracket (}) of the first block. The following code snippet shows the added comma in red on the fourth line:

{"id": "rss", "url":"http://blogs.sun.com/JavaFundamentals/feed/entries/rss", "xslStyleSheet": "rss.xsl" }, {"id": "rss2″, "url":"http://blogs.sun.com/new2javaUpdates/feed/entries/rss", "xslStyleSheet": "rss.xsl" }

The whatsnew.jsp Page

Go to the whatsnew.jsp page, and delete the HTML code. Add the following static HTML code:

<h3>What's Popular</h3> <ul> <li><a href="http://java.sun.com/docs/books/tutorial/">The Java Tutorial</a></li> <li><a href="http://blogs.sun.com/JavaFundamentals/">Java Technology Fundamentals</a></li> <li><a href="http://blogs.sun.com/CoreJavaTechTips/">Core Tech Tips</a></li> <li><a href="http://java.sun.com/developer/onlineTraining/tools/netbeans/">Easy Web Site Creation in the NetBeans IDE</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/">The Java EE 5 Tutorial</a></li> </ul> <h3>What's New</h3>

Next, from the jMaki Widgets palette on the right side of the display, drag and drop the Block List widget onto the page. Change the code as shown here:

<a:widget name="jmaki.blockList" service="/xhp?id=rss2" />

Customizing the jMaki Widgets

All the files that you need for customizing any of the widgets are available in the resources directory by widget name. In this case, look under jMaki for the files for the block list. Expand the blocklist directory, and open the file called component.css.

Change the line that says height : 85px; to height : 25px; and save the file.

Next, open the component.html file, and delete the following code from it:

<br/> @{description}<br/>

This removes the descriptions from the RSS feeds, leaving only the title as a link. You can also add content, such as a date, by adding it to this file. Now, save all the files, click Undeploy and Deploy, then run the portlet again by clicking on Run in the menu and selecting Run Main Project.

Again, click Undeploy and Deploy. Then click Run the application. You now see the pages that you've created with the content. Notice also that the block list is taking up a lot of room. You can customize jMaki widgets easily by going to the Projects tab, expanding the resources directory, expanding the jMaki directory and then blockList. Edit component.css so that the height is just 25 pixels (25px).

Click Undeploy and Deploy again. When you run the portlet.

Your portlet is now complete. Once the portlet is deployed, users can add the portlet to their portal page and have access to the information they want on their page. You can tailor portlets in many different ways to suit the needs of your web site. The NetBeans IDE provides many widgets that you can drag and drop, but you are not limited by what that palette provides. You can also create your own widgets, or use Java code to create an unlimited number of objects to get the functionality that you want.

The next step is to archive the entire project in a ZIP file and send it to the server administrator. If you are also the server administrator, read the next section.

Packaging and Deployment

The portlet specification specifies the packaging and deployment of portlets as part of standard Web Application Archive (WAR) files that may contain other web components, such as JSP pages and servlets. In addition to the web.xml deployment descriptor now found in WAR files, the portlet.xml file in the WEB-INF directory descriptor defines all portlets and portlet-related configurations. An XML schema included in the portlet specification JSR 168 defines the standard elements for portlet configuration stored in the portlet.xml file.

Each portal-server vendor must provide a tool to parse the portlet descriptor file and deploy the portlet. These tools likely exist in GUI form as well as in command-line form. Developers will be able to integrate the command-line deployment tools with the Apache Ant tool. This creates additional development environment possibilities, because most development tools provide an interface for Apache Ant.

To deploy the project onto the server, see the documentation for your portal server for complete details. Most portal servers will allow you to deploy the WAR file, which is located in your project's dist directory after you perform a build. Depending on your portal server, this may be deployed by using the Ant command, copying the WAR to your portal autodeploy directory, or using the administrative feature of your portal server.

Summary

Now that you have created a portlet, you can create other types of portlets for the portal page for your users. Portlets can include components such as local weather, the latest news, live sports scores, maps, and RSS feeds from other sites. Portlets allow your users to customize the web page to meet their specific needs, and this keeps them coming back to your web site.

For More Information

• Flash Demo Using Portal Pack Plug-ins/Netbeans 6.0 Beta With OpenPortal Portlet Container
• Understanding the Portlet Container 2.0 Beta Software
• Introducing Java Portlet Specifications: JSR 168 and JSR 286
• Introduction to JSR 168 — The Java Portlet Specification (PDF)
• OpenPortal Portlet Repository

See Also http://java.sun.com/developer/technicalArticles/tools/nb_portlets/?cid=925028