This section details deploying your first portlet in JBoss Portal. Before proceeding, download the HelloWorldPorlet from JBoss PortletSwap.

Like other Java EE applications, portlets are packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles, images, HTML, JSPs, and other static or dynamic files. The following is an example of the directory structure of the HelloWorldPortlet portlet:

The following is the HelloWorldPortlet/src/main/org/jboss/portlet/hello/HelloWorldPortlet.java java source file, which comes bundled with the HelloWorldPortlet:

package org.jboss.portlet.hello;

import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.UnavailableException;
import java.io.IOException;
import java.io.PrintWriter;

public class HelloWorldPortlet extends GenericPortlet

{
	protected void doView(RenderRequest rRequest, RenderResponse rResponse) 
	throws PortletException, IOException, UnavailableException

	{
		rResponse.setContentType("text/html");
		PrintWriter writer = rResponse.getWriter();
		writer.write("Hello World!");
		writer.close();
	}

} 

JBoss Portal requires certain descriptors to be included in a portlet WAR file. Some of these descriptors are defined by the JSR-168 Portlet Specification, and others are specific to JBoss Portal. The following is an example of the directory structure of the HelloWorldPortlet portlet:

The following is an example of the HelloWorldPortlet/WEB-INF/portlet.xml file. Note: in order to create the WEB-INF and META-INF directories, extract the helloworldportlet.war file:

<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
                                 http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd"
             version="1.0">
   <portlet>
      <portlet-name>HelloWorldPortlet</portlet-name>
      <portlet-class>org.jboss.portlet.hello.HelloWorldPortlet</portlet-class>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <portlet-info>
         <title>HelloWorld Portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>

This file must adhere to its definition in the JSR-168 Portlet Specification. You may define more than one portlet application in this file.

The following is an example of the HelloWorldPortlet/WEB-INF/portlet-instances.xml file:

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portlet Instances 2.6//EN"
   "http://www.jboss.org/portal/dtd/portlet-instances_2_6.dtd">
<deployments>
   <deployment>
      <instance>
         <instance-id>HelloWorldPortletInstance</instance-id>
         <portlet-ref>HelloWorldPortlet</portlet-ref>
      </instance>
   </deployment>
</deployments>

This is a JBoss Portal specific descriptor that allows you to create instances of portlets. The <portlet-ref> value must match the <portlet-name> value given in the HelloWorldPortlet/WEB-INF/portlet.xml file. The <instance-id> value can be named anything, but it must match the instance-ref values given in *-object.xml files as we shall below.

The following is an example helloworld-object.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portal Object 2.6//EN"
   "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
   <deployment>
      <parent-ref>default.default</parent-ref>
      <if-exists>overwrite</if-exists>
      <window>
         <window-name>HelloWorldPortletWindow</window-name>
         <instance-ref>HelloWorldPortletInstance</instance-ref>
         <region>center</region>
         <height>1</height>
      </window>
   </deployment>
</deployments>

*-object.xml files are JBoss Portal specific descriptors and allow users to define the structure of their portal instances as well as create/configure their windows and pages. In our example, we create a portlet window, specify that it will display the markup generated by the HelloWorldPortletInstance portlet instance, assign it to the default.default page, and specify where it should appear on that page.

To illustrate the relationship between the descriptors, we have provided this simple diagram

Portal 2.6 introduces the notion of content type, which is a generic mechanism to specify which content will be displayed by a given portlet window. The window section of the previous example can be re-written to take advantage of the new content framework, resulting in the following deployment descriptor:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deployments PUBLIC
   "-//JBoss Portal//DTD Portal Object 2.6//EN"
   "http://www.jboss.org/portal/dtd/portal-object_2_6.dtd">
<deployments>
   <deployment>
      <parent-ref>default.default</parent-ref>
      <if-exists>overwrite</if-exists>
      <window>
         <window-name>HelloWorldPortletWindow</window-name>
         <content>
            <content-type>portlet</content-type>
            <content-uri>HelloWorldPortletInstance</content-uri>
         </content>
         <region>center</region>
         <height>1</height>
      </window>
   </deployment>
