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-sbs-plugin-archetype structure

The archetype creates a single project, representing the plugin to be developed, built, and deployed.



src/main/assembly

The plugin makes use of the maven-assembly-plugin to determine how the plugin JAR is packaged.  Its configuration is contained within the assembly-plugin.xml.

src/main/java

The Java code making up the plugin goes here.  Not much else to say about it.

src/main/plugin

Artifacts contained within this folder are placed in the plugin's root directory as part of the build process.  Artifacts in this folder are filtered by the build process and can be parameterized.  Files included in this folder by default include:

  • cache-config.xml: For specifying any custom Coherence caches needed by the plugin.
  • plugin.xml: The plugin's definition, including Sitemesh configs, widgets, schema version, UI customizations, etc.
  • schema.xml:  Definition of the initial database schema to be created upon the plugin's initial installation into the system.
  • spring.xml: Definition of any Spring beans needed by the plugin.  This includes new beans defined within the plugin itself, as well as overrides for bean definitions in the core product.  The latter practice is completely legal, but a little dangerous in that it could invite problems when deployed into in an environment with multiple plugins, any of which could override the same core Spring bean, causing a collision.
  • struts.xml: Definition pf the Struts configuration and mappings needed by the plugin.  Like the spring.xml, it can contain both new and overridden items, which can cause collisions.

src/main/plugin/resources/images

Images needed by the plugin go here.

src/main/plugin/resources/script

Javascript files used by the plugin go here.

src/main/plugin/resources/styles

The plugin's cascading stylesheets go here.

src/main/plugin/resources/templates

FreeMarker templates needed by the plugin go here.

src/main/resources

Artifacts in this directory are placed in the classes directory when the project is built.  Only one file, plugin_i18n.properties, which acts as the default resource bundle for the plugin, is included here by default.

src/test/java

Unit tests go here.

maven-sbs-plugin-archetype build

The build behavior is all contained within the plugin's pom.xml file.  This section contains a walk through of the pom sections, explaining them in detail.

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~  $Revision: 96475 $
  ~  $Date: 2009-11-02 16:51:02 -0800 (Mon, 02 Nov 2009) $
  ~
  ~  Copyright (C) 1999-${YEAR} Jive Software. All rights reserved.
  ~
  ~  This software is the proprietary information of Jive Software. Use is subject to license terms.
  -->
<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">
    <!--
      These parameters were pased in via the commandline when this pom was created by the archetype.
      -->
    <modelVersion>4.0.0</modelVersion>
    <groupId>${groupId}</groupId>
    <artifactId>${artifactId}-plugin</artifactId>
    <name>${artifactId}</name>
    <version>1.0</version>
    <packaging>jar</packaging>
    <url>http://www.jivesoftware.com</url>

This is the standard Maven project definition, the parameterized values of which are populated upon creation of the plugin project.

    <build>
        <finalName>${artifactId}-plugin</finalName>
        <plugins>
         <!-- For compilation-->
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>

The finalName element defines the name of the JAR file created by the build process.

Like the web POM, the maven-compiler-plugin is set up to use JDK 6 to compile Java resources.

            <!-- Weave transactions into the plugin -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>aspectj-maven-plugin</artifactId>
                <version>1.1</version>
                <configuration>
                    <aspectLibraries>
                        <aspectLibrary>
                            <groupId>org.springframework</groupId>
                            <artifactId>spring-aspects</artifactId>
                        </aspectLibrary>
                    </aspectLibraries>
                    <source>1.6</source>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>compile</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

The aspectj-maven-plugin allows for the weaving of aspect libraries into the plugin code.  By default, the spring-aspects library is included to provide support for use of the @Transactional aspect within Java classes.

            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <executions>
                    <execution>
                        <id>assembly</id>
                        <phase>package</phase>
                        <goals><goal>single</goal></goals>
                        <configuration>
                            <appendAssemblyId>false</appendAssemblyId>
                            <descriptors>
                                <descriptor>\${basedir}/src/main/assembly/assembly-plugin.xml</descriptor>
                            </descriptors>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

The maven-assembly-plugin affects how the JAR file artifact produced by the build process is structured.  This configuration points to the assembly-plugin.xml for its directives.

            <plugin>
                <artifactId>maven-antrun-plugin</artifactId>
                <executions>
                    <execution>
                        <!-- Unpackages this SBS plugin.  That way it can be used in conjunction with the -DpluginDirs= property, which
                             bypasses the standard plugin installation (which happens via the Admin Console), by pointing to exploded plugin jar created by this. -->
                        <id>explode-sbs-plugin</id>
                        <phase>package</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <tasks>
                               <mkdir dir="\${basedir}/target/${artifactId}" />
                               <unjar src="\${basedir}/target/${artifactId}-plugin.jar" dest="\${basedir}/target/${artifactId}" />
                            </tasks>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

The maven-antrun-plugin for the plugin build process takes the resulting JAR artifact and explodes it into a directory, whose name is dictated by the plugin's name, within the plugin's target folder.  This enables the inclusion of the plugin in a local SBS instance using the pluginDirs system property, which points to the exploded JAR directory.

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <phase>verify</phase>
                        <goals>
                            <goal>jar</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

Including the maven-source-plugin creates a source jar artifact for the plugin when it's built.

         <!-- For unit testing -->
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>**/selenium/*Test.java</exclude>
                    </excludes>
                </configuration>
            </plugin>

        </plugins>
    </build>

Like in the web POM, this configuration of the maven-surefire-plugin excludes Selenium tests from being run as part of the normal build process.

    <dependencies>
        <dependency>
            <groupId>com.jivesoftware</groupId>
         <artifactId>jive-sbs-employee</artifactId>                <version>${sbs.version}</version>
            <type>jar</type>
            <scope>provided</scope>
     </dependency>
        <dependency>            <groupId>com.jivesoftware</groupId>
            <artifactId>jive-sbs-employee-all</artifactId> 
            <version>${sbs.version}</version>
            <type>pom</type>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.3</version>
            <type>jar</type>
            <scope>provided</scope>
        </dependency>
             <!-- The following dependencies are for unit testing-->
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.4</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.objenesis</groupId>
            <artifactId>objenesis</artifactId>
            <version>1.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>cglib</groupId>
            <artifactId>cglib</artifactId>
            <version>2.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.jmock</groupId>
            <artifactId>jmock-junit4</artifactId>
            <version>2.4.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

The plugin POM includes the following dependencies by default:

  • jive-sbs-employee: Needed for compilation of SBS-dependent code.
  • jive-sbs-employee-all: Provides a way to the libraries needed by SBS core code.
  • servlet-api: Needed to satisfy references to the J2EE Servlet API by plugin classes.
  • junit: JUnit 4 unit testing library
  • objenesis: Needed for use with the JMock library
  • cglib:  Neded for use with the JMock library
  • jmock-junit4: JMock library, which allows for the creation of mock objects to satisfy downstream dependencies of classes under test with JUnit.
    <!-- This is where you set the Jive SBS version your plugin is compiled against. -->
    <properties>
        <sbs.version>4.0.0</sbs.version>
    </properties>
</project>

The version of Jive against which the plugin is being compiled against is defined here, in the sbs.version property.