Standard layout of Jetspeed Portal Maven projects

A typical custom Jetspeed Portal project usually contains a module (sub project) for building and configuring the custom Jetspeed Portal itself as well as one or more modules for portlet application(s) to be deployed to the Jetspeed Portal.

The following standard project layout is provided as best practice and in line with standard Maven project guidelines. It is also easily expandable and customizable to incorporate future changes to the project goals and requirements.

The Jetspeed Archetype Maven Plugin can be used as a quickstart to setting up a new custom Jetspeed Portal project and will create a project structure using this standard layout. Furthermore, it will contain a typical and default setup and configuration for the Jetspeed Maven Plugins for automating common Portal deployment and integration tasks using Maven itself.

The master project

To support central management and configuration of all or most of the individual (Maven) project artifacts and (Jetspeed) integration tasks, a master/root Maven project pom.xml is used of type <packaging>pom</packaging>.

This root project will contain one or more modules (sub projects), which will have this root project defined as their parent project. This way, all artifacts will be buildable and installable directly from the root project, and (Jetspeed) integration tasks can be executed from anywhere within this project structure using the jetspeed:mvn plugin.

In addition to the "standard" pom.xml project file(s), one or more custom jetspeed-mvn-${target name}-pom.xml project files can be defined, as well as corresponding jetspeed-mvn[...].properties files and even a custom override of the Maven user settings.xml with a jetspeed-mvn-settings.xml file.

The custom jetspeed-mvn[...].properties and custom jetspeed-mvn-settings.xml files will serve as default and fallback configuration automatically looked up through the project parent chain if a sub project doesn't provide these by itself when executing a jetspeed:mvn invoked target task against a sub project.

The portal sub project module

For building and configuring the custom Jetspeed portal itself, as well as configuring and running Jetspeed Portal specific integration tasks, the root project contains a "portal" subproject module. As a Jetspeed Portal is "just" a web application, <packaging>war</packaging> is used for its pom.xml.

For building the custom Jetspeed Portal war artifact, the war overlay mechanism is used in the pom.xml, using the Jetspeed-2 provided org.apache.portals.jetspeed-2:jetspeed:war artifact as overlay. Note: this jetspeed war only contains the default (demo) Jetspeed Portal web application resources.

For pulling in the required portal application jar dependencies (to be put under its WEB-INF/lib) folder, the pom.xml contains a dependency on the org.apache.portals.jetspeed-2:jetspeed-dependencies:pom artifact.

The advantage of separating the dependencies from the default jetspeed application war is that the jetspeed-dependencies dependency itself can be further restricted or overridden within the pom. This wouldn't be possible (using standard Maven configuration) when these dependencies were incorporated in the default jetspeed war.

Portlet Application sub project module(s)

For building additional portlet applications to be deployed on the custom Jetspeed Portal, one or more additional "portlet application" subproject modules can be added to the root project (note: a common abbriviation for "portlet application" is "pa"). As a pa also is "just" a web application, again <packaging>war</packaging> is used for their pom.xml.

And, like with the portal module, a pa module can contain, in addition to the "standard" pom.xml, one or more custom jetspeed-mvn-${target name}-pom.xml project files, as well as corresponding jetspeed-mvn[...].properties or even a custom override of the Maven user settings.xml with a (module specific) jetspeed-settings.xml file.

For a portlet application module, this really is optional and often not needed, as typically just the pa war file needs to be deployed.

A common use-case where additional integration tasks might be needed however is when the pa defines and uses a custom database back-end (or likewise: ldap, JCR etc.) which needs to be setup/created/upgraded or whatever. If an appropriate Maven plugin is available for performing such an integration task (e.g. like the jetspeed-db:init plugin), standardizing and automating the execution of such tasks using the jetspeed:mvn plugin should be very easy.

Conceptable project layout and contents

Using the above specification a conceptable custom Jetspeed Portal layout and its contents will look like the following:

