JBoss Portal 2.4

The binary download is available from our download page .

Once downloaded and extracted, the folder hierarchy should look like this:

We will be using files contained in this download in the further sections, so please download and extract it first.

Of course you will need to install JBoss Application Server prior to installing JBoss portal, if you didn't do so yet, please install JBoss 4.0.4+ from here .

You will need a database for JBoss Portal to function, you can use any database supported by Hibernate.

The JBoss Portal download you extracted in Section 2.2.1.1, “Getting the Binary” contains pre-configured datasource descriptors, you can use for most popular RDBMS under the setup directory.

At this point, you should configure the one that suits you best with your Database and JDBC driver.

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

Please verify that the username, password, url, and driver-class are correct for your flavor of DB. You can deploy the datasource file by itself to test, in advance.

Of course you will need to install JBoss Application Server prior to installing JBoss portal, if you didn't do so yet, please install JBoss 4.0.4+ from here .

For the build targets to work, you must first set the JBOSS_HOME environment variable in your operating system, to the root directory of the JBoss Application Server installation.

In Windows, this is accomplished by going to Start > Settings > Control Panel > System > Advanced > Environment Variables . Now under the System Variables section, click New . You will be setting the JBOSS_HOME environment variable to the location of your JBoss Application Server installation:

On a Unix-like Operating System, you would accomplish this by typing:

export JBOSS_HOME=/path/to/your/jboss/directory

You will need a database for JBoss Portal to function, you can use any database supported by Hibernate.

You will need a valid datasource descriptor, for JBoss Portal to communicate with your database. Having obtained the sources and having set your JBOSS_HOME environment variable ( Section 2.3.2.2, “Operating System Environment Setting” ), you can now have the JBoss Portal build system generate preconfigured datasources for you.

Navigate to JBOSS_PORTAL_HOME_DIRECTORY/core and type:

build datasource

Once complete, the datasource build should produce the following directory and file structure:

At this point, you should configure the one that suits you best with your Database and JDBC driver.

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

Please verify that the username, password, url, and driver-class are correct for your flavor of DB.

Now copy your datasource descriptor to JBOSS_HOME/server/default/deploy

You can find a prepared binary at:

You can obtain portal sources from either:

Using the second method you will always have all latest updates from portal 2.4 cvs branch

After downloading the sources you need to build the Migration Application. Before you start be sure you have JBOSS_HOME environment variable set pointing to JBoss Application Server directory. Migration Application archive can be build using following commands:

               
                  cd jboss-portal-2.4
                  cd build
                  ./build.sh
                  cd ..
                  cd migration
                  ./build.sh
               
            

Deployable web application archive can be found at jboss-portal-2.4/migration/output/lib/portal-migration.war

You can also deploy it automatically by executing:

               
                  cd jboss-portal-2.4
                  cd migration
                  ./build.sh deploy
               
            

This section will introduce the reader to deploying his first portlet in JBoss Portal. It requires you download the HelloWorldPortlet from PortletSwap.com, using this link .

Portlets are packaged in war files, just like other JEE applications. A typical portlet war file can also include servlets, resource bundles, images, html, jsps, and other static or dynamic files you would commonly include.

Included in the download bundle you should have one java source file: HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldPortlet.java , and it should contain the following:

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

Now lets dissect our simplest of portlets:

JBoss Portal requires certain descriptors be included in your portlet war, for different reasons. Some of these descriptors are defined by the Portlet Specification, and some are specific to JBoss Portal.

Now lets explain what each of these does:

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

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 src files and produce a helloworldportlet.war 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 the helloworldportlet.war, and allow you to deploy it as an expanded directory. It will work just the same, with some additional benefits noted below:

The advantage to expanded war deployments is that you can modify xml descriptors, resource files jsp/jsf pages easily during development. Simply touch the web.xml to have JBoss Application Server hot-deploy the web appllication on a live-running server instance

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

18:25:56,366 INFO  [Server] JBoss (MX MicroKernel) [4.0.3SP1 (build: CVSTag=JBoss_4_0_3_SP1 date=200510231054)] 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:

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.

Portlets are packaged in war files, just like other JEE applications. A typical portlet war file can also include servlets, resource bundles, images, html, jsps, and other static or dynamic files you would commonly include.

Included in the download bundle you should have one java source file: HelloWorldPortlet\src\main\org\jboss\portlet\hello\HelloWorldJSPPortlet.java , and it should contain 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 lets look at some of our methods:

JBoss Portal requires certain descriptors be included in your portlet war, for different reasons. Some of these descriptors are defined by the Portlet Specification, and some are specific to JBoss Portal. For brevity, we only discuss the portlet.xml descriptor here. For discussion on the other descriptors, please view Section 5.2.1.4, “The Application Descriptors” or the chapter on descriptors: Section 6.1, “Portlet Descriptors” .