Working with Portlet Overlays

Many Jasig portlets are packaged as completely separate projects from uPortal. This packaging allows adopters to mix and match portlet versions, as well as ensures that we have clean separation and strong adherence to portlet APIs. Portlets distributed as separate projects may be included in the uPortal build via a maven overlay. This strategy ensures that even though you may be working with multiple Jasig projects, you can have one source code base capable of configuring and building all those projects, leading to more repeatable builds.

A maven overlay is a strategy for including a separately packaged project, potentially replacing certain files along the way. For example, we might want to update the project to use a particular database driver or modify a Spring configuration file. These overlay files can additionally make use of maven filtering to pick up information such as database or CAS configuration parameters from the main uPortal filter files.

More background information:

Maven Overlays: http://maven.apache.org/plugins/maven-war-plugin/overlays.html
Maven Filtering: http://maven.apache.org/plugins/maven-resources-plugin/examples/filter.html
uPortal Filter Configuration: Building and Deploying uPortal

Adding a New Portlet Overlay

Step 1: Define the portlet version property

Open the main (top-level) uPortal pom.xml file and add a new property representing the version for your new portlet. This property is often named something like PortletName.version. The value should be equal to the version of the external portlet project you'd like to add to uPortal.

pom.xml

<properties>
   . . .
   <CalendarPortlet.version>2.1.0-RC1</CalendarPortlet.version>
   . . .
</properties>

Step 2: Add a new submodule to uportal-portlets-overlay

Add a new directory to uportal-portlets-overlay to represent your included portlet. This directory name is often the same as the artifact ID of the portlet. For our example, we will use the directory name "CalendarPortlet". Once the directory is created, create a new file named pom.xml at the root of the directory. This pom file should have a parent groupId and version equal to the groupId and version of the uportal-portlets-overlay directory for the portal you're building in. It's often easiest to set the artifactId for the new submodule to the same value as the portlet you're including.

In this example, we're including the Calendar Portlet in uPortal 4.0.4.

Portlet Overlay pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">


    <parent>
        <groupId>org.jasig.portal.portlets-overlay</groupId>
        <artifactId>uportal-portlets-overlay</artifactId>
        <version>4.0.4</version>
    </parent>

    <modelVersion>4.0.0</modelVersion>
    <artifactId>CalendarPortlet</artifactId>
    <packaging>war</packaging>
    <name>Calendar Portlet</name>
    <description>Overlay on Calendar Portlet.</description>
    <dependencies>


        <!-- Distributed portlet artifact -->
        <dependency>
            <groupId>org.jasig.portlet</groupId>
            <artifactId>CalendarPortlet</artifactId>
            <version>${CalendarPortlet.version}</version>
            <type>war</type>
        </dependency>


        <!-- Configured uPortal database driver -->        
        <dependency>
            <groupId>${jdbc.groupId}</groupId>
            <artifactId>${jdbc.artifactId}</artifactId>
            <version>${jdbc.version}</version>
            <scope>compile</scope>
        </dependency>

    </dependencies>
    <build>
        <filters>
            <!-- uPortal filter file -->
            <filter>../../${filters.file}</filter>
        </filters>
        <resources>
            <!-- Filter any overlaid resource files -->
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                    <!-- Exclude the default portlet project database driver -->
                    <dependentWarExcludes>
                        WEB-INF/lib/hsqldb-*.jar
                    </dependentWarExcludes>
 
                    <!-- Filter overlaid web resources -->
                    <!--webResources>
                        <resource>
                            <directory>${basedir}/src/main/webapp</directory>
                            <includes>
                                <include>WEB-INF/context/exampleFile.xml</include>
                            </includes>
                            <filtering>true</filtering>
                        </resource>
                    </webResources-->
                </configuration>
            </plugin>
           <plugin>
                <groupId>org.apache.portals.pluto</groupId>
                <artifactId>maven-pluto-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Using the example above, your resulting maven overlay structure will resemble the following:

uPortal Root Directory
- uportal-portlets-overlay
  - CalendarPortlet
    - pom.xml

2. Now, include CalendarPortlet in the module list under uportal-portlets-overlay/pom.xml

uportal-portlets-overlay/pom.xml

....
 
 <name>uPortal Portlets</name>
    <description>Parent package for portlets deployed with uPortal.</description>
    <modules>
        <module>BookmarksPortlet</module>
        <module>CalendarPortlet</module>
        <module>cas</module>
        <module>cas-proxy-test-portlet</module>
        <module>email-preview</module>
        <module>FunctionalTestsPortlet</module>
        <module>jasig-widget-portlets</module>
        <module>pluto-testsuite</module>
        <module>NewsReaderPortlet</module>
        <module>SimpleContentPortlet</module>
        <module>WeatherPortlet</module>
        <module>WebProxyPortlet</module>
    </modules>
    <build>

....

Step 3: Add the portlet to uportal-ear/pom.xml

Now we need to include the new portlet overlay in uPortal's overall build. uPortal packages the entire portal as an ear file, which is a collection of webapps and shared libraries to later be deployed to Tomcat. Adding the overlay artifact we created above will make our new portlet part of the overall build artifact and ensure that it is automatically deployed each time we run "ant deploy-ear". To add the new portlet, first add the artifact as a dependency to the uportal-ear/pom.xml file. Here we're adding the overlay as a dependency, not the original portlet, so the dependency information will be specific to this version of uPortal and the overlay group. We also need to add a matching webModule entry to the build section in the same file.

uportal-ear/pom.xml

    <dependencies>
        . . .
        <dependency>
            <groupId>org.jasig.portal.portlets-overlay</groupId>
            <artifactId>CalendarPortlet</artifactId>
            <version>${project.version}</version>
            <type>war</type>
        </dependency>
        . . .
    </dependencies>
 
    <build>
        <finalName>${uportal.docbase}</finalName>
        <plugins>
            <plugin>
                <artifactId>maven-deploy-plugin</artifactId>
                <configuration>
                    <skip>true</skip>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-ear-plugin</artifactId>
                <configuration>
                    <modules>
                        . . . 
                        <webModule>
                            <groupId>org.jasig.portal.portlets-overlay</groupId>
                            <artifactId>CalendarPortlet</artifactId>
                            <bundleFileName>CalendarPortlet.war</bundleFileName>
                            <contextRoot>/CalendarPortlet</contextRoot>
                        </webModule> 
                        . . . 
                    </modules>
                </configuration>
            </plugin>
        </plugins>
    </build>

Step 4: Build and Deploy

Use the following command to deploy all portlet overlays and test your new build:

ant clean deploy-ear

Having problems with these instructions?

Please send us feedback at uportal-user@lists.ja-sig.org