JBoss® Portal 2.6.6

The binary download is available from the JBoss Portal Downloads page. Look for the JBoss Portal Binary package. Once the binary ZIP file has been downloaded and extracted, the folder hierarchy will look similar to the following:

Files contained in this download are used in later sections. Download and extract the JBoss Portal binary ZIP file before proceeding.

Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS installed. Customers who have access to the JBoss Customer Support Portal (CSP) are advised to download and install JBoss EAP 4.3. Customers who do not have access to the JBoss CSP are advised to use JBoss AS. For JBoss AS installation instructions, please refer to the JBoss AS Installation Guide.

For JBoss EAP, JBoss AS, and build targets to work, you must configure a JBOSS_HOME environment variable. This environment variable must point to the root directory of the JBoss EAP or JBoss AS installation directory, which is the directory where the JBoss EAP or JBoss AS files were extracted to.

On Windows, this is accomplished by going to Start > Settings > Control Panel > System > Advanced > Environment Variables. Under the System Variables section, click New. Set the JBOSS_HOME environment variable to the location of your JBoss EAP or JBoss AS installation directory:

To configure the JBOSS_HOME environment variable on Linux:

A database is required for JBoss Portal to run. JBoss EAP and JBoss AS include an embedded Hypersonic SQL database that JBoss Portal can use; however, this is only recommended for developer use. The following databases are recommended for production use, and have had test suites run against them: MySQL® 4 and 5, Microsoft® SQL Server®, PostgreSQL 8, and Oracle® Database 9 and 10. JBoss Portal can use any database that is supported by Hibernate.

To configure a database to use with JBoss Portal:

The JBoss Portal binary download that was extracted in Section 2.2.1.1, “Getting the Binary”, contains pre-configured Datasource descriptors for the more popular databases. Datasource descriptors are provided for the MySQL 4 and 5, PostgreSQL, Microsoft SQL Server, and Oracle databases, and can be found in the setup subdirectory where the JBoss Portal binary was extracted to:

Copy the Datasource descriptor that matches your database into the $JBOSS_HOME/server/configuration/deploy/ directory, where configuration is either all, default, minimal or production. The production configuration only exists on JBoss EAP, and not JBoss AS. For example, if you are using the all configuration, copy the Datasource descriptor into the $JBOSS_HOME/server/all/deploy/ directory.

After the Datasource descriptor has been copied into the deploy directory, make sure the user-name, password, connection-url, and driver-class, are correct for your chosen database. Datasource descriptor files can be deployed to test before being used in production. The following is an example Datasource descriptor for a PostgreSQL database:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:postgresql:jbossportal</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>portal</user-name>
    <password>portalpassword</password>
  </local-tx-datasource>
</datasources>

For further details about Datasource descriptors, please refer to the JBoss JDBC Datasource Wiki page.

Before deploying JBoss Portal, make sure you have JBoss EAP or JBoss AS installed. Customers who have access to the JBoss Customer Support Portal (CSP) are advised to download and install JBoss EAP 4.3. Customers who do not have access to the JBoss CSP are advised to use JBoss AS. For JBoss AS installation instructions, please refer to the JBoss AS Installation Guide.

For JBoss EAP, JBoss AS, and build targets to work, you must configure a JBOSS_HOME environment variable. This environment variable must point to the root directory of the JBoss EAP or JBoss AS installation directory, which is the directory where the JBoss EAP or JBoss AS files were extracted to.

On Windows, this is accomplished by going to Start > Settings > Control Panel > System > Advanced > Environment Variables. Under the System Variables section, click New. Set the JBOSS_HOME environment variable to the location of your JBoss EAP or JBoss AS installation directory:

To configure the JBOSS_HOME environment variable on Linux:

This section describes how to deploy a portlet in JBoss Portal. Before proceeding, download the HelloWorldPortlet from JBoss PortletSwap.

Like other Java Platform, Enterprise Edition (Java EE) applications, portlets are packaged in WAR files. A typical portlet WAR file can include servlets, resource bundles, images, HTML, JavaServer™ Pages (JSP™), 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:

To create the WEB-INF/ and META-INF/ directories, extract the helloworldportlet.war file.

The following is an example of the HelloWorldPortlet/WEB-INF/portlet.xml file. This file must adhere to its definition in the JSR-168 Portlet Specification. You may define more than one portlet application in this 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>

The HelloWorldPortlet/WEB-INF/portlet-instances.xml file 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> value given in the *-object.xml file, which in this example, would be the HelloWorldPortlet/WEB-INF/helloworld-object.xml 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>

The *-object.xml file is a JBoss Portal specific descriptor that allow users to define the structure of their portal instances, and create and configure their windows and pages. In the following example:

The following is an example HelloWorldPortlet/WEB-INF/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>

