Maven: Jive Maven archetypes

This document describes in detail the Jive SBS Maven archetypes, covering both their structure and build processes.

Version: 4.0.x-SNAPSHOT

The 4.0.x-SNAPSHOT version of the SBS Maven archetypes includes two separate archetypes:

maven-sbs-archetype: Intended for WAR overlay projects.
maven-sbs-plugin-archetype: For use with SBS plugin projects.

Each archetype can be used independently of the other. However, plugin projects are generally created within the context of a WAR overlay project. The following sections describe each archetype in detail.

maven-sbs-archetype The WAR overlay archetype is generally used in a Jive SBS customized implementation when plugins will not suffice. The general idea is that changes within this project are compressed into a WAR, along with the core SBS code, to create a custom SBS instance. While a plugin is the preferred method of customizing your SBS instance, in extreme cases, an overlay is acceptable.
maven-sbs-plugin-archetype The plugin archetype provides a template for SBS plugin projects and is the preferred method for customizing an SBS instance.

Maven: Building actions

maven-sbs-archetype structure

In addition to the standard Maven src folder, the archetype contains a single sub-project, web. The root project's structure contains mainly test resources that allow the local instance to run properly, while the web project houses the customized pieces of the project.

Project Structure

src/test/resources/jiveHome

This is the jiveHome directory that is used by default by the overlay instance. When the project is built at the root level, the jiveHome directory is copied directly to the root target folder, replacing whatever was there before. It is generally best not to do builds from the root level after the initial build, instead opting for individual sub-project levels. The initial contents of the folder consist only of:

jive_startup.xml: Contains server startup settings, such as database and log info. The initial database name listed is directly affected by the name of the project being generated with the archetype.
jive.license: A standard development license. Non-expiring, including all optional modules (except Insights), and limited to 15 users.

web/src/main/etc

Commonly referred to as the ETC Escape Hatch, the etc folder is where any Spring XML files are placed. Jive SBS loads these XML files last when initializing the Spring application context, allowing developers to override or define new Spring beans as needed. When the web project is built, this directory's contents are copied to the root target/jiveHome/etc. Although only one file, spring-etc.xml, is included by default, multiple Spring XML files can be included in this directory as needed.

web/src/main/java

This is where custom Java classes reside. The package structure is up to the developer, reflecting the current project. If an overlay of a core SBS class is needed, the developer must create the exact package structure where the class to be overlaid lives and copy the core Java class for modification. During the build, the core Jive SBS WAR file is exploded, and the contents of the web/src/main/java folder are copied to the exploded WAR's WEB-INF/classes directory, which takes precedence over any classes defined in JAR files in the WAR's lib directory. A placeholder class, App.java, is included by default but can be deleted when development begins.

web/src/main/keys

Any public/private encryption key certificates needed by the customization should be placed here. At build time, the contents of this folder are copied to the root target/jiveHome/keys directory to be available to the development instance.

web/src/main/overlay

Certain overlaid resources cannot just be placed within the WAR's WEB-INF/classes directory for customization to take effect. Items like Javascript files and Widget properties files must replace the original artifacts in the SBS JAR file and be placed back into the WAR. By default, this is disabled in the web pom.xml due to performance reasons but can be enabled by uncommenting the package-sbs-plugin execution element in the maven-antrun-plugin section of the pom.

web/src/main/overlay/beans

Overlaid widget properties files are placed here, typically when adding, removing, or modifying the configurable properties available within a core SBS widget.

web/src/main/overlay/resources/scripts

Any overlaid Javascript resources live here. In previous versions of the archetype, overlaid Javascript files had to include a compressed version, but this processing is now done automatically by the build.

web/src/main/resources-filtered

The contents of this folder are filtered at build time, and parameterized sections of the files contained within are populated with values, such as build number and project name. The version.properties file is accessed by the web/src/main/webapp/customer_version.jsp to provide info about the build number for a deployed instance.

web/src/main/themes

This is where custom themes are stored. The provided theme.xml file is initially populated with a theme name reflecting the project's name. This file should be copied to the theme's main folder (web/src/main/theme/mytheme) to be visible to the app.

web/src/main/webapp

The webapp folder contains artifacts that are to be placed within the exploded WAR file directory. The archetype provides customer_version.jsp and a WEB-INF folder to house WAR customizations.

web/src/main/webapp/WEB-INF/classes

This location contains a series of files intended to provide custom configuration to an SBS overlay instance:

jive_custom_i18n_en.properties: Override existing resource bundle values and add new mappings here. This file is created by default; for other languages, the developer needs to create appropriate variations (e.g., jive_custom_i18n_es.properties).
struts-community-custom.xml: Override core Struts actions and add new actions here.
ui-components-custom.xml: Manage additions and deletions of certain UI components.
upgrade-custom.xml: Define custom upgrade tasks here.