</deployments>

This declaration is equivalent to the previous example. We specify that the content being displayed by the HelloWorldPortletWindow is a portlet content. The content URI identifies which content to be displayed, in this case, the HelloWorldPortletInstance. It is possible to declare windows with a cms content type and use directly the path to the file in the CMS to make the window show the content of the associated file. That behavior is pluggable and it is possible to plug virtually any kind of content.

If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. Executing the deploy target will compile all the source files and produce a helloworldportlet.war file under HelloWorldPortlet\helloworldportlet.war.

If you want to create an expanded WAR directory, after executing the above deploy target, you should execute the explode target.

The above target will produce the following:

This will deflate helloworldportlet.war, and allow you to deploy it as an expanded directory. It will work just the same but is easier to work with during development as you can easily modify the XML descriptors, resources files, JSF/JSP pages. A simple touch operation (or equivalent) on the web.xml file will let any live JBoss Application Server instance know that it needs to hot-redeploy your web application.

Deploying a portlet is as simple as copying/moving helloworldportlet.war to your server deploy directory. Doing this on a running instance of JBoss Portal and application server, will trigger a hot-deploy of your portlet:

18:25:56,366 INFO  [Server] JBoss (MX MicroKernel) [4.2.2.GA (build:
             CVSTag=JBoss_4_0_5_GA date=2006000000)] Started in 1m:3s:688ms
18:26:21,147 INFO  [TomcatDeployer] deploy, ctxPath=/helloworldportlet,
             warUrl=.../tmp/deploy/tmp35219helloworldportlet-exp.war/

Pointing your browser to http://localhost:8080/portal/, should yield a view of our HelloWorldPortlet, added to the default page of Portal:

This section will introduce the reader to deploying a simple JSP portlet in JBoss Portal. It requires you download the HelloWorldJSPPortlet from PortletSwap.com, using this link.

This portlet will introduce you to using JSPs for view rendering and the portlet taglib for generating links.

The application descriptors for this portlet are similar to the ones we saw in Section 5.2.1.4, “Application Descriptors”. See the Section 6.2, “Portlet Descriptors” chapter on descriptors for more details.

As you can see in the figure above, the package content is what you'd expect from a traditional web application augmented with the portlet- and JBoss Portal-specific application descriptors.

Included in the download bundle you should have one java source file: HelloWorldJSPPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java, containing the following:

package org.jboss.portlet.hello;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.PortletRequestDispatcher;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.UnavailableException;
import java.io.IOException;

public class HelloWorldJSPPortlet extends GenericPortlet
{
   protected void doView(RenderRequest rRequest, RenderResponse rResponse)
                     throws PortletException, IOException, UnavailableException
   {
      rResponse.setContentType("text/html");

      String sYourName = (String) rRequest.getParameter("yourname");

      if(sYourName != null)
      {
         rRequest.setAttribute("yourname", sYourName);
         PortletRequestDispatcher prd = getPortletContext()
            .getRequestDispatcher("/WEB-INF/jsp/view2.jsp");
         prd.include(rRequest, rResponse);
      }
      else
      {
         PortletRequestDispatcher prd = getPortletContext()
            .getRequestDispatcher("/WEB-INF/jsp/view.jsp");
         prd.include(rRequest, rResponse);
      }
   }

   public void processAction(ActionRequest aRequest, ActionResponse aResponse)
                  throws PortletException, IOException, UnavailableException
   {
      String sYourname = (String) aRequest.getParameter("yourname");

      // do something

      aResponse.setRenderParameter("yourname", sYourname);
   }

   protected void doHelp(RenderRequest rRequest, RenderResponse rResponse)
                     throws PortletException, IOException, UnavailableException
   {
      rResponse.setContentType("text/html");
      PortletRequestDispatcher prd = getPortletContext()
         .getRequestDispatcher("/WEB-INF/jsp/help.jsp");
      prd.include(rRequest, rResponse);
   }