The following diagram illustrates the relationship between the portlet.xml, portlet-instances.xml, and helloworld-object.xml descriptors:

JBoss Portal 2.6 introduces the notion of content-type, which is a generic mechanism to specify what content displayed by a given portlet window. The window section of the previous example, HelloWorldPortlet/WEB-INF/helloworld-object.xml, can be re-written to take advantage of the new content framework. The following is an example deployment descriptor that uses the new content framework:

<?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 HelloWorldPortlet/WEB-INF/helloworld-object.xml example. Use <content-type> to specify the content to display. In this example, the content being displayed by the HelloWorldPortletWindow is a portlet. The <content-uri> element specifies which content to display, which in this example, is the HelloWorldPortletInstance:

<content>
   <content-type>portlet</content-type>
   <content-uri>HelloWorldPortletInstance</content-uri>
</content>

To display certain content or a file, use the cms content-type, with the <content-uri> element being the path to the file in the CMS. This behavior is pluggable: you can plug in almost any type of content.

The HelloWorldPortlet.zip file contains a pre-compiled helloworldportlet.war file; however, to manually build the helloworldportlet.war file:

Note: the directory names will be different for your system.

Expanding the helloworldportlet.war file allows you to deploy the portlet as an expanded directory, which makes development easier. As well, it gives you access to the application descriptors, resource files, JSF, and JSP pages. To expand the helloworldportlet.war file:

Note: the directory names will be different for your system.

The ant explode command creates a directory structure such as the following:

The expanded WAR file and the application descriptors are located in the HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/WEB-INF/ directory.

If you did not expand the helloworldportlet.war file, copy the HelloWorldPortlet/helloworldportlet.war file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworldportlet.war file, copy the HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/ directory into the correct JBoss AS or JBoss EAP deploy/ directory. For example, if you are using the default JBoss AS profile, copy the WAR file or the expanded directory into the $JBOSS_HOME/server/default/deploy/ directory.

Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss Portal, triggers a hot-deploy of the portlet:

INFO  [TomcatDeployer] deploy, ctxPath=/helloworldportlet, 
warUrl=.../tmp/deploy/tmp35219helloworldportlet-exp.war/

To see the HelloWorldPortlet, navigate to http://localhost:8080/portal/, or, if the default JBoss Portal page is already open, refresh the page. The HelloWorldPortlet is added to the bottom of the default JBoss Portal page:

To re-deploy the portlet, for example, if you have made changes to any of the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldportlet.war/WEB-INF/web.xml file. This only works if you copied the HelloWorldPortlet/output/lib/exploded/helloworldportlet.war/ directory into the JBoss AS or JBoss EAP deploy/ directory. On Linux, run the touch $JBOSS_HOME/server/configuration/deploy/helloworldportlet.war/WEB-INF/web.xml command to re-deploy the HelloWorldPortlet.

Re-deploying the HelloWorldPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following:

INFO  [TomcatDeployer] undeploy, ctxPath=/helloworldportlet, 
warUrl=.../deploy/helloworldportlet.war/
INFO  [TomcatDeployer] deploy, ctxPath=/helloworldportlet, 
warUrl=.../deploy/helloworldportlet.war/

This section describes how to deploy a JSP™ portlet in JBoss Portal. Before proceeding, download the HelloWorldJSPPortlet from JBoss PortletSwap. The HelloWorldJSPPortlet demonstrates how to use JSP pages for view rendering, and the portlet tag library (taglib) for generating links.

The application descriptors for the HelloWorldJSPPortlet portlet are similar to those from the HelloWorldPortlet (Section 5.2.1.4, “Application Descriptors”). Refer to Section 6.2, “Portlet Descriptors” for further information about application descriptors.

The HelloWorldJSPPortlet portlet contains the traditional portlet and JBoss Portal specific application descriptors. The following is an example of the directory structure of the HelloWorldJSPPortlet portlet:

To create the WEB-INF/ and META-INF/ directories, extract the helloworldjspportlet.war file.

The HelloWorldJSPPortlet contains the HelloWorldJSPPortlet/src/main/org/jboss/portlet/hello/HelloWorldJSPPortlet.java file:

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);
   }
}

The HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp and HelloWorldJSPPortlet/WEB-INF/jsp/view2.jsp JSP™ files are included in the HelloWorldJSPPortlet portlet. The view.jsp file allows a user to input their name. This is then posted to the processAction method in the portlet class, which is set as a aResponse.setRenderParameter. The doView render method is invoked, which dispatches to the view2.jsp JSP:

The following is an example of the HelloWorldJSPPortlet/WEB-INF/jsp/view.jsp file:

<%@ 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>

The HelloWorldJSPPortlet.zip file contains a pre-compiled helloworldjspportlet.war file; however, to manually build the helloworldjspportlet.war file:

