How-to for Building a Custom Portal with Maven-2 and Jetspeed 2.1.x

Custom Portal Generation

The Maven1 j2:portal.genapp goal has been supported in the Maven2 build as an archetype. However, until a Jetspeed2 Maven2 repository is completely populated, a normal Maven2 build must be completed to make Jetspeed2 archetypes available in your local repository. One can tweak the following command as needed to create a Jetspeed2 instance using this archetype:

mvn archetype:create -DarchetypeGroupId=org.apache.portals.jetspeed-2 -DarchetypeArtifactId=portal-archetype -DarchetypeVersion=2.1.3 -DgroupId=myportalgroup -DartifactId=myportal -Dversion=1.0

Custom Portal Directory Structure Conventions

Note that this and other archetypes can issue many harmless warnings while expanding. Please ignore the warnings unless the expansion of the archetype template fails. When complete, the portal archetype expansion will contain the following structure within a directory named as the specified artifactId relative to the current working directory:

  • <artifactId>/applications - conventional subdirectory for portal application war modules.
  • <artifactId>/app-servers - contains portal deployment builds and resources.
  • <artifactId>/components - conventional subdirectory for portal component jar modules.
  • <artifactId>/etc/assembly - custom portal application component Spring assemblies.
  • <artifactId>/etc/conf - portal application context configuration files.
  • <artifactId>/etc/decorations - custom decorations in images, layout, and portlet subdirectories.
  • <artifactId>/etc/pages - custom portal PSML pages to augment/override minimal defaults, (e.g. /Administrative/**, /default-page.psml, /myaccount.psml, /page.security, and /system/**).
  • <artifactId>/etc/schema - Jetspeed2 database schema definitions.
  • <artifactId>/etc/sql - Jetspeed2 base database configuration scripts.
  • <artifactId>/etc/templates - custom overrides for Jetspeed2 layout portlet templates.
  • <artifactId>/etc/webapp - custom content reaources to be packaged with portal application.
  • <artifactId>/portal - portal application war build scripts and webapp resource overrides.
  • <artifactId>/src - these directories are an artifact of archetype expansion and should be deleted.

Configuration

The archetype also contains a settings.xml.sample that is a subset of the Jetspeed2 source build parameters. If one has not previously configured the ~/.m2/settings.xml file as described above, this sample can be used to do so without J2 test configurations.

When the Maven2 enviroment is properly configured, the J2 Maven2 commands outlined above can now be used to build and deploy a customized portal. Most of the command options are supported with the exception of these profiles:

  • min and full are not supported because the archetype supports only the minimal deployment.
  • test features to populate the J2 test database have also been provisionally stripped from the archetype.
  • dbpsml is not yet supported in the custom portal build to import to the production database PSML.

Currently, only Maven2 builds are supported. Longer range goals include support for Ant custom portal builds and prepackaged Maven2 repository downloads.

Two additional Maven2 archetypes are also available to generate custom portal applications and components on top of the generated portal template. Before these archetypes are used, the host portal archetype should have been previously built to install all parent POMs, (it is not necessary to deploy the portal before using these archetypes). These archetypes should be created from the applications and components subdirectories to work correctly.

Archetype Commands

A portal portlets application to be deployed by Jetspeed2:

mvn archetype:create -DarchetypeGroupId=org.apache.portals.jetspeed-2 -DarchetypeArtifactId=application-archetype -DarchetypeVersion=2.1.3 -DgroupId=myportalgroup -DartifactId=myportal-application -Dversion=1.0

A simple component to be used by other component and application modules:

mvn archetype:create -DarchetypeGroupId=org.apache.portals.jetspeed-2 -DarchetypeArtifactId=component-archetype -DarchetypeVersion=2.1.3 -DgroupId=myportalgroup -DartifactId=myportal-component -Dversion=1.0

A shared component to be deployed as a shared JAR in the application server:

mvn archetype:create -DarchetypeGroupId=org.apache.portals.jetspeed-2 -DarchetypeArtifactId=shared-component-archetype -DarchetypeVersion=2.1.3 -DgroupId=myportalgroup -DartifactId=myportal-shared-component -Dversion=1.0

A component to be deployed within the portal, (Jetspeed2), web application:

mvn archetype:create -DarchetypeGroupId=org.apache.portals.jetspeed-2 -DarchetypeArtifactId=portal-component-archetype -DarchetypeVersion=2.1.3 -DgroupId=myportalgroup -DartifactId=myportal-portal-component -Dversion=1.0

Note that the groupId and version settings should match the values used when generating the host portal template.

Maven POM Configuration

There are a few manual steps that must be followed to use these created applications and components.

  • The new application/component must be added as <module> elements in the parent POM. An application would be added like this by subdirectory name, (artifactId): 
    <modules>
    ...
    <module>myportal-application</module>

    ...
</modules>

    The same syntax is used for components.

  • A dependency declaration should be added in the root POM. Components packaged as jars should be added like this: 
    <dependencyManagement>
    <dependencies>
        ...
        <dependency>

            <groupId>${pom.groupId}</groupId>
            <artifactId>myportal-component</artifactId>
            <version>${pom.version}</version>
        </dependency>

        ...
    </dependencies>
</dependencyManagement>

    Applications are declared similarly, except for the addition of a required <type> element: 

    <dependencyManagement>
    <dependencies>

        ...
        <dependency>
            <groupId>${pom.groupId}</groupId>
            <artifactId>myportal-application</artifactId>
            <type>war</type>

            <version>${pom.version}</version>
        </dependency>
        ...
    </dependencies>
</dependencyManagement>
  • These dependencies can now be used to include the applications and components into the build process. Components are added as included dependencies to other applications and components in individual POMs associated with the modules that reference the component: 
    <dependencies>
    ...
    <dependency>
        <groupId>${pom.groupId}</groupId>
        <artifactId>myportal-component</artifactId>

    </dependency>
    ...
</dependencies>

    Shared components that are intended to be deployed as a shared JAR should be declared as a provided dependency in the applications POM or individual application and component POMs, (note the additional provided <scope> element): 

    <dependencies>
    ...
    <dependency>

        <groupId>${pom.groupId}</groupId>
        <artifactId>myportal-shared-component</artifactId>
        <scope>provided</scope>
    </dependency>

    ...
</dependencies>

    Shared and portal components must also be made available for deployment and should be integrated in the app-servers module POM as a normal dependency: 

    <dependencies>
    ...
    <dependency>
        <groupId>${pom.groupId}</groupId>

        <artifactId>myportal-shared-component</artifactId>
    </dependency>
    ...
</dependencies>

    Applications are normally referenced only for deployment. To ensure they are available during deployment builds, they must be integrated in the app-servers module POM like this: 

    <dependencies>

    ...
    <dependency>
        <groupId>${pom.groupId}</groupId>
        <artifactId>myportal-application</artifactId>
        <type>war</type>

    </dependency>
    ...
</dependencies>
  • Finally, the new applications and components must be added to the app-servers deployment Ant buildfiles. Applications should be added to the 'hot' application/WAR deployment hooks in the application server specific build files, (e.g. tomcat-build.xml): 
    <target name="hot-deploy-apps">
    ...
    <antcall target="hot-deploy-war">

        <param name="org.apache.jetspeed.deploy.groupid" value="${portal.groupid}"/>
        <param name="org.apache.jetspeed.deploy.artifactid" value="myportal-application"/>
        <param name="org.apache.jetspeed.deploy.version" value="${portal.version}"/>
    </antcall>
    ...
</target>

    Shared components that are to be installed in the application server should be added to the shared deployment hook in the same buildfile: 

    <target name="hot-deploy-shared-components">
    ...
    <antcall target="hot-deploy-shared-jar">
        <param name="org.apache.jetspeed.deploy.groupid" value="${portal.groupid}"/>
        <param name="org.apache.jetspeed.deploy.artifactid" value="myportal-shared-component"/>
        <param name="org.apache.jetspeed.deploy.version" value="${portal.version}"/>

    </antcall>
    ...
</target>

    And finally, portal components that are to be inserted into the portal application itself should be added to the 'hot' component/JAR hooks like this: 

    <target name="hot-deploy-components">
    ...
    <antcall target="hot-deploy-jar">
        <param name="org.apache.jetspeed.deploy.groupid" value="${portal.groupid}"/>

        <param name="org.apache.jetspeed.deploy.artifactid" value="myportal-portal-component"/>
        <param name="org.apache.jetspeed.deploy.version" value="${portal.version}"/>
    </antcall>
    ...
</target>

Please refer to the Maven2 site documentation for more detail or background information: Maven-2 Docs