   protected void doEdit(RenderRequest rRequest, RenderResponse rResponse)
                     throws PortletException, IOException, UnavailableException
   {
      rResponse.setContentType("text/html");
      PortletRequestDispatcher prd = getPortletContext()
         .getRequestDispatcher("/WEB-INF/jsp/edit.jsp");
      prd.include(rRequest, rResponse);
   }
}

Now let's look at some of our methods:

Of importance in this tutorial are the two view JSPs. The first, view.jsp, allows the user to input his name, which is then posted to the processAction method in our portlet class, set as a renderParameter, then the render method is invoked (in our case, doView, which then dispatches to our view2.jsp).

Now let's have a look at our view.jsp:

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

<portlet:defineObjects/>

<div align="center">
   This is a simple HelloWorld JSP Portlet. Type in a name and it will dispatch
   to the view2.jsp to print out your name.
   <br/>

   <form action="<portlet:actionURL><portlet:param name="page" value="mainview"/>
         </portlet:actionURL>" method="POST">
      Name:<br/>
      <input type="text" name="yourname"/>
   </form>
   <br/>
   You can also link to other pages, using a renderURL, like <a
      href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo">
            </portlet:param></portlet:renderURL>">this</a>.
</div>

If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. Executing the deploy target will compile all source files and produce a helloworldjspportlet.war file in a way similar to what we saw in Section 5.2.1.5, “Building your portlet”.

The explode target will produce the following:

Deploying the portlet is as easy as copying/moving the helloworldjspportlet.war file to the server deploy directory. We can then see our portlet on the Portal default page (http://localhost:8080/portal/):

This section will introduce the reader to deploying a simple JSF portlet in JBoss Portal, using Apache's MyFaces JSF implementation on JBoss AS 4.2.x. It requires you download the HelloWorldJSFSunRIPortlet from PortletSwap.com, using this link: http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles/HelloWorldJSFSunRIPortlet.zip.

Like a typical JSF application, we also package our faces-config.xml that defines our managed-beans, converters, validators, navigation rules, etc...

For the sake of brevity, we only discuss the portlet.xml and faces-config.xml descriptors here. For discussion on the other descriptors, please view Section 5.2.1.4, “Application Descriptors” or the chapter on descriptors: Section 6.2, “Portlet Descriptors”.

If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. Executing ant will compile all source files and produce a helloworldjspportlet.war file in a way similar to what we saw in Section 5.2.1.5, “Building your portlet”.

Deploying the portlet is as easy as copying/moving the helloworldjspportlet.war file to the server deploy directory. We can then see our portlet on the Portal default page (http://localhost:8080/portal/):

This section will introduce the reader to deploying a simple JSF portlet in JBoss Portal, using Apache's MyFaces JSF implementation on JBoss AS 4.2. It requires you download the HelloWorldJSFMyFaces42Portlet from PortletSwap.com, using this link: http://anonsvn.jboss.org/repos/portletswap/portlets/2_6/bundles/HelloWorldJSFMyFaces42Portlet.zip. There are actually different ways to do it, one would be to use MyFaces globally for the whole server and replace the Sun RI libraries by the myFaces ones, but in this section the portlet will not affect the application server and embed its own libraries.

Like a typical JSF application, we also package our faces-config.xml that defines our managed-beans, converters, validators, navigation rules, etc... The WEB-INF/lib must contain the MyFaces libraries along with dependent libraries.

For the sake of brevity, we only discuss the portlet.xml, web.xml and faces-config.xml descriptors here. For discussion on the other descriptors, please view Section 5.2.1.4, “Application Descriptors” or the chapter on descriptors: Section 6.2, “Portlet Descriptors”.

If you have downloaded the sample, you can execute the build.xml with ant or inside your IDE. Executing ant will compile all source files and produce a helloworldjsfportlet.war file in a way similar to what we saw in Section 5.2.1.5, “Building your portlet”.

Deploying the portlet is as easy as copying/moving the helloworldjsfmyfacesportlet.war file to the server deploy directory. We can then see our portlet on the Portal default page (http://localhost:8080/portal/):