Jivespace : Document List - Developers

Jive SBS Maven Archetypes

communities@jivesoftware.com — Mon, 09 Nov 2009 16:13:17 GMT

This document will describe 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 will describe each archetype in detail.

Archetype: 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.

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.

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. Because of this, save for your initial build,it's probably best not to do your builds from the root level, but at the individual sub-project levels instead. The initial contents of the folder consists 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 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, so any beans defined therein will take precedence over any defined within the core SBS Spring XML files. This gives developers the ability to override any Spring beans defined within SBS, as well as add new ones, 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, if the developer wishes to ruther compartmentalize any custom Spring beans.

web/src/main/java

This is where your custom Java classes will live. The package structure used here is up to the developer, and should reflect the current project. However, if an overlay of a core SBS class is needed, the developer will need to create the exact package structure in which the class to be overlaid lives, and the core Java class copied and modified as needed. At build time, 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, and thusly take precedence over any classes defined in JAR files contained within the WAR's lib directory. A placeholder class, App.java, is included here by default, but can be deleted when development work starts.

web/src/main/keys

Any public/private encryption key certifications needed by the customization go here. At build time, contents of this folder are copied to the root target/jiveHome/keys directory to make them 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 the customization to take effect. Resources like Javascript files and Widget properties files need to actually replace the original artifacts in the SBS JAR file, and placed back into the WAR. By default, this is disabled in the web pom.xml for build performance reasons, but can be enabled by uncommenting the package-sbs-plugin execution element in the maven-antrun-plugin section in the pom.

web/src/main/overlay/beans

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

web/src/main/overlay/resources/scripts

Any overlaid Javascript resources will live here. In previous versions of the archetype, overlaid Javascript files needed to be accompanied by a compressed version of the file, but now that processing is done automatically by the build.

web/src/main/resources-filtered

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

web/src/main/themes

This is where custom themes go. The provided theme.xml file is initially populated with a theme name reflecting the name of the project. This file should be copied into the theme's main folder (web/src/main/theme/mytheme) in order to be visible to the app. It is merely placed in this folder as a placeholder.

web/src/main/webapp

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

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

A series of files meant to provide a custom configuration to an SBS overlay instance go here. Specifically:

jive_custom_i18n_en.properties: Override existing resource bundle values, and add new mappings here. This file is created by default. Should the project require other languages, the developer will need to create the appropriate file variations (jive_custom_i18n_es.properties, etc.).
struts-community-custom.xml: Override core Struts actions here. New actions can be added, as well.
ui-components-custom.xml: Additions, deletions of certain UI components are done here.
upgrade-custom.xml: Custom upgrade tasks are defined here.

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

Add your custom Freemarker templates here. Generally, if your change is look and feel-related, it will go in a theme. However, if the change needs to exist outside the context of a theme, such as in a major page structure/logic change, it will need to go here, in the same directory structure as the FTL being overlaid. Any overlaid Freemarker templates defined here will take precedence over any matching files within the core WAR file.

Archetype Build

The build behavior is all contained within the web/pom.xml file. This section will walk through each section of the pom, explaining them in detail.

<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>

This is the standard pom fare, defining the name, packaging, version, parentage of the project. The parameterized values are populated by the archetypes generation process.

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

The finalName element dictates the name of the custom WAR file generated by the build process, and reflects the name of the project, and the version of SBS being built upon.

As referenced above, the resources element specifies that artifacts in the src/main/resources-filtered folder are to be filtered when they are processed by the Maven build.

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
            <source>1.6</source>    <!-- compiling with JDK 6 now -->
            <target>1.6</target>
        </configuration>
     </plugin>

The maven-compiler-plugin is set up to compile with JDK 6.

We also use some Ant tasks to accomplish some of the more rudimentary file movements needed for the build:

<plugin>
    <artifactId>maven-antrun-plugin</artifactId>
        <executions>
            <execution>
                <id>delete-cobertura-ser</id>
                <phase>clean</phase>
                <goals>
                    <goal>run</goal>
                </goals>
                <configuration>
                    <tasks>
                        <echo message="deleting cobertura.ser" />
                        <delete file="\${basedir}/cobertura.ser" failonerror="false"/>
                    </tasks>
                </configuration>
            </execution>

The delete-cobertura-ser Ant execution deletes the cobertura.ser file generated in previous builds. If this file is not deleted, it can result in erroneous coverage data.

<execution>
    <id>compile-sbs-artifacts</id>
    <phase>compile</phase>
    <goals>
        <goal>run</goal>
    </goals>
    <configuration>
        <tasks>
            <!-- Copy themes files into ../target/jiveHome/themes for testing  -->
            <copy todir="\${basedir}/../target/jiveHome/themes" overwrite="true">
                <fileset dir="\${basedir}/src/main/themes">
                    <include name="**/*" />
                </fileset>
            </copy>
            <!-- Now build a new themes.zip for distribution -->
            <mkdir dir="${project.build.directory}/themes"/>
            <copy todir="${project.build.directory}/themes" overwrite="yes" filtering="off">
                <fileset dir="\${basedir}/src/main/themes"
                         includes="**/*" excludes="**/.svn, **/.svn/**" />
            </copy>
            <zip destfile="${project.build.directory}/themes.zip">
                <zipfileset dir="${project.build.directory}/themes" prefix=""/>
            </zip>
            <!-- Copy your etc directory to ../target/jiveHome for testing-->
            <mkdir dir="../target/jiveHome/etc"/>
            <copy todir="../target/jiveHome/etc" overwrite="true">
                <fileset dir="src/main/etc">
                    <include name="*.xml"/>
                </fileset>
            </copy>
            <!-- Build an etc.zip for distribution-->
            <zip destfile="${project.build.directory}/etc.zip">
                <zipfileset dir="\${basedir}/src/main/etc" prefix=""/>
            </zip>

            <!-- Copy your etc directory to ../target/jiveHome for testing-->
            <mkdir dir="../target/jiveHome/keys"/>
            <copy todir="../target/jiveHome/keys" overwrite="true">
                <fileset dir="\${basedir}/src/main/keys">
                    <include name="*.der"/>
                </fileset>
            </copy>
            <!-- Build an keys.zip for distribution-->
            <zip destfile="${project.build.directory}/keys.zip">
                <zipfileset dir="\${basedir}/src/main/keys" prefix=""/>
            </zip>
        </tasks>
    </configuration>
