public class HelloWorldPortlet extends GenericPortlet

All Portlets MUST implement the javax.portlet.Portlet interface. The Portlet API also provides a convenience implementation of this interface in the form of the javax.portlet.GenericPortlet class which, among other things, implements the Portlet render method to dispatch to abstract mode-specific methods to make it easier to support the standard portlet modes. It also provides a default implementation for processAction, init and destory methods. It is recommended to extend GenericPortlet for most cases.

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

As we extend from GenericPortlet and we are only interested in supported the VIEW mode, we only need to implement the doView method, and GenericPortlet's render implementation will call our implementation when the VIEW mode is requested.

rResponse.setContentType("text/html");

Just like in the servlet-world, you must declare what content-type the portlet will be responding in. You need to do this before starting to write content or the portlet will throw an exception.

PrintWriter writer = rResponse.getWriter();
writer.write("Hello World!");
writer.close();

Here we output the text Hello World! in our portlet window.

portlet.xml

<?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 Portlet Specification. You may define more than one portlet application in this file.

portlet-instances.xml

<?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 create an instance of a portlet. The portlet-ref value must match the portlet-name value given in the packaged portlet.xml. The instance-id value can be named anything, but it must match the instance-ref value given in the *-object.xml file we will explore below.

helloworld-object.xml

<?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 thier 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.

protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) { ... }

// And

protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) { ... } 

Support for these Modes must be declared in the portlet.xml. They will be triggered when a user clicks on the respective icons in the portlet window titlebar, or through generated links within the portlet.

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

   // do something

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

This method will be triggered upon clicking on an ActionURL from our view.jsp. It will retrieve yourname from the HTML form, and pass it along as a renderParameter to the doView() method.

rResponse.setContentType("text/html");

Just like in the servlet world, you must declare which kind of MIME type of the content the portlet will be generating.

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

In this case, our doView implementation is responsible for dispatching to the appropriate JSP view.jsp or view2.jsp, depending on the existence of the yourname parameter passed in from processAction.

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

Define the portlet taglib. You do NOT need to bundle the portlet taglib, JBoss Portal will handle that for you.

<portlet:defineObjects/>

Calling defineObjects makes available implicit objects, such as renderRequest, actionRequest, portletConfig, in this JSP.

<form action="<portlet:actionURL><portlet:param name="page" value="mainview"/>
      </portlet:actionURL>" method="POST">

We create an HTML form, but generate the URL it will post to using the portlet tag library. In this case, notice how we are creating an actionURL, which will activate our processAction method, passing in any input parameters in the form.

<a href="<portlet:renderURL><portlet:param name="yourname" value="Roy Russo">
</portlet:param></portlet:renderURL>">

Likewise, we are able to create a link to our doView method, by simply creating it with a renderURL, that passes in our yourname parameter.

portlet.xml

<?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>HelloWorldJSFPortlet</portlet-name>
      <portlet-class>com.sun.faces.portlet.FacesPortlet</portlet-class>
      <init-param>
         <name>com.sun.faces.portlet.INIT_VIEW</name>
         <value>/WEB-INF/jsp/index.jsp</value>
      </init-param>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <portlet-info>
         <title>HelloWorld JSF Portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>

This file must adhere to its definition in the Portlet Specification. You may define more than one portlet application in this file. Now let's look at the portions that deal with our use of JSF:

faces-config.xml

<?xml version="1.0"?>
<!DOCTYPE faces-config PUBLIC
   "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
   "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>
   <managed-bean>
      <description>Basic UserBean</description>
      <managed-bean-name>user</managed-bean-name>
      <managed-bean-class>org.jboss.portlet.hello.bean.User</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
   </managed-bean>
   <navigation-rule>
      <navigation-case>
         <from-outcome>done</from-outcome>
         <to-view-id>/WEB-INF/jsp/result.jsp</to-view-id>
      </navigation-case>
   </navigation-rule>
</faces-config>

There is nothing special about the faces-config.xml file included here. This application would work just as well outside of a portlet as it would inside a portlet container. In the above lines, we define a basic User Bean and a navigation rule to handle the submittal of the original form on index.jsp.

web.xml

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC
   "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
   "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>

    <!-- Faces Servlet -->
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>


    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.jsf</url-pattern>
    </servlet-mapping>

</web-app>

For the Sun RI, this definition is mandatory to associate jsf extension with the faces servlet.

jsf-portlet.jar This library that can be downloaded here: https://jsfportletbridge.dev.java.net/servlets/ProjectDocumentList contains the classes for the JSF-Portlet bridge. Since they are not included with the JSF implementation (unlike myfaces) neither in JBoss AS, it is required to have this library available in the package.

portlet.xml

<?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>HelloWorldJSFPortlet</portlet-name>
      <portlet-class>org.apache.myfaces.portlet.MyFacesGenericPortlet</portlet-class>
      <init-param>
         <name>default-view</name>
         <value>/WEB-INF/jsp/index.jsp</value>
      </init-param>
      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>VIEW</portlet-mode>
      </supports>
      <portlet-info>
         <title>HelloWorld JSF Portlet</title>
      </portlet-info>
   </portlet>
</portlet-app>

This file must adhere to its definition in the Portlet Specification. You may define more than one portlet application in this file. Now let's look at the portions that deal with our use of JSF:

faces-config.xml

<?xml version="1.0"?>
<!DOCTYPE faces-config PUBLIC
   "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
   "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>
   <managed-bean>
      <description>Basic UserBean</description>
      <managed-bean-name>user</managed-bean-name>
      <managed-bean-class>org.jboss.portlet.hello.bean.User</managed-bean-class>
      <managed-bean-scope>session</managed-bean-scope>
   </managed-bean>
   <navigation-rule>
      <navigation-case>
         <from-outcome>done</from-outcome>
         <to-view-id>/WEB-INF/jsp/result.jsp</to-view-id>
      </navigation-case>
   </navigation-rule>
</faces-config>

There is nothing special about the faces-config.xml file included here. This application would work just as well outside of a portlet as it would inside a portlet container. In the above lines, we define a basic User Bean and a navigation rule to handle the submittal of the original form on index.jsp.