Note: the directory names will be different for your system.

Expanding the helloworldjspportlet.war file allows you to deploy the portlet as an expanded directory, which makes development easier. As well, it gives you access to the application descriptors, resource files, JSF, and JSP™ pages. To expand the helloworldjspportlet.war file:

Note: the directory names will be different for your system.

The ant explode command creates a directory structure such as the following:

The expanded WAR file and the application descriptors are located in the HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/WEB-INF/ directory.

If you did not expand the helloworldjspportlet.war file, copy the HelloWorldJSPPortlet/helloworldjspportlet.war file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworldjspportlet.war file, copy the HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/ directory into the correct JBoss AS or JBoss EAP deploy/ directory. For example, if you are using the default JBoss AS profile, copy the WAR file or the expanded directory into the $JBOSS_HOME/server/default/deploy/ directory.

Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss Portal, triggers a hot-deploy of the portlet:

INFO  [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet, 
warUrl=.../deploy/helloworldjspportlet.war/

To see the HelloWorldJSPPortlet, navigate to http://localhost:8080/portal/, or, if the default JBoss Portal page is already open, refresh the page. The HelloWorldJSPPortlet is added to the bottom of the default JBoss Portal page:

To re-deploy the portlet, for example, if you have made changes to any of the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldjspportlet.war/WEB-INF/web.xml file. This only works if you copied the HelloWorldJSPPortlet/output/lib/exploded/helloworldjspportlet.war/ directory into the JBoss AS or JBoss EAP deploy/ directory. On Linux, run the touch $JBOSS_HOME/server/configuration/deploy/helloworldjspportlet.war/WEB-INF/web.xml command to re-deploy the HelloWorldJSPPortlet.

Re-deploying the HelloWorldJSPPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following:

INFO  [TomcatDeployer] undeploy, ctxPath=/helloworldjspportlet, 
warUrl=.../deploy/helloworldjspportlet.war/
INFO  [TomcatDeployer] deploy, ctxPath=/helloworldjspportlet, 
warUrl=.../deploy/helloworldjspportlet.war/

This section describes how to deploy a JSF portlet in JBoss Portal, using the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Before proceeding, download the HelloWorldJSFSunRIPortlet from JBoss PortletSwap.

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. Like a typical JSF application, the HelloWorldJSFSunRIPortlet package contains a faces-config.xml file that defines managed-beans, converters, validators, navigation rules, and so on. The following is an example of the directory structure of the HelloWorldJSFSunRIPortlet portlet:

To create the WEB-INF/ and META-INF/ directories, extract the helloworldjsfsunriportlet.war file.

Only the portlet.xml, faces-config.xml, and web.xml descriptors are described here. For more information about application descriptors, refer to Section 5.2.1.4, “Application Descriptors” and Section 6.2, “Portlet Descriptors”.

The following is an example of the HelloWorldJSFSunRIPortlet/WEB-INF/portlet.xml file. This file must adhere to its definition in the JSR-168 Portlet Specification. You may define more than one portlet application in this 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>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>

The following is an example HelloWorldJSFSunRIPortlet/WEB-INF/faces-config.xml file:

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

Without the faces-config.xml file, the application would work the same outside of the portlet as it would inside a portlet container. In this example, a basic user bean, <managed-bean-name>user</managed-bean-name>, and a navigation rule are defined, which handle the submission of the original form in the HelloWorldJSFSunRIPortlet/WEB-INF/jsp/index.jsp file.

The following is an example of the Faces Servlet and Faces Servlet Mapping sections from the HelloWorldJSFSunRIPortlet/WEB-INF/web.xml file:

<?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 Sun JSF RI portlets, the Faces Servlet and Faces Servlet Mapping sections are required to associate files with the .jsf extension to the Apache MyFaces servlet.

The HelloWorldJSFSunRIPortlet.zip file contains a pre-compiled helloworldjsfsunriportlet.war file; however, to manually build the helloworldjsfsunriportlet.war file:

Note: the directory names will be different for your system.

Expanding the helloworldjsfsunriportlet.war file allows you to deploy the portlet as an expanded directory, which makes development easier. As well, it gives you access to the application descriptors, resource files, JSF, and JSP pages. To expand the helloworldjsfsunriportlet.war file:

Note: the directory names will be different for your system.

The expanded WAR file and the application descriptors are located in the HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/WEB-INF/ directory.

If you did not expand the helloworldjsfsunriportlet.war file, copy the HelloWorldJSFSunRIPortlet/helloworldjsfsunriportlet.war file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworldjsfsunriportlet.war file, copy the HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/ directory into the correct JBoss AS or JBoss EAP deploy/ directory. For example, if you are using default JBoss AS profile, copy the WAR file or the expanded directory into the $JBOSS_HOME/server/default/deploy/ directory.

Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss Portal, triggers a hot-deploy of the portlet:

INFO  [TomcatDeployer] deploy, ctxPath=/helloworldjsfsunriportlet,
warUrl=.../tmp/deploy/tmp9138helloworldjsfsunriportlet-exp.war/

To see the HelloWorldJSFSunRIPortlet, navigate to http://localhost:8080/portal/, or, if the default JBoss Portal page is already open, refresh the page. The HelloWorldJSFSunRIPortlet is added to the bottom of the default JBoss Portal page:

To re-deploy the portlet, for example, if you have made changes to any of the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml file. This only works if you copied the HelloWorldJSFSunRIPortlet/output/lib/exploded/helloworldjsfsunriportlet.war/ directory into the JBoss AS or JBoss EAP deploy/ directory. On Linux, run the touch $JBOSS_HOME/server/configuration/deploy/helloworldjsfsunriportlet.war/WEB-INF/web.xml command to re-deploy the HelloWorldJSFSunRIPortlet.

Re-deploying the HelloWorldJSFSunRIPortlet produces output to the JBoss AS or JBoss EAP console, similar to the following:

INFO  [TomcatDeployer] undeploy, ctxPath=/helloworldjsfsunriportlet, 
warUrl=.../deploy/helloworldjsfsunriportlet.war/
INFO  [TomcatDeployer] deploy, ctxPath=/helloworldjsfsunriportlet, 
warUrl=.../deploy/helloworldjsfsunriportlet.war/

This section describes how to deploy a JSF portlet in JBoss Portal, using the Apache MyFaces JSF implementation in JBoss AS and JBoss EAP. Before proceeding, download the HelloWorldJSFMyFaces42Portlet from JBoss PortletSwap.

Apache MyFaces can be used globally for the entire server, replacing the Sun JSF RI libraries, but the HelloWorldJSFMyFaces42Portlet uses its own libraries, but does not affect the application server.

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. Like a typical JSF application, the HelloWorldJSFMyFaces42Portlet package contains a faces-config.xml file that defines managed-beans, converters, validators, navigation rules, and so on. The following is an example of the directory structure of the HelloWorldJSFMyFaces42Portlet portlet:

To create the WEB-INF/ and META-INF/ directories, extract the helloworldjsfmyfacesportlet.war file. The WEB-INF/lib/ directory must contain the Apache MyFaces libraries, along with the dependent libraries.

Only the portlet.xml, faces-config.xml, and web.xml descriptors are described here. For more information about application descriptors, refer to Section 5.2.1.4, “Application Descriptors” and Section 6.2, “Portlet Descriptors”.

The following is an example of the HelloWorldJSFMyFaces42Portlet/WEB-INF/portlet.xml file. This file must adhere to its definition in the JSR-168 Portlet Specification. You may define more than one portlet application in this 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>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>

The following is an example HelloWorldJSFMyFaces42Portlet/WEB-INF/faces-config.xml file:

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

Without the faces-config.xml file, the application would work the same outside of the portlet as it would inside a portlet container. In this example, a basic user bean, <managed-bean-name>user</managed-bean-name>, and a navigation rule are defined, which handle the submission of the original form in the HelloWorldJSFMyFaces42Portlet/WEB-INF/jsp/index.jsp file.

The following is an example of the <context-parm> element from the HelloWorldJSFMyFaces42Portlet/WEB-INF/web.xml file:

<context-param>
   <param-name>org.jboss.jbossfaces.WAR_BUNDLES_JSF_IMPL</param-name>
   <param-value>true</param-value>
</context-param>

These extra parameters let the application server know that the portlet embeds its own libraries. This avoids collision with the Sun JSF RI libraries bundled with JBoss AS and JBoss EAP. For more information, refer to the JBossFaces page on the JBoss Wiki.

The HelloWorldJSFMyFaces42Portlet.zip file contains a pre-compiled helloworldjsfmyfacesportlet.war file; however, to manually build the helloworldjsfmyfacesportlet.war file:

Note: the directory names will be different for your system.

Expanding the helloworldjsfmyfacesportlet.war file allows you to deploy the portlet as an expanded directory, which makes development easier. As well, it gives you access to the application descriptors, resource files, JSF, and JSP pages. To expand the helloworldjsfmyfacesportlet.war file:

Note: the directory names will be different for your system.

The expanded WAR file and the application descriptors are located in the HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/WEB-INF/ directory.

If you did not expand the helloworldjsfmyfacesportlet.war file, copy the HelloWorldJSFMyFaces42Portlet/helloworldjsfmyfacesportlet.war file into the correct JBoss AS or JBoss EAP deploy/ directory. If you expanded the helloworldjsfmyfacesportlet.war file, copy the HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/ directory into the correct JBoss AS or JBoss EAP deploy/ directory. For example, if you are using the default JBoss AS profile, copy the WAR file or the expanded directory into the $JBOSS_HOME/server/default/deploy/ directory.

Performing this step on a running instance of JBoss AS or JBoss EAP, and JBoss Portal, triggers a hot-deploy of the portlet.

To see the HelloWorldJSFMyFaces42Portlet, navigate to http://localhost:8080/portal/, or, if the default JBoss Portal page is already open, refresh the page. The HelloWorldJSFMyFaces42Portlet is added to the bottom of the default JBoss Portal page:

To re-deploy the portlet, for example, if you have made changes to any of the application descriptors, touch the $JBOSS_HOME/server/configuration/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml file. This only works if you copied the HelloWorldJSFMyFaces42Portlet/output/lib/exploded/helloworldjsfmyfacesportlet.war/ directory into the JBoss AS or JBoss EAP deploy/ directory. On Linux, run the following command to re-deploy the HelloWorldJSFMyFaces42Portlet:

touch $JBOSS_HOME/server/configuration/deploy/helloworldjsfmyfacesportlet.war/WEB-INF/web.xml

The following example injects a specific style sheet, /images/management/management.css, allowing the portlet to leverage a specific style:

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
   "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
   <portlet>
      <portlet-name>ManagementPortlet</portlet-name>
      <header-content>
         <link rel="stylesheet" type="text/css" href="/images/management/management.css"
               media="screen"/>
      </header-content>
   </portlet>
</portlet-app>

Use the <header-content> and <link> elements to specify a style sheet.

The following example injects the UserModule service as an attribute to the portlet context:

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
   "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
   <service>
      <service-name>UserModule</service-name>
      <service-class>org.jboss.portal.identity.UserModule</service-class>
      <service-ref>:service=Module,type=User</service-ref>
   </service>
</portlet-app>

This allows the portlet to leverage the service, for example:

UserModule userModule = (UserModule) getPortletContext().getAttribute("UserModule");
String userId = request.getParameters().getParameter("userid");
User user = userModule.findUserById(userId);

As of JBoss Portal 2.6.3, icons can be defined for a portlet by using the <icon>, <small-icon>, and <large-icon> elements:

<?xml version="1.0" standalone="yes"?>
<!DOCTYPE portlet-app PUBLIC
   "-//JBoss Portal//DTD JBoss Portlet 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-portlet_2_6.dtd">
<portlet-app>
   <portlet>
      <portlet-name>ManagementPortlet</portlet-name>
      <portlet-info>
         <icon>
            <small-icon>/images/smallIcon.png</small-icon>
            <large-icon>/images/largeIcon.png</small-icon>
         </icon>
      </portlet-info>
   </portlet>
</portlet-app>

References to icons can be absolute, for example, http://www.example.com/images/smallIcon.png, or relative to the web application context, for example, /images/smallIcon.png. Icons can be used by different parts of the portlet user interface.

Several template Datasource descriptors are included in the binary and bundled distributions of JBoss Portal. They are commonly located in the jboss-portal-version/setup/ directory:

The jboss-portal-version/setup/ directory contains sample Datasource descriptors for the MySQL, Microsoft SQL Server, PostgreSQL, and Oracle databases, which can be customized for your own database:

To build the Datasource descriptors from source:

Note: if the JBoss Portal source was not built as per step 3, the sh build.sh datasource and build.bat datasource commands fail with an error, such as the following:

BUILD FAILED
java.io.FileNotFoundException: /jboss-portal-2.6.3.GA-src/core/../thirdparty/libraries.ent 
(No such file or directory)

The datasource build process produces the following directory and file structure, with the Datasource descriptors in the JBOSS_PORTAL_SOURCE_DIRECTORY/core/output/resources/setup directory:

The following is an example Datasource descriptor for a PostgreSQL database:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <local-tx-datasource>
    <jndi-name>PortalDS</jndi-name>
    <connection-url>jdbc:postgresql:jbossportal</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <user-name>portal</user-name>
    <password>portalpassword</password>
  </local-tx-datasource>
</datasources>

Make sure the user-name, password, connection-url, and driver-class, are correct for your chosen database.

Here is the base skeleton of the content portlet. The FSContentDrivenPortlet shows the files which are in the war file in which the portlet is deployed. The arbitrary name filesystem will be the content type interpreted by the portlet.

public class FSContentDrivenPortlet extends GenericPortlet
{

   /** The edit_content mode. */
   public static final PortletMode EDIT_CONTENT_MODE = new PortletMode("edit_content");

   /** The select_content mode. */
   public static final PortletMode SELECT_CONTENT_MODE = new PortletMode("select_content");

   ...

}

First the doDispatch(RenderRequest req, RenderResponse resp) is overridden in order to branch the request flow to a method that will take care of displaying the editor.

protected void doDispatch(RenderRequest req, RenderResponse resp)
                  throws PortletException, PortletSecurityException, IOException
{
   if (EDIT_CONTENT_MODE.equals(req.getPortletMode()) || 
       SELECT_CONTENT_MODE.equals(req.getPortletMode()))
   {
      doEditContent(req, resp);
   }
   else
   {
      super.doDispatch(req, resp);
   }
}

The portlet also needs a few utilities methods which take care of converting content URI to a file back and forth. There is also an implementation of a file filter that keep only text files and avoid the WEB-INF directory of the war file for security reasons.

protected File getFile(String contentURI) throws IOException
{
   String realPath = getPortletContext().getRealPath(contentURI);
   if (realPath == null)
   {
      throw new IOException("Cannot access war file content");
   }
   File file = new File(realPath);
   if (!file.exists())
   {
      throw new IOException("File " + contentURI + " does not exist");
   }
   return file;
}

   protected String getContentURI(File file) throws IOException
   {
      String rootPath = getPortletContext().getRealPath("/");
      if (rootPath == null)
      {
         throw new IOException("Cannot access war file content");
      }

      // Make it canonical
      rootPath = new File(rootPath).getCanonicalPath();

      // Get the portion of the path that is significant for us
      String filePath = file.getCanonicalPath();
      return filePath.length() >=
        rootPath.length() ? filePath.substring(rootPath.length()) : null;
   }

   private final FileFilter filter = new FileFilter()
   {
      public boolean accept(File file)
      {
         String name = file.getName();
         if (file.isDirectory())
         {
            return !"WEB-INF".equals(name);
         }
         else if (file.isFile())
         {
            return name.endsWith(".txt");
         }
         else
         {
            return false;
         }
      }
   };

The editor is probably the longest part of the portlet. It tries to stay simple though and goes directly to the point.

protected void doEditContent(RenderRequest req, RenderResponse resp)
                  throws PortletException, PortletSecurityException, IOException
{
   // Get the uri value optionally provided by the portal
   String uri = req.getParameter("content.uri");

   // Get the working directory directory
   File workingDir;
   if (uri != null)
   {
      workingDir = getFile(uri).getParentFile();
   }
   else
   {
      // Otherwise try to get the current directory we are browsing,
      // if no current dir exist we use the root
      String currentDir = req.getParameter("current_dir");
      if (currentDir == null)
      {
         currentDir = "/";
      }
      workingDir = getFile(currentDir);
   }

   // Get the parent path
   String parentPath = getContentURI(workingDir.getParentFile());

   // Get the children of the selected file, we use a filter
   // to retain only text files and avoid WEB-INF dir
   File[] children = workingDir.listFiles(filter);

   // Configure the response
   resp.setContentType("text/html");
   PrintWriter writer = resp.getWriter();

   //
   writer.print("Directories:<br/>");
   writer.print("<ul>");
   PortletURL choseDirURL = resp.createRenderURL();
   if (parentPath != null)
   {
      choseDirURL.setParameter("current_dir", parentPath);
      writer.print("<li><a href=\"" + choseDirURL + "\">..</a></li>");
   }
   for (int i = 0;i < children.length;i++)
   {
      File child = children[i];
      if (child.isDirectory())
      {
         choseDirURL.setParameter("current_dir", getContentURI(child));
         writer.print("<li><a href=\"" + choseDirURL + "\">" + child.getName() +
                      "</a></li>");
      }
   }
   writer.print("</ul><br/>");

   //
   writer.print("Files:<br/>");
   writer.print("<ul>");
   PortletURL selectFileURL = resp.createActionURL();
   selectFileURL.setParameter("content.action.select", "select");
   for (int i = 0;i < children.length;i++)
   {
      File child = children[i];
      if (child.isFile())
      {
         selectFileURL.setParameter("content.uri", getContentURI(child));
         writer.print("<li><a href=\"" + selectFileURL + "\">" + child.getName() +
                      "</a></li>");
      }
   }
   writer.print("</ul><br/>");

   //
   writer.close();
}

Last but not least the portlet needs to implement the doView(RenderRequest req, RenderResponse resp) method in order to display the file that the portal window wants to show.

protected void doView(RenderRequest req, RenderResponse resp)
                  throws PortletException, PortletSecurityException, IOException
{
   // Get the URI provided by the portal
   String uri = req.getParameter("uri");

   // Configure the response
   resp.setContentType("text/html");
   PrintWriter writer = resp.getWriter();

   //
   if (uri == null)
   {
      writer.print("No selected file");
   }
   else
   {
      File file = getFile(uri);
      FileInputStream in = null;
      try
      {
         in = new FileInputStream(file);
         FileChannel channel = in.getChannel();
         byte[] bytes = new byte[(int)channel.size()];
         ByteBuffer buffer = ByteBuffer.wrap(bytes);
         channel.read(buffer);
         writer.write(new String(bytes, 0, bytes.length, "UTF8"));
      }
      catch (FileNotFoundException e)
      {
         writer.print("No such file " + uri);
         getPortletContext().log("Cannot find file " + uri, e);
      }
      finally
      {
         if (in != null)
         {
            in.close();
         }
      }
   }

   //
   writer.close();
}

Finally we need to make the portal aware of the fact that the portlet can edit and interpret content. For that we need a few descriptors. The portlet.xml descriptor will define our portlet, the portlet-instances.xml will create a single instance of our portlet. The web.xml descriptor will contain a servlet context listener that will hook the content type in the portal content type registry.

<?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>
      <description>File System Content Driven Portlet</description>
      <portlet-name>FSContentDrivenPortlet</portlet-name>
      <display-name>File System Content Driven Portlet</display-name>
      <portlet-class>org.jboss.portal.core.portlet.test.FSContentDrivenPortlet</portlet-class>
      <supports>
         <mime-type>text/html</mime-type>
      </supports>
      <portlet-info>
         <title>File Portlet</title>
         <keywords>sample,test</keywords>
      </portlet-info>
   </portlet>
   ...
</portlet-app>

The portlet.xml descriptor

<deployments>
   ...
   <deployment>
      <instance>
         <instance-id>FSContentDrivenPortletInstance</instance-id>
         <portlet-ref>FSContentDrivenPortlet</portlet-ref>
      </instance>
   </deployment>
   ...
</deployments

The portlet-instances.xml descriptor

<web-app>
   ...
   <context-param>
      <param-name>org.jboss.portal.content_type</param-name>
      <param-value>filesystem</param-value>
   </context-param>
   <context-param>
      <param-name>org.jboss.portal.portlet_instance</param-name>
      <param-value>FSContentDrivenPortletInstance</param-value>
   </context-param>
   <listener>
      <listener-class>org.jboss.content.ContentTypeRegistration</listener-class>
   </listener>
   ...
</web-app>

The web.xml descriptor

A portal node event is fired when an event of interest happens to a portal node of the portal tree. The notification model is comparable to the bubbling propagation model defined by the DOM specification. When an event is fired, the event is propagated in the hierarchy from the most inner node where the event happens to the root node of the tree.

The portal node event propagation model

The org.jboss.portal.api.node.event.PortalNodeEventListener interface should be used instead of the too generic org.jboss.portal.api.event.PortalEventListener when it comes down of listening portal node events. Actually it does not replace it, the PortalEventListener interface semantic allows only traditional event delivering. The PortalNodeEventListener interface is designed to match the bubbling effect during an event delivery.

The PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event) method declares a PortalNodeEvent as return type. Commonly the method returns null; however, a returned PortalNodeEvent replaces the event in the listeners subsequently called during the event bubbling process.