</execution>

The compile-sbs-artifacts Ant execution performs the following actions:

Copies the web/src/main/themes directory to the root target/jiveHome/themes for use by the local instance (if running Cargo, this is not necessary as the -DthemesDir system property points to the src/main/themes directory and makes changes available on the fly).
Zips the web/src/main/themes directory up into a themes.zip file, for deployment to a test or production server.
Copies the web/src/main/etc directory to the root target/jiveHome/etc for use by the local instance.
Zips the web/src/main/etc directory up into an etc.zip file, for deployment to a test or production server.
Copies the web/src/main/keys directory to the root target/jiveHome/keys for use by the local instance.
Zips the web/src/main/keys directory up into a keys.zip file, for deployment to a test or production server.

        <!-- The execution below should be used when a project needs to overlay any Jive SBS bean.properties
             or resources in the Jive SBS directory "resources.scripts".  In order for these overlay files
             to actually override their equivalents in the Jive SBS jar, they need to be placed in the
             Jive SBS jar itself. -->                     
        <!--<execution>
            <id>repackage-sbs-jar</id>
            <phase>package</phase>
            <goals>
                <goal>run</goal>
            </goals>
            <configuration>
                <tasks>
                    <unjar src="./target/${build.finalName}/WEB-INF/lib/jive-sbs-employee-${sbs.shortversion}.jar"
                           dest="./target/jive-sbs-employee-temp-${sbs.shortversion}" />
                    <copy todir="./target/jive-sbs-employee-temp-${sbs.shortversion}" overwrite="true">
                        <fileset dir="./src/main/overlay/" includes="**/*"/>
                    </copy>
                    <taskdef name="yui-compressor"
                             classname="net.noha.tools.ant.yuicompressor.tasks.YuiCompressorTask"
                             classpathref="maven.dependency.classpath"/>

                    <yui-compressor
                            warn="false"
                            munge="true"
                            preserveallsemicolons="false"
                            todir="./target/jive-sbs-employee-temp-${sbs.shortversion}"
                            fromdir="./src/main/overlay"
                            charset="utf8">
                    </yui-compressor>
                    <jar jarfile="./target/${build.finalName}/WEB-INF/lib/jive-sbs-employee-${sbs.shortversion}.jar" update="false">
                        <fileset dir="./target/jive-sbs-employee-temp-${sbs.shortversion}" includes="**/*"/>
                    </jar>
                    <jar destfile="./target/${build.finalName}.war">
                        <fileset dir="./target/${build.finalName}"/>
                    </jar>
                </tasks>
            </configuration>
        </execution>-->
    </executions>
</plugin>

The repackage-sbs-jar Ant execution, which is commented out by default, repackages the SBS JAR file with artifacts that cannot be appropriately overlaid within the WAR's WEB-INF/classes directory, specifically widget properties and Javascript files. It performs the following actions:

Explodes the core SBS JAR file to a directory.
Copies any artifacts from web/source/main/overlay to the exploded SBS JAR directory, overwriting any duplicate files.
Compresses any Javascript artifacts using the YUI Compressor utility to create the *-min.js Javascript artifacts.
Creates a new JAR file from the contents of the exploded JAR directory.
Creates a new WAR file from the contents of the exploded WAR directory.