web/src/main/webapp/WEB-INF/classes/template

Add custom FreeMarker templates here. For changes related to look and feel, use themes. Changes requiring existence outside a theme's context, such as major page structure modifications, should go here, maintaining the same directory structure as the FTL being overlaid. Overlaid FreeMarker templates here take precedence over any matching files within the core WAR file.

maven-sbs-archetype build

The build behavior is outlined within the web/pom.xml file, which defines several POM sections. The following sections summarize key elements.

POM Overview

<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">
    <name>weboverlay</name>
    <modelVersion>4.0.0</modelVersion>
    <groupId>${groupId}</groupId>
    <artifactId>web</artifactId>
    <packaging>war</packaging>
    <version>${version}</version>
    <description>
       Custom Jive SBS war. We try to only place files in this project that MUST be overlayed.
       Usually this means there is no way to make the change as a plugin. Most customizations can be done by plugin these days, and there
       are many advantages to doing so in terms of packaging, deployment, upgradability, and debugging.
       Overlaying a file ensures that you will have to put forth at least some development effort when you want to upgrade versions
       of Jive SBS.
    </description>
    <parent>
        <groupId>${groupId}</groupId>
        <artifactId>${artifactId}</artifactId>
        <version>${version}</version>
        <relativePath>../pom.xml</relativePath>
    </parent>

Build Configuration

The build section specifies the name of the generated WAR file and includes resource filtering:

<build>
    <finalName>
        ${customer}-${customer}-sbs-${sbs}
    </finalName>
    <resources>
        <resource>
            <directory>\${basedir}/src/main/resources-filtered</directory>
            <filtering>true</filtering>
        </resource>
    </resources>
</build>

Plugins Configuration

The maven-compiler-plugin is set up to compile with JDK 6, while the maven-surefire-plugin is configured to exclude any Selenium tests:

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
            <source>1.6</source>
            <target>1.6</target>
        </configuration>
     </plugin>
    <plugin>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
            <excludes>
                <exclude>**/selenium/*Test.java</exclude>
            </excludes>
        </configuration>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.0</version>
        <configuration>
            <workingDirectory>\${basedir}/target/tmp</workingDirectory>
        </configuration>
    </plugin>
</plugins>

maven-sbs-archetype profiles

Profiles allow for different configurations to be used during a build by specifying the profile at runtime. The overlay project uses two default profiles:

[int](/jive_integrations/developing_plugins_and_extensions/BuildingWidgets#writing-properties-files): Integration-testing profile for running all the integration tests.
[dev](/user_tools/using_jive_with_development_tools/MavenDebugging#step-1-set-up-your-ide): Similar to the int profile but with adjustments for a more conducive development environment.

Profile: `int`

The int profile includes the following plugins:

cargo-maven2-plugin: Allows deployment to Tomcat for integration testing.
selenium-maven-plugin: Runs the Selenium integration test suite.
maven-surefire-plugin: Configured to run only Selenium integration tests.

Running Commands

Several commands can be used with Cargo for integration testing:

Command	Comments
`mvn -P int integration-test`	Runs the integration tests inside Cargo.
`mvn -Dcargo.wait=true -P int integration-test`	Runs the app within Cargo while waiting for user input.
`mvn -Dcargo.wait=true -P int cargo:start`	Deploys the existing custom WAR to the Tomcat instance and waits for user input.

Profile: `dev`

The dev profile provides for running the customized SBS instance locally but focuses on development rather than integration testing. It utilizes:

cargo-maven2-plugin
javarebel-maven-plugin (commented out by default due to licensing requirements, allows for hot-deployment).

This profile tweaks system properties for development convenience.

This merged content encompasses all relevant information from both sources without adding new material, combining unique content into a logical structure and ensuring clarity and coherence throughout the document.

Version: 4.0.x-SNAPSHOT​

maven-sbs-archetype structure​

src/test/resources/jiveHome​

web/src/main/etc​

web/src/main/java​

web/src/main/keys​

web/src/main/overlay​

web/src/main/overlay/beans​

web/src/main/overlay/resources/scripts​

web/src/main/resources-filtered​

web/src/main/themes​

web/src/main/webapp​

web/src/main/webapp/WEB-INF/classes​

web/src/main/webapp/WEB-INF/classes/template​

maven-sbs-archetype build​

POM Overview​

Build Configuration​

Plugins Configuration​

maven-sbs-archetype profiles​

Profile: int​

Running Commands​

Profile: dev​