The PortalNodeEventContext interface

The org.jboss.portal.api.node.event.PortalNodeEventContext interface extends the PortalEventContext interface and plays an important role in the event delivery model explained in the previous section. That interface gives full control over the delivery of the event to ascendant nodes in the hierarchy, even more it gives the possibility to replace the current event being delivered by a new event that will be transformed into the corresponding portal behavior. However there are no guarantees that the portal will turn the returned event into a portal behavior, here the portal provides a best effort policy, indeed sometime it is not possible to achieve the substitution of one event by another.

Here the simplest implementation of a listener that does nothing except than correctly passing the control to a parent event listener if there is one.

public PortalNodeEvent onEvent(PortalNodeEventContext context, PortalNodeEvent event)
{
   return context.dispatch();
}

The method PortalNode getNode() returns the current node being selected during the event bubbler dispatching mechanism.

As of Portal 2.6, a configuration portlet is provided to configure access to remote WSRP Producers grahically. You can access it at http://{hostname}:{port}/portal/auth/portal/admin/WSRP or by logging in as a Portal administrator and clicking on the WSRP tab in the Admin portal. If all went well, you should see something similar to this:

This screen presents all the configured producers associated with their status and possible actions on them. A Consumer can be active or inactive. Activating a Consumer means that it is ready to act as a portlet provider. Deactivating it will remove it from the list of available portlet providers. Note also that a Consumer can be marked as requiring refresh meaning that the information held about it might not be up to date and refreshing it from the remote Producer might be a good idea. This can happen for several reasons: the service description for that remote Producer has not been fetched yet, the cached version has expired or modifications have been made to the configuration that could potentially invalidate it, thus requiring re-validation of the information.