<plugin>
    <!-- Surefire is our unit testing framework of choice-->
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <!-- Don't suck up selenium tests in there-->
        <excludes>
            <exclude>**/selenium/*Test.java</exclude>
        </excludes>
    </configuration>
</plugin>

The maven-surefire-plugin is configured to exclude any Selenium tests from being executed as part of the normal build process.

         <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>
</build>

More goodies for further configuring the maven-war-plugin.

<!-- These properties are set by a TeamCity CI server.  They get populated into the customer_version.jsp that
     is copied into our war file at the root.  This gives you web-accessible, definitive build information -->
<properties>
    <build.number>${env.BUILD_NUMBER}</build.number>
    #set($vcsNumber = '${env.BUILD_VCS_NUMBER.1}')
    <build.vcs.number>$vcsNumber</build.vcs.number>
    #set($projectName = '${env.TEAMCITY_PROJECT_NAME}')
    <build.project.name>$projectName</build.project.name>
</properties>

This is how we get the build version numbers into the custom_version.jsp file.

<dependencies>
    <dependency>
        <groupId>com.jivesoftware</groupId>
        <artifactId>jive-sbs-employee</artifactId>     <!-- was clearspacex -->
        <version>${sbs.version}</version>
        <type>war</type>
    </dependency>
        
    <dependency>
        <groupId>com.jivesoftware</groupId>
        <artifactId>jive-sbs-employee</artifactId>     <!-- was clearspacex -->
        <version>${sbs.version}</version>
        <type>jar</type>
        <scope>provided</scope>
    </dependency>
        
    <dependency>
        <groupId>com.jivesoftware</groupId>
        <artifactId>jive-sbs-employee-all</artifactId> <!-- was clearspacex-all -->
        <version>${sbs.version}</version>
        <type>pom</type>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>servlet-api</artifactId>
        <version>2.4</version>
        <scope>compile</scope>
    </dependency>
    <!-- We assume your jdbc jars will be provided at runtime-->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>5.1.5</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>8.3-603.jdbc3</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.openqa.selenium.client-drivers</groupId>
        <artifactId>selenium-java-client-driver</artifactId>
        <version>0.9.2</version>
        <scope>test</scope>
    </dependency>
    <!-- The dependencies below should be used when a project needs to overlay any resources in the Jive SBS
         directory "resources.scripts".  In order for the minimized Javascript files to be generated, these
         dependencies must be present so the yui-compressor task can run -->
    <!--<dependency>
        <groupId>com.jivesoftware</groupId>
        <artifactId>yuicompressor</artifactId>
        <version>2.2.4_2_0_0_rc1</version>
    </dependency>
    <dependency>
        <groupId>com.jivesoftware</groupId>
        <artifactId>yuicompressor-anttask</artifactId>
        <version>2.4.2</version>
    </dependency>-->
</dependencies>

The dependency element defines the libraries needed to compile and build the web project, including:

jive-sbs-employee (war): Jive SBS Core WAR
jive-sbs-employee (jar): Jive SBS Core JAR file
jive-sbs-employee-all (pom): Jive SBS Core dependencies
servlet-api: J2EE Servlet library needed to run the app. This used to be included via transitive dependencies, which have recently been discontinued.
mysql-connector-java: MySQL JDBC Driver
postgresql: PostgreSQL JDBC Driver
selenium-java-client-driver: Test driver class for Selenium test suite
yuicompressor: YUI Compressor library. Disabled by default, this is needed if the repackage-sbs-jar plugin is in use.
yuicompressor-anttask: YUI Compressor Ant task definition. Disabled by default, this is needed if the repackage-sbs-jar plugin is in use.

Profiles

The following section describes the various profiles that exist within the web project's POM. Profiles allow for different configurations to be used during a build by specifying the profile when the build is run. In the case of the overlay project, two profiles are used by default:

int: integration-testing profile. Allows for running all of the integration tests for the project, but more commonly for running the project inside of a local Tomcat instance via Cargo.
dev: largely the same as the int profile, but adds the ability to run the project in an environment a bit more conducive to the iterations associated with development.

Profile: int

The int profile contains two plugins:

cargo-maven2-plugin: Discussed below
selenium-maven-plugin: Runs the Selenium integration test suite
maven-surefire-plugin: Specifies that only Selenium integration tests are to be run

The cargo-maven2-plugin allows us to deploy the app to Tomcat for the purpose of running integration tests against the instance, and also to allow for manual use of the app, depending how it is run.

There are several ways to run Cargo:

Command	Comments
mvn -P int integration-test	Runs the integration tests inside of Cargo and then exits. Maven will run through all of the other dependent lifecycle phases before running the tests (compile, package, test, etc). You would use this if you wanted to only run the automated integration tests.
mvn -Dcargo.wait=true -P int integration-test	Runs the app within Cargo, after running through dependent Maven lifecycle phases. The presence of the cargo.wait system property tells Maven to keep the Tomcat instance up and to wait for either user input, or for the instance to be shut down manually. Note that running this way will cause the custom WAR to be rebuilt before the app is deployed.
mvn -Dcargo.wait=true -P int cargo:start	Runs the app within Cargo, but does not run through any dependent Maven lifecycle phases. Rather, it deploys the existing custom WAR to the Tomcat instance, and waits for user input or a manual shutdown. This option is recommended for plugin development when a new WAR is not required to observe changes in a local instance.

The cargo-maven2-plugin is defined in the POM as follows:

<profiles>
    <profile>
        <id>int</id>
        <build>
            <plugins>
                <!-- Cargo is our main method of running and testing/debugging SBS.  This is the main configuration area. -->
          <!-- Here is the config reference:  http://cargo.codehaus.org/Maven2+Plugin+Reference+Guide    -->
                <plugin>
                    <groupId>org.codehaus.cargo</groupId>
                    <artifactId>cargo-maven2-plugin</artifactId>
                    <version>1.0</version>
                    <configuration>
                  <!-- Feed them this value; Decides if Cargo should wait after the container is started or not -->
                        <wait>${cargo.wait}</wait>
                        <container>
                            <containerId>tomcat6x</containerId>
                            <home>${tomcat6.home}</home>
                            <systemProperties>
                                <jive.instance.home>\${basedir}/../target/jiveHome</jive.instance.home>
                                <jive.ws.disabled>true</jive.ws.disabled>
                                <jive.devMode>true</jive.devMode>
                                <themes.directory>\${basedir}/src/main/themes</themes.directory>
                                <!-- <pluginDirs>\${basedir}/../myplugin/src/main/plugin</pluginDirs> -->
                            </systemProperties>
                            <dependencies>
                       <!-- Throw in our most common jdbc connectors; add yours here if it's missing -->
                                <dependency>
                                    <groupId>mysql</groupId>
                                    <artifactId>mysql-connector-java</artifactId>
                                    <type>jar</type>
                                </dependency>
                                <dependency>
                                    <groupId>postgresql</groupId>
                                    <artifactId>postgresql</artifactId>
                                </dependency>
                                <dependency>
                                    <groupId>javax.servlet</groupId>
                                    <artifactId>servlet-api</artifactId>
                                    <type>jar</type>
                                </dependency>
                            </dependencies>
                        </container>
                        <configuration>
                            <home>target/tomcat6x</home>
                            <properties>
                                <cargo.jvmargs>-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n -Xms512m -Xmx1024m -XX:MaxPermSize=256m -XX:+UseParNewGC -XX:+UseConcMarkSweepGC</cargo.jvmargs>
                            </properties>
                            <deployables>
                                <deployable>
                                    <location>target/${customer.name}-${customer.version}-sbs-${sbs.version}.war</location>
                                    <pingURL>http://localhost:8080/jive</pingURL>
                                    <properties>
                                        <context>jive</context>
                                    </properties>
                                </deployable>
                            </deployables>
                        </configuration>
                    </configuration>
                    <executions>
                        <execution>
                            <id>start-container</id>
                            <phase>pre-integration-test</phase>
                            <goals>
                                <goal>start</goal>
                            </goals>
                        </execution>
                        <execution>
                            <id>stop-container</id>
                            <phase>post-integration-test</phase>
                            <goals>
                                <goal>stop</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>

The configuration element allows for the specification of system properties, deployables, customization of the JVM args, and more. Each item is discussed below.

<wait>${cargo.wait}</wait>

The value for the wait property is passed through from the command line, and determines whether Cargo will remain up, waiting for user interaction.

<container>
    <containerId>tomcat6x</containerId>
    <home>${tomcat6.home}</home>
    <systemProperties>
        <jive.instance.home>\${basedir}/../target/jiveHome</jive.instance.home>
        <jive.ws.disabled>true</jive.ws.disabled>
        <jive.devMode>true</jive.devMode>
        <themes.directory>\${basedir}/src/main/themes</themes.directory>
        <!-- <pluginDirs>\${basedir}/../myplugin/target/myplugin</pluginDirs> -->
    </systemProperties>
    <dependencies>
        <!-- Throw in our most common jdbc connectors; add yours here if it's missing -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <type>jar</type>
        </dependency>
        <dependency>
            <groupId>postgresql</groupId>
            <artifactId>postgresql</artifactId>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <type>jar</type>
        </dependency>
    </dependencies>
</container>

The container element allows for the configuration of how the Tomcat instance is run. The home element specifies where the Tomcat instance to be used is located, the value of which should be specified in your Maven settings.xml file.

JVM system properties are specified in the systemProperties element. The default values are as follows:

System Property	Value	Comments
jive.instance.home	${basedir}/../target/jiveHome	This points the SBS instance to the jiveHome directory deployed when the root project is built.
jive.ws.disabled	true	Disables web services, which makes startup much faster.
jive.devMode	true	Allows for running SBS in dev mode, which allows for the use of pluginDirs, themes.directory, and disables FTL cacheing.
themes.directory	${basedir}/src/main/themes	Specifies that the themes directory used by the app will be the those in the src/main/themes directory. This allows for changes to the themes to be made and observed on the fly, without rebuilding or restarting.
pluginDirs	none	Specifes a comma-delimited list of plugins to run, each being represented by a directory containing the contents of the exploded plugin JAR file. This allows the plugin to be installed in the SBS instance without actually saving it to the database and having to restart.

The dependencies element references upstream dependencies defined within the POM that are needed to properly run the tomcat instance.

    <configuration>
        <home>target/tomcat6x</home>
        <properties>
            <cargo.jvmargs>-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n -Xms512m -Xmx1024m -XX:MaxPermSize=256m -XX:+UseParNewGC -XX:+UseConcMarkSweepGC</cargo.jvmargs>
        </properties>
        <deployables>
            <deployable>
                <location>target/${customer.name}-${customer.version}-sbs-${sbs.version}.war</location>
                <pingURL>http://localhost:8080/jive</pingURL>
                <properties>
                    <context>jive</context>
                </properties>
            </deployable>
        </deployables>
    </configuration>
</configuration>

The configuration element defines various Cargo properties, including how to start the JVM, and where the artifacts to be deployed reside. The home element specifies where the WAR being deployed should be copied to and exploded. Running SBS is very memory intensive and requires that additional memory be allocated to the stack, which is done using the cargo.jvmargs property. The webapp(s) to run is/are defined in the deployables element, each supplying the location of the war to be deployed, as well as the context under which the deployable is to be run. By default, only one deployable is defined: the WAR created during the build, which runs under the jive context (http://localhost:8080/jive).

Profile: dev

The dev profile, like the int profile, provides for the running of the customized SBS instance locally, via Tomcat and Cargo, but without the notion of integration testing being the purpose. The plugins offered by the profile are:

cargo-maven2-plugin
javarebel-maven-plugin

The cargo-maven2-plugin functions largely the same as in the int profile, but with a few more options to better facilitate the use of Java Rebel. For example, the following system properties are specified in the systemProperties element:

System Property	Default Value	Comments
docverse.enabled	false	Disables the DocVerse module, which causes problems with JavaRebel
rebel.struts2-plugin	true	Enables Rebel monitoring of Struts configuration changes

The JavaRebel plugin is commented out by default, since it requires a license to run. Java Rebel allows for the monitoring of class directories so that changes can be hot-deployed to a running instance without a restart.

<!--<plugin>
    <groupId>org.zeroturnaround</groupId>
    <artifactId>javarebel-maven-plugin</artifactId>
    <executions>
        <execution>
            <id>generate-rebel-xml</id>
            <phase>process-resources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <classpath>
            <fallback>default</fallback>
            <resources>
                <resource>
                    <directory>\${basedir}/../myplugin/target/classes</directory>
                </resource>
                <resource>
                    <jarset>\${basedir}/../myplugin/target/dependency</jarset>
                </resource>
            </resources>
        </classpath>
        <war>
            <path>\${basedir}/target/${customer.name}-${customer.version}-sbs-${sbs.version}</path>
        </war>
    </configuration>
</plugin> -->

The custom WAR file is specified by default. To target additional directories, such as plugins, an entry for the plugin's classes directory is needed in the resources element, like shown in the listing above. This will allow for changes to the plugin's code to be monitored and loaded without having to rebuild the plugin and restart the server.

Archetype: maven-sbs-plugin-archetype

The plugin archetype provides a template for SBS plugin projects, and is the preferred method for customizing an SBS instance.

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 will be 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: Defines the initial database schema to be created upon the plugin's initial installation into the system.
spring.xml: Defines 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: Defines 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 will go here.

src/main/plugin/resources/templates

Freemarker templates needed by the plugin go here.

src/main/resources

Artifacts in this directory will be 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

This is where unit tests live.

Archetype Build

The build behavior is all contained within the plugin's pom.xml file. This section will walk through each section of the pom, 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 SBS against which the plugin is being compiled against is defined here, in the sbs.version property.

Dynamically Extending or Modifying the Acegi Security Chain in SBS 4.0 and later

communities@jivesoftware.com — Tue, 03 Nov 2009 18:01:57 GMT

Introduction

This document presents a simple yet powerful approach to adding custom security filters deployed by a plugin. These filters allows a plugin to intercept requests and perform operations during the authentication phase.

Problem Defintion

The Acegi security filters are defined in spring-security.xml in a bean called "filterChainProxy". This filter chain proxy is composed of a series of URL patterns and each URL pattern has an associated ordered list of filters. Often there is a need for plug-ins or other customizations to either modify the list of filters associated with a URL pattern or add a new URL pattern with it's own associated list. The Acegi API provides the ability to get access to the list of filters for each URL pattern and allows you to replace the entire list. This was the technique described in the aforementioned blog post. However it did not provide any ability to add new URL patterns. Furthermore, the coding required to do this was quite verbose and required you to copy the existing list of filters and re-write it back in order to preserve existing behavior.

Example extract of the filter chain proxy bean:

 <bean id="filterChainProxy">
        <property name="filterInvocationDefinitionSource">
            <value>
                ...     
                /admin/**=httpSessionContextIntegrationFilter, sessionTrackingFilter, adminAuthenticationFilter, openfireAuthenticationFilter, adminExceptionTranslationFilter,jiveAuthenticationTranslationFilter
                ...
                /__services/**=httpSessionContextIntegrationFilter, basicAuthenticationFilter, wsExceptionTranslator, jiveAuthenticationTranslationFilter
                ...               
                /**=httpSessionContextIntegrationFilter, sessionTrackingFilter, formAuthenticationFilter, loginPopupFormAuthenticationFilter, rememberMeProcessingFilter, feedBasicAuthenticationFilter, exceptionTranslationFilter, jiveAuthenticationTranslationFilter,contextOptimizationFilter
                ...




           </value>
        </property>
    </bean>

We need a better way to add new filters into existing chain and also provide for new URL patterns.

Solution

Since each filter can also be treated as a filter chain proxy, we can add standardized filter chain proxies to the filter lists in the hard coded spring-security.xml. By defining these filter chain proxies as "org.springframework.security.util.FilterChainProxy", we are provided with a much more flexibile API where we can control both the list of filters and the actual URL mapping.

Using the example extract above, the following standardized filter chain proxies have been defined and added to spring-security.xml in SBS 4.0:

    <bean id="filterChainProxy">
        <property name="filterInvocationDefinitionSource">
            <value>     
                ...
                /admin/**=pluginPreFilterChain, httpSessionContextIntegrationFilter, pluginPostSessionContextFilterChain, sessionTrackingFilter, adminAuthenticationFilter, openfireAuthenticationFilter, adminExceptionTranslationFilter,jiveAuthenticationTranslationFilter, pluginPostFilterChain
                ...
                /__services/**=pluginPreFilterChain, httpSessionContextIntegrationFilter, pluginPostSessionContextFilterChain, basicAuthenticationFilter, wsExceptionTranslator, jiveAuthenticationTranslationFilter, pluginPostFilterChain
                ...
                /**=pluginPreFilterChain, httpSessionContextIntegrationFilter, pluginPostSessionContextFilterChain, sessionTrackingFilter, formAuthenticationFilter, loginPopupFormAuthenticationFilter, rememberMeProcessingFilter, feedBasicAuthenticationFilter, exceptionTranslationFilter, jiveAuthenticationTranslationFilter,contextOptimizationFilter, pluginPostFilterChain
           </value>
        </property>
    </bean>

    <bean id="pluginPreFilterChain">
        <security:filter-chain-map path-type="ant">
            <security:filter-chain pattern="do-not-filter-stub" filters="none" />
        </security:filter-chain-map>
    </bean>


    <!-- Filter chain that is processed right after the httpSessionContextIntegrationFilter has been processed -->
    <bean id="pluginPostSessionContextFilterChain">
        <security:filter-chain-map path-type="ant">
            <security:filter-chain pattern="do-not-filter-stub" filters="none" />
        </security:filter-chain-map>
    </bean>

    <!-- Filter chain that is processed after all other filters have been processed -->
    <bean id="pluginPostFilterChain">
        <security:filter-chain-map path-type="ant">
            <security:filter-chain pattern="do-not-filter-stub" filters="none" />
        </security:filter-chain-map>
    </bean>

Three standard filter chains have been provided; pluginPreFilterChain, pluginPostSessionContextFilterChain and pluginPostFilterChain. Of the three pluginPreFilterChain is the most powerful as it will be processed before the others, allowing you to potentially override subsequent processing. The other two have been provided for convenience as common customization require inserting processing in the middle of the chains.

These filter chain proxies are defined as empty stubs in the hard coded spring file. Custom code can add new URL patterns and associate a list of filters.

For example, consider the need to add our custom processing filter (smeAuthFilter) to our restful service which is accessed at the URL /__services/sme. In order to do this we need to add a sub filter chain to the existing pattern /__services/**. We will use the pluginPreFilterChain to ensure that we get priority processing. This can be achieved with the following code which should be called from your plugin init method:

    private void addWebserviceSecurityFilter() {
        JiveContext context = JiveApplication.getContext();
        FilterChainProxy chain = (FilterChainProxy) context.getSpringBean("pluginPostSessionContextFilterChain");
        Map filterChainMap = chain.getFilterChainMap();
        filterChainMap.put("/__services/sme/**", getFilterList("smeWebServiceAuthFilter"));
        chain.setFilterChainMap(filterChainMap);
    }
 
    private List<Filter> getFilterList(String... names) {
        JiveContext context = JiveApplication.getContext();
        List<Filter> filters = Lists.newArrayList();
        for (String name : names) {
            filters.add((Filter) context.getSpringBean(name));
        }
        return filters;
    }

This technique can be used to modify or extend any existing URL access pattern. For example, one could add a new URL pattern to block an existing specific web service.

Maven: How to use with Eclipse

communities@jivesoftware.com — Thu, 24 Sep 2009 16:07:02 GMT

Approach Using M2Eclipse Plugin

We recommend using the M2Eclipse Plugin for Maven. First you will want to have the most current versions available of the following:

Eclipse Classic version of the Eclipse IDE: http://www.eclipse.org/downloads/
Eclipse XML Editors and Tools
M2Eclipse Plugin

First, install Eclipse Classic. Next,

Install Eclipse XML Editors and Tools

Go to Help > Install New Software:

Select the Galileo update site and select the Eclipse XML Editors and Tools:

Install the M2Eclipse Plugin

Use the same facility to add the M2Eclipse tools. Click the Add. . . button and enter the M2Eclipse update site URL: http://m2eclipse.sonatype.org/update/

Select the first group, to include all of "Maven Integration". When this completes successfully, your IDE should be good to go. It will restart several times in the above process.

Project Setup

From an empty or existing workspace, choose File > Import or right click on the Package Explorer pane and select Import. Select to import Maven Projects:

M2Eclipse will detect all the pom files and generate the project structure. Create a New. . . Java working set from this:

Click on the Advanced options and add a template name to tie each maven module to your project, e.g. Acme-[artifactId]

Congratulations your project has been creaed:

Now when you build Eclipse will use the Maven compile configuration.

Where are my sources?

Sources are stored in Maven source jars. To download and link these up in your IDE, do the following steps:

Right-click on your pom > Maven > Downlaod Sources

This should pull the dependency sources and link them up. Try by pulling up a Jive class, such as LoginAction (cmd+shift+T) and validate the source is there.

And what about my .ftls and other war file sources?

If you have downloaded a source build, you can perform the above sets and create a new working set that references those source files. However, the simplest approach is to include your war target directories in the project configuration. The good news is that this will happen by default, unless you choose to explicitly hide the target directories. The bad news is you'll see multiple entries for files such as struts-community-custom.xml when you do a resource search (cmd+shift-R).

If you want to go ahead and hide the target directories from an index search, right-click on the e.g. web/target directory in your package explorer, and click Properties:

If you check the Derived checkbox, it will no longer appear in your searches.

Maven-Only Alternative Method

It is possible to use Maven with Eclipse without using the M2Eclipse tool.

From the root of your project run the following command:

mvn eclipse:clean eclipse:eclipse -DdownloadSources=true

This will refresh your existing eclipse project files and link up your sources, so that all SBS sources are indexed and will link up in the debugger.

Then from a fresh workspace you import the root directory as an existing project.

Information on Configuring Domain Name for Cloud Edition

communities@jivesoftware.com — Thu, 03 Sep 2009 19:26:32 GMT

This page provides information and instructions on how to set up DNS entries so that your Jive SBS community can be accessed by a hostname of your choosing. As an example this will let you refer to your site as something like http://public.mycompany.com instead of http://public-mycompany.jivesbs.com. This feature is only available on Cloud editions of Jive SBS.

Background

DNS is an internet protocol that maps human-friendly hostnames like 'www.mycompany.com' to the IP Addresses like '10.192.7.8' that are needed to actually communicate over the network. The technical name for this type of mapping is a DNS "A" Record. With Jive SBS hostname mapping we use a separate type of DNS mapping called a "CNAME record". This just points one hostname to another.

What we want to have setup is two DNS mappings:

public.mycompany.com is a CNAME record pointing to public-mycompany.jivesbs.com
public-mycompany.jivesbs.com is an A record pointing to the specific address hosting your service.

A key part of how DNS works is that every domain has it's own "Master Server". So for instance the jivesbs.com domain has a Master Server controlled by Jive while mycompany.com would have it's own Master Server controlled by either the IT department of "My Company" or by a 3rd party DNS registrar. DNS software handles all the details of figuring out which Master Server to contact to look for records.

What this means for you is that Jive can only make DNS changes for domains we control, such as jivesbs.com. In our example this means Jive can't make any changes to the DNS setup for the mycompany.com domain.

Setting up CNAME

The steps to do this all depend on who is maintaining the DNS server for the domain you want to use. In most companies this change can be done just by making a request to your I.T. department to setup the CNAME record.

If you are using a 3rd-party registrat like GoDaddy then you most likely have self-service access to make these kinds of DNS changes. For instance in GoDaddy you would follow these steps:

login to godaddy.com
Go to your domain dashboard
Go to "Total DNS/MAX" Manage
Click on "Add CNAME"
Enter the sub-domain you want to use ('public' in the example above). For the "points to host name" value use the name supplied in the product ('public-mycompany.jivesbs.com' in the example).
For the "TTL" value use something like "1 Hour". This stands for "Time To Live" - it governs how long DNS servers should cache the value without rechecking.

Configuring in Jive SBS

Once the CNAME has been setup you need to configure in Jive SBS what the name of the site is. This can be found under "Settings -> Network Settings"

FAQ

Q: Can I just have Jive handle setting this up?

A: No - as explained above Jive can only make DNS changes to domains it controls.

Q: Why don't we just map 'public.mycompany.com' to an IP address?

A: There are various technical reasons for this - the main one is that by using a CNAME then Jive can move your service to a different IP address without having to make any changes to DNS configuration for 'mycompany.com'.

Q: What does Jive SBS use the configured hostname for?

A: Examples of where this value will be used include:

creating links in outgoing emails
creating links for blog trackbacks
replacing full URLs pasted into the editor with relative links to the actual content

Q: How does this impact the mail address/domain used by my community?

A: This has no impact on mail addresses and domains. In the future Jive SBS will provide a method to configure incoming and outgoing emails to go through a customer domain.

Q: How this impact SSL?

A: When using a CNAME for your community name SSL will not be available. In the future Jive SBS will provide a method to allow the appropriate SSL certificates to be generated/uploaded.

Customer SVN Repository JIRA Policy

communities@jivesoftware.com — Thu, 03 Sep 2009 17:37:26 GMT

Audience

This document applies only to customers or partners who have access to a project in the customer Subversion (SVN) source code repository hosted by Jive's Professional Services.

Overview of Changes

Effective 9/14/09, a change to the SVN checkin policy will affect you if you are commiting code to this repository. The change requires that all commits contain a valid JIRA Issue ID in the commit message. Commits without a valid JIRA Issue ID in the message will fail.

This change affects all projects located under the following directory: https://svn.jivesoftware.com/svn/ext/customer/

If you are actively working on a project in conjunction with Jive Professional Services, please contact your Jive project or account manager to provide you with a JIRA ID. If you are not currently working with Jive but still using our repository, you can contact Greg Weinger (greg.weinger@jivesoftware.com), and he will provide you a JIRA ID.

We apologize for any inconvenience.

Why We Are Doing This

Jive PS is adopting this policy to provide better traceability from coding requirements and/or bug fixes to the actual modifications made in source code. Requiring a JIRA ID ensures we can link from the JIRA documentation of the requirement or bug report to the code modifications. We believe this will improve our efficiency in writing new and modifying old code, aid troubleshooting, improve code quality, and enhance communication with our customers.

These benefits extend to all custom code deployed on Jive SBS that we maintain, and therefore we are adopting this across the entire repository.

Instructions

First, you need to obtain a valid JIRA ID for your checkins. Contact Gregory Weinger, or your Jive Professional Services Project Manager or Account Manager to provide you with one. If you'd like to use the JIRA tool to do issue tracking as well, we'll be happy to set up a specific JIRA account and project, and thereafter you can create your own individual JIRA IDs.

To commit successfully you need to embed this JIRA ID in your commit message. For example, if the JIRA ID associated with the code changes is "BEE-22", to check in a change to a file named test.txt, from the command line you would type:

svn commit -m "BEE-22 New test text" test.txt

If you have an invalid JIRA ID or if you do not include one, you will see a message like this:

gw$ svn commit test.txt
Sending test.txt
Transmitting file data .svn: Commit failed (details follow):
svn: Commit blocked by pre-commit hook (exit code 1) with output:
Committer: greg.weinger
Commit message: "no!"
Commit rejected: No project accepts this commit. Project [*]: Commit message must contain at least one valid issue key.

Jive SBS Delegated Authentication

communities@jivesoftware.com — Thu, 03 Sep 2009 17:29:36 GMT

What is Jive SBS Delegated Authentication?

Delegated Authentication is a mechanism that allows a customer to control the definition of users outside of the Jive SBS system. This feature is available in Jive SBS starting with version 4.0.

Elements controlled by Delegated Authentication include:

existance of a user account
enabled/disabled state of a user account
password used to authenticate an account
profile fields associated with account

When Delegated Authentication is enabled and configured Jive SBS will make a simple Web Service call out to the configured server whenever a user attempts to login.

Web Service Details

When Delegated Authentication is enabled, the login process is as follows:

When a user tries to log in through the website or Jive API, a web services call passes the username, password, and sourceIP to a web service hosted by your organization. The web service must be deployed at a location that can be accessed by Jive servers.
Your implementation of the web service validates the information and returns a value for "authenticated" of either "true" or "false". Optionally, the web service can return profile information that should be used by Jive, and whether the user account is enabled or disabled.
If the disabled value is "true" then the user account will be disabled in the Jive SBS UI and the user is informed that the username and password combination was invalid.
If the authenticated value is "true" then the login succeeds. If "false" is returned, then the user is informed that the username and password combination was invalid.
If the authenticated value is "true" and includes profile data, the Jive profile information for the user will be updated with the supplied values.

The web service will be called using HTTP POST using the following parameters:

Name	Description
username	the user's username
password	the user's password
sourceIP	the IP address that originated the login request. This value can be used to only allow logins from a certain IP address range; for example, to ensure that a user is connected to the VPN.

The response to the web service call is an XML document with a single required parameter indicating whether the authentication succeeded. If authenticated has a value of "true" the web service response can include optional profile data so that the Jive profile is kept synchronized with an external profile such as an LDAP directory or website member data. An optional attribute will control if the user account should be disabled.

Name	Description
authenticated	"true" if the user should be authenticated, "false" otherwise. When "true", an optional profile element can be specified to update the user's profile data
disabled	"true" if the user account should be disabled, "false" otherwise.

The values contained in the <profile> element depend on the edition and configuration of your Jive SBS instance. All values are optional. The following is an example of values that are recognized by a Jive SBS Public Community:

Name	Description
firstName	The user's first name; the Jive profile will be updated with this value
lastName	The user's late name; the Jive profile will be updated with this value
occupation	The user's occupation; the Jive profile will be updated with this value if the profile field exists
company	The company the user works at; the Jive profile will be updated with this value if the profile field exists
phonenumber	The user's primary phone number; the Jive profile will be updated with this value if the profile field exists
biography	The user's biography; the Jive profile will be updated with this value if the profile field exists
url	The user's url; the Jive profile will be updated with this value if the profile field exists
expertise	A description of the user's expertise areas; the Jive profile will be updated with this value if the profile field exists
joindate	Date the user account was created; the Jive profile will be updated with this value if the profile fields exists
alternatephonenumber	The user's alternative phone number; the Jive profile will be updated with this value if the profile fields exists
alternateemail	The user's alternative email address; the Jive profile will be updated with this value if the profile fields exists

Example web service responses:

1. User is authenticated and certain profile data is included.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationResponse xmlns:ns2="http://jivesoftware.com/authentication">
    <authenticated>true</authenticated>
    <profile>
        <firstName>Joe</firstName>
        <lastName>Smith</lastName>
        <email>joe.smith@example.com</email>
    </profile>
</AuthenticationResponse>

2. Authentication fails

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AuthenticationResponse xmlns:ns2="http://jivesoftware.com/authentication">
    <authenticated>false</authenticated>
</AuthenticationResponse>

Additional Recommendations and Considerations

We highly recommend using and requiring https for the web service end-point to improve security. When https is used, a valid signed certificate is required from a trusted provider such as Thawte or Verisign.
The web service endpoint must return a reasponse within 2 seconds. If a response is not returned within this period, the end-user will be shown an error message stating that the remote authentication service is not available.
The implementation of the web service must be accessible by Jive servers. Typically this means deploying the web service on a server in the DMZ then using the server's external DNS name when configuring authentication gateway URL within Jive.

Sample Projects

There are two attachments to this document for implementations of sample servers. Both of these servers have a sample implementation of user validation logic - if the user name is like 'userN@company.com' (where N is a number) and the password is 'passN' then the user will be authenticated. You can replace this sample implementation with your own logic.

delegatedsso-sample-cxf.tar

This is a sample Java implementation. It is a Maven project that uses CXF's support for JAX-RS to implement the server.

To get the sample up and running:

tar xvf delegated-sample-cxf.tar

cd delegated-sample-cxf

mvn install

mvn jetty:run

At this point you can access the webservice at a URL like:

http://localhost:8080/delegated-sample-cxf/jiveauth/auth?username=user1@company.com&password=pass1 8080/delegated-sample-cxf/jiveauth/auth?username=user1@company.com&password=pass1

This project will output a WAR file that can be deployed to your choice of App server.

You can replace the sample implementation in SampleSSOManager.java with your own implementation. To specify your implementation you can edit the spring configuration in cxf-beans.xml.

delegatedsso.zip

This is a ASP.Net project solution. After opening the project and running it you can access the sample at a URL like:

http://localhost/Auth.asmx/doAuth?username=user2@company.com&password=pass2&sourceip=//localhost/Auth.asmx/doAuth?username=user2@company.com&password=pass2&sourceip=

Implementation of sample service is in the Auth.asmx Web Service Code-Behind file Auth.asmx.cs.

Testing REST

communities@jivesoftware.com — Fri, 10 Jul 2009 23:00:52 GMT

Testing REST on SBS is quick and straight forward with the REST Client Firefox Add-on.

Go to your SBS Admin Console and System > Settings > Web Services to enable REST web services. You will need to restart your server for the settings to take effect.
Read through the REST Web Services Reference documentation to find what commands you will need.
Once REST Client is installed, open it through Tools > REST Client in Firefox.
Log into the appropriate account.
Fill out the appropriate request. Put your XML parameters in the Request Body field.

Displaying a Custom Icon for a Content Type

steve@jivesoftware.com — Thu, 09 Apr 2009 16:45:47 GMT

You can have the application display a different icon for included content types. To do that, you override SkinUtils.getJiveObjectIcon. Include your code where it will execute on application startup, or where it will execute when your plugin is initialized.

Note: If you're building a custom content type, be sure to check out Content Type Framework and TypeUIProvider.

To replace an included icon with another, your code should add an icon generator that is associated with the existing content type -- here, a blog post:

// Override an existing icon
IconGenerator blogpostIG = new IconGenerator() {
   public String getIcon(JiveObject object, boolean returnAsCssClass, int type) {
      return my-blog-post;
   }
};
SkinUtils.addIconGenerator(JiveConstants.BLOGPOST, blogpostIG);

When you want to associate an icon with a particular content type, but only when that content type features a particular property and value, check for the property on the JiveObject instance your code receives:

// Only handle documents with a certain property, otherwise use the default.
IconGenerator documentIG = new IconGenerator() {
   public String getIcon(JiveObject object, boolean returnAsCssClass, int type) {
      Document doc = (Document)object;
      if (doc.getProperties().get(my.prop) != null) {
         return my-property";
      }
      else {
         return null;
      }
   }
};
SkinUtils.addIconGenerator(JiveConstants.DOCUMENT, documentIG);

Jive SBS 3.0 Admin & Developer Training Course: San Francisco, May 14-15 2009

rick@jivesoftware.com — Wed, 25 Mar 2009 20:29:21 GMT

Ramp up quickly on Jive SBS 3.0 Administration, Management, and Development

Learn what's new in version 3.0. Includes 1 Day of User/Admin Training and 1 Day of Developer Training. Computers and software are provided.

To sign up, return the attached order form to education@jivesoftware.com or fax to (503) 961-1322.

Agenda/Price: (order form and agenda attached below)

$1695 for both days

$995 per day if only attending one day (save $295 by attending both days)

Dates:

May 14-15, 2009

Location:

New Horizons Training Center

160 Pine Street - Suite 530

San Francisco, CA 94111

Directions:

Driving Directions (see map below)

From I-80 Eastbound (San Francisco Airport and Peninsula)
1. Take EXIT 2 (4th Street)
2. Slight LEFT at Bryant Street
3. Turn LEFT at 2nd (Second) Street
4. Turn RIGHT at Market Street
5. Turn LEFT at Front Street
6. Turn LEFT at Pine Street

From I-80 Westbound (across Bay Bridge)
1. Take the FREMONT STREET exit.
2. Turn LEFT at Fremont Street
3. Continue on Front Street
4. Turn LEFT at Pine Street.

BART (Bay Area Rapid Transit):

1. 1. Take BART to the EMBARCADERO Station (298 Market St.)
2. Walk WEST on Pine Street (towards Front Street)
3. 160 Pine is located on your right
4. New Horizons is located in Suite 530 (5th floor).

For additional BART directions, see www.bart.gov

MUNI (San Francisco Municipal Transportation Agency):
Note: The N, L, M, K, T, and J lines intersect this station.

1. Take the light rail to EMBARCADERO Station, which is a BART station.
2. Follow the directions above from Embarcadero Station.

Jive SBS 3.0 Admin & Developer Training Course - Portland, May 5-6 2009

rick@jivesoftware.com — Wed, 25 Mar 2009 20:23:49 GMT

Ramp up quickly on Jive SBS 3.0 Administration, Management, and Development

1 Day User/Admin Training

1 Day Developer Training

Agenda/Price: (order form and agenda attached below)

$1695 for both days

$995 per day if only attending one day (save $295 by attending both days)

Dates:

May 5-6, 2009

Location:

Jive Software, Inc - Training Room

915 SW Stark St. - Suite 400
Portland, OR 97205