Introduction

The portlet plugin provides help with creating a portlet application file (i.e., a war file) appropriate for a particular portlet container. As such, it helps the portlet developer develop his or her portlets in such a way as to be able to target multiple portal frameworks. The currently supported frameworks are uPortal and GridSphere.

This plugin makes heavy use of the Maven war plugin and the Tomcat plugin from codeczar.com.

Getting Started

First you'll need to download the portlet plugin. Execute the following:

      maven -DartifactId=portlet-plugin -DgroupId=portlet-plugin 
        -Dmaven.repo.remote=http://www.extreme.indiana.edu/dist/java-repository,http://www.ibiblio.org/maven 
        -Dversion=0.2 plugin:download
      

Alternatively, you can add the following as a dependency to your project.xml for your maven project:

        <dependency>
            <groupId>portlet-plugin</groupId>
            <artifactId>portlet-plugin</artifactId>
            <type>plugin</type>
            <version>0.2</version>
        </dependency>
      

and add http://www.extreme.indiana.edu/dist/java-repository to your project's maven.repo.remote property.

This step is optional, but highly recommended. Get the Tomcat plugin from codeczar:

      maven -DartifactId=maven-tomcat-plugin -DgroupId=codeczar-tomcat
        -Dmaven.repo.remote=http://www.codeczar.com/maven -Dversion=1.1 plugin:download      
      

Alternatively, you can add the following as a dependency to your project.xml for your maven project:

        <dependency>
            <groupId>codeczar-tomcat</groupId>
            <artifactId>maven-tomcat-plugin</artifactId>
            <type>plugin</type>
            <version>1.1</version>
        </dependency>
      

and add http://www.codeczar.com/maven to your project's maven.repo.remote property.

To get the most use out of the Tomcat plugin, you'll need to setup your Tomcat installation so that it uses the manager application. This means creating a user account for yourself with the role of manager. See the Tomcat Manager documentation. In general it means adding a line like the following to TOMCAT_HOME/conf/tomcat-users.xml.

      <user name="USERNAME" password="PASSWORD" roles="manager" />
      

where USERNAME is your username and PASSWORD is your Tomcat manager password.

Working with uPortal

To get started working with uPortal, you'll need to set some uPortal specific properties. You'll also need to configure the Tomcat plugin with your username, password, etc. A sample build.properties file follows:

      maven.portlet.framework=uportal
      maven.portlet.uportal.home=/usr/local/uPortal_rel-2-4-2
      #maven.portlet.uportal.pubchan=${maven.conf.dir}/pubchan
      maven.tomcat.username=machrist
      maven.tomcat.password=tomcat
      maven.tomcat.host=myportal.myorg.org
      maven.tomcat.port=8080
      # the following is needed to prevent precompilation of JSPs
      # doesn't work otherwise
      maven.tomcat.precompile=false
      

The first thing needed above is to set maven.portlet.framework to uportal. You then need to give the location of where you unpacked the uPortal-only release. The last few settings tell the Tomcat plugin how to contact and authenticate with the manager application for this Tomcat instance. Now we can run:

      maven tomcat:deploy
      

This builds the war file, and modifies it so that it will work correctly in uPortal. It then deploys it to the tomcat container.

The next thing to do is to register the portlet with uPortal. This requires that we have a channel definition file in the conf/pubchan directory. See the ${maven.portlet.uportal.home}/properties/chanpub directory for examples of such files. Also, note that you can modify the default directory for the channel definition files with the maven.portlet.uportal.pubchan property. Now we can run:

      maven portlet:register
      

Note that this goal needs to be run on the same machine as where the uPortal source is installed and where the database is running, since it uses the uPortal build.xml file and contacts the uPortal database to register the portlet.

Working with GridSphere

To get started working with GridSphere, you'll need to set some GridSphere specific properties. You'll also need to configure the Tomcat plugin with your username, password, etc. A sample build.properties file follows:

      maven.portlet.framework=gridsphere
      #maven.portlet.gridsphere.webxml=${maven.war.src}/WEB-INF/web.xml.gridsphere
      maven.portlet.gridsphere.webapp=/usr/local/tomcat/gridsphere
      maven.tomcat.username=machrist
      maven.tomcat.password=tomcat
      maven.tomcat.host=myportal.myorg.org
      maven.tomcat.port=8080
      # the following is needed to prevent precompilation of JSPs
      # doesn't work otherwise
      maven.tomcat.precompile=false
      

The first thing needed above is to set maven.portlet.framework to gridsphere. You can specify where the GridSphere specific web.xml file is, or just use the default setting. Note that a GridSphere specific web.xml file will not be generated by this plugin; it must be created by hand (see the GridSphere documentation [www.gridsphere.org]). The last few settings tell the Tomcat plugin how to contact and authenticate with the manager application for this Tomcat instance. Now we can run:

      maven tomcat:deploy
      

This builds the war file, and modifies it so that it will work correctly in GridSphere. It then deploys it to the tomcat container.

The next thing to do is to register the portlet with GridSphere. This requires that we set the maven.portlet.gridsphere.webapp property to point to the GridSphere webapp directory. Now we can run:

      maven portlet:register
      

Note that this goal needs to be run on the same machine as the GridSphere tomcat is running.

NOTE Currently, the tomcat:deploy and portlet:register do not work as well as one might wish with GridSphere. You are encouraged to use GridSphere's builtin deployment and portlet application management. In this case, you can use the portlet plugin to simply create a war file using maven war and then follow GridSphere's instructions for deploying and managing portlets from within the portal.

Updating a Portlet Application

This is easy. If you have everything set up, you can simply do:

      maven tomcat:redeploy
      

It is sometimes useful to restarts the portal's web application as well (or some arbitrary web application). You can do that too. For example, the following restarts the uPortal webapp:

      maven tomcat:stop tomcat:start -Dmaven.tomcat.war.context=/uPortal
      

For uPortal this is particularly useful after registering a new portlet since uPortal has to be restarted for it to see the new portlet.