Next, we create a new Consumer which we will callbea. Type "bea" in the "Create a consumer named:" field then click on "Create consumer":

You should now see a form allowing you to enter/modify the information about the Consumer. Set the cache expiration value to 300 seconds and enter the WSDL URL for the producer in the text field and press the "Refresh & Save" button:

This will retrieve the service description associated with the Producer which WSRP is described by the WSDL file found at the URL you just entered. In our case, querying the service description will allow us to learn that the Producer requires registration and that it expects a value for the registration property named registration/consumerRole:

Enter "public" as the value for the registration property and press "Save & Refresh" once more. You should now see something similar to:

The Consumer for the bea Producer should now be available as a portlet provider and is ready to be used.

A producer is configured, by default, by retrieving the producer's information via a WSDL URL. There are rare cases, however, where URLs need to be provided for each of the producer's end points. You can do exactly that by unchecking the "Use WSDL?" checkbox, as is the case for the self producer:

We will create a public-bea-wsrp.xml descriptor. Note that the actual name does not matter as long as it ends with -wsrp.xml:

<?xml version='1.0' encoding='UTF-8' ?>
<!DOCTYPE deployments PUBLIC "-//JBoss Portal//DTD WSRP Remote Producer Configuration 2.6//EN"
   "http://www.jboss.org/portal/dtd/jboss-wsrp-consumer_2_6.dtd">