/my-portal-project
  | pom.xml                                                  // standard maven root pom for the my-portal project
  | jetspeed-mvn.settings.xml                                // project scoped maven settings configuration used for jetspeed:mvn target execution
  | jetspeed-mvn-<target name>-pom.xml                       // custom pom providing the "build" tasks for a global/generic jetspeed:mvn target(s)
  | jetspeed-mvn.properties                                  // default                         properties for jetspeed:mvn target execution
  | jetspeed-mvn-${target name}.properties                   // default ${target name} specific properties for jetspeed:mvn target execution
  | jetspeed-mvn-${target name}-${target id}.properties      // default ${target id}   specific properties for jetspeed:mvn target execution
  + /my-portal
      | pom.xml                                              // standard maven my-portal war pom using a war overlay mechanism 
      | jetspeed-mvn.settings.xml                            // my-portal scoped maven settings configuration used for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-pom.xml                  // custom pom providing the "build" tasks for my-portal specific jetspeed:mvn target(s)
      | jetspeed-mvn.properties                              // my-portal specific                    properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}.properties               // my-portal and ${target name} specific properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-${target id}.properties  // my-portal and ${target id}   specific properties for jetspeed:mvn target execution
  + /my-pa1
      | pom.xml                                              // standard maven my-pa1 war pom
      | jetspeed-mvn.settings.xml                            // my-pa1 scoped maven settings configuration used for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-pom.xml                  // custom pom providing the "build" tasks for my-pa1 specific jetspeed:mvn target(s)
      | jetspeed-mvn.properties                              // my-pa1 specific                    properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}.properties               // my-pa1 and ${target name} specific properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-${target id}.properties  // my-pa1 and ${target id}   specific properties for jetspeed:mvn target execution              
  + /my-pa2
      | pom.xml                                              // standard maven my-pa2 war pom
      | jetspeed-mvn.settings.xml                            // my-pa2 scoped maven settings configuration used for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-pom.xml                  // custom pom providing the "build" tasks for my-pa2 specific jetspeed:mvn target(s)
      | jetspeed-mvn.properties                              // my-pa2 specific                    properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}.properties               // my-pa2 and ${target name} specific properties for jetspeed:mvn target execution
      | jetspeed-mvn-${target name}-${target id}.properties  // my-pa2 and ${target id}   specific properties for jetspeed:mvn target execution              
      

Typical project layout and contents

In practice not all of the above possible layout structure and files will be needed.

A typical custom Jetspeed Portal project is much simpler and can look like the following:

/my-portal-project
  | pom.xml                                // standard maven root pom for the my-portal project
  | jetspeed-mvn.settings.xml              // project only maven settings configuration used for jetspeed:mvn target execution
  | jetspeed-mvn-prod.settings.xml.sample  // optional project only maven production settings *sample* configuration to be used for jetspeed:mvn target execution:
                                           //   typically, production settings contain security sensitive parameters which should not be
                                           //   committed to a version control system and a concrete jetspeed-mvn-prod.settings.xml would
                                           //   not be allowed to be committed.
                                           //   the sample configuration then just provides a template to be copied to jetspeed-mvn-settings.xml
                                           //   and further configured by the developer/deployer locally. 
  | jetspeed-mvn.properties                // optional (default) properties used for jetspeed:mvn target execution
  + /my-portal
      | pom.xml                            // standard maven my-portal war pom using war overlay mechanism 
      | jetspeed-mvn-portal-pom.xml        // custom pom providing all the "build" tasks for my-portal specific jetspeed:mvn targets, like using jetspeed-db and jetspeed-deploy plugins
  + /my-pa
      | pom.xml                            // standard maven my-pa war pom
      | jetspeed-mvn-pa-pom.xml            // Custom pom providing the all the "build" tasks for my-pa specific jetspeed:mvn target(s), like using jetspeed-deploy plugin
      

The above example project layout is what the Jetspeed Archetype Maven plugin (partly) generates, where the "my-" prefix and the maven artifact coordinates (groupId,artifactId,version) are configurable.