<deployments>
  <deployment>
    <wsrp-producer id="bea" expiration-cache="300">
      <endpoint-wsdl-url>http://wsrp.bea.com:7001/producer/producer?WSDL</endpoint-wsdl-url>
      <registration-data>
        <property>
          <name>registration/consumerRole</name>
          <lang>en</lang>
          <value>public</value>
        </property>
      </registration-data>
    </wsrp-producer>
  </deployment>
</deployments>

This producer descriptor gives access to BEA's public WSRP producer. We will look at the details of the different elements later. Note for now the producer-id element with a "bea" value. Put this file in the deploy directory and start the server (with JBoss Portal and its WSRP service deployed).

Let's now look at the Admin page and the Management portlet. Click on the "Portlet definitions" tab at the top. Once this is done, look at the list of available portlet providers. If all went well, you should see something similar to this:

We have 3 available portlet providers: local, self andbea. The local portlet provider exposes all the portlets deployed in this particular instance of Portal. As explained above, the self provider refers to the default WSRP consumer bundled with Portal that consumes the portlets exposed by the default WSRP producer. The bea provider corresponds to BEA's public producer we just configured. Select it and click on "View portlets". You should now see something similar to:

From there on out, you should be able to configure WSRP portlets just as any other. In particular, you can create an instance of one of the remote portlets offered by BEA's public producer just like you would create an instance of a local portlet and then assign it to a window in a page. If you go to that page, you should see something similar to below for this portlet:

Let's now look at which information needs to be provided to configure access to a remote producer.

First, we need to provide an identifier for the producer we are configuring so that we can refer to it afterwards. This is accomplished via the mandatory id attribute of the <wsrp-producer> element.

JBoss Portal also needs to learn about the remote producer's endpoints to be able to connect to the remote web services and perform WSRP invocations. Two options are currently supported to provide this information:

Both the id attribute and either <endpoint-config> or <endpoint-wsdl-url> elements are required for a functional remote producer configuration.

It is also possible to provide addtional configuration, which, in some cases, might be important to establish a proper connection to the remote producer.

One such optional configuration concerns caching. To prevent useless roundtrips between the local consumer and the remote producer, it is possible to cache some of the information sent by the producer (such as the list of offered portlets) for a given duration. The rate at which the information is refreshed is defined by the expiration-cache attribute of the <wsrp-producer> element which specifies the refreshing period in seconds. For example, providing a value of 120 for expiration-cache means that the producer information will not be refreshed for 2 minutes after it has been somehow accessed. If no value is provided, JBoss Portal will always access the remote producer regardless of whether the remote information has changed or not. Since, in most instances, the information provided by the producer does not change often, we recommend that you use this caching facility to minimize bandwidth usage.

Additionally, some producers require consumers to register with them before authorizing them to access their offered portlets. If you know that information beforehand, you can provide the required registration information in the producer configuration so that the Portal consumer can register with the remote producer when required.

Registration configuration is done via the <registration-data> element. Since JBoss Portal can generate the mandatory information for you, if the remote producer does not require any registration properties, you only need to provide an empty <registration-data> element. Values for the registration properties required by the remote producer can be provided via <property> elements. See the example below for more details. Additionally, you can override the default consumer name automatically provided by JBoss Portal via the <consumer-name> element. If you choose to provide a consumer name, please remember that this should uniquely identify your consumer.