Not only are all of their apps highly useful, but they are, for the most part, pretty consistent when it comes to installation and plugin management.

Essentially, you extract a zip of the app, edit a [app-name]-init.properties file and include a path where you’d like the app’s home directory to live, and start the app. At this point, the app is running with some pre-bundled plugins and provides a plugins folder within the specified home directory where you can drop in new plugins.

Simple.

Now if you’re like me, at some point you’ll think that it would be pretty awesome if there was an easy way to make your own webapps behave in this same way including full spring support, auto-home directory creation, bundled plugins, etc, etc.

Lucky for you, I’ve done all the ground work, and I’ve packaged it up into something I call the Atlas Webapp Kit

Source

The result of this project will be a war file that can be used as a starting point to build an Atlassian®-like webapp.

The source code can be checked out from subversion:

svn co http://svn.sysbliss.com/public/atlassian-webappkit/trunk

Alternatively, you can download a source gzip file.

Lastly, you can download a binary of the war file.

Project Structure

The project is structured as a maven multi-module project with a parent module and two children:

• atlas-webappkit – the parent pom
  • atlas-webappkit-core – all of the java code for the app
  • atlas-webappkit-webapp – the webapp descriptors and such

The Parent POM

Rather than waste bits by listing the parent pom, just take a look at it’s source.
It’s pretty basic in that it lists our child modules, sets up dependency and plugin versions and lists the repositories needed.
That’s it.

The Webapp

We’re starting with the webapp since it’s pretty simple and will provide us with some context when we get to the core project.

First let’s do a quick overview of the files since there are only a few of them:

• bundled-plugins.xml – a simple descriptor used by the maven assembly plugin to zip up any plugins we want to bundle
• applicationContextBootstrap.xml – a spring beans file for use during the bootstrap process
• applicationContextPlugins.xml – a spring beans file for initializing the plugins framework
• log4j.properties – you should know what this is
• refplatform-init.properties – the properties file that holds our home directory path
• context.xml – the file to map our url/context in tomcat
• web.xml – the main web app descriptor
• index.jsp – just a placeholder jsp

Since we are doing a couple of interesting things during the build, I think it’s worthwhile to have a look at the pom.xml for the webapp module….

Webapp POM

The top of the pom is pretty normal, just inherits the parent pom and sets the project details and so we’ll skip to the interesting stuff.

Defining Bundled Plugins

Lines 23-82 are used to configure the maven-dependency plugin which we’re using to resolve the plugin artifacts we want to bundle with our app and copy them to the ${pluginBundleDirectory}

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

            <plugin>
                <artifactId>maven-dependency-plugin</artifactId>
                <executions>
                    <execution>
                        <id>copy-bundled-plugins</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>copy</goal>
                        </goals>
                        <configuration>
                            <outputDirectory>${pluginBundleDirectory}</outputDirectory>
                            <artifactItems>
 
                                <artifactItem>
                                    <groupId>org.apache.felix</groupId>
                                    <artifactId>org.apache.felix.webconsole</artifactId>
                                    <version>1.2.10</version>
                                </artifactItem>
 
                                !!! Others Removed To Save Space !!!
 
                            </artifactItems>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

Lines 84-102 use the maven assembly plugin to create a zip file containing the bundled plugins we just copied and put it in the classpath of the resulting war

Notice on line 87 we specify the finalName as atlassian. This will result in our zip file being named atlassian-bundled-plugins.zip
We’ll need to use this name later to extract the bundle.

84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <configuration>
                    <finalName>atlassian</finalName>
                    <descriptors>
                        <descriptor>src/main/assembly/bundled-plugins.xml</descriptor>
                    </descriptors>
                    <outputDirectory>${project.build.outputDirectory}</outputDirectory>
                </configuration>
                <executions>
                    <execution>
                        <id>create-bundled-plugins</id>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>attached</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

The next section of the full pom sets up cargo for testing and is not listed here.

Creating our context

Remember the context.xml file? It’s used to map our context url to our webapp, however since our final war contains a version number which may change, we need to use some maven “magic” to ensure tomcat maps it properly.

Notice our context.xml uses the ${project.version} maven variable

context.xml

1
2

<?xml version="1.0" encoding="UTF-8"?>
    <Context path="/atlas-webappkit" docBase="webapps/atlas-webappkit-webapp-${project.version}"/>

And on lines 126-141 of our pom, we use the maven-war-plugin to process and filter the context.xml which does the variable substitution for us

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-war-plugin</artifactId>
                 <configuration>
                     <webResources>
                         <webResource>
                             <directory>${basedir}/src/main/webapp/META-INF</directory>
                             <includes>
                                 <include>context.xml</include>
                             </includes>
                             <targetPath>META-INF</targetPath>
                             <filtering>true</filtering>
                         </webResource>
                     </webResources>
                 </configuration>
             </plugin>

Dependencies

Since we’ve split out all the actual java code to a separate module, our dependency list for the webapp is tiny.
We just need our core jar and log4j

145
146
147
148
149
150
151
152
153
154
155
156
157
158

    <dependencies>
        <dependency>
            <groupId>com.atlassian.refplatform</groupId>
            <artifactId>atlas-webappkit-core</artifactId>
            <version>${parent.version}</version>
        </dependency>
 
        <dependency>
            <groupId>log4j</groupId>
            <artifactId>log4j</artifactId>
            <version>1.2.9</version>
        </dependency>
 
    </dependencies>

And finally, we need to define the pluginBundleDirectory property that we used above to bundle plugins.

160
161
162

    <properties>
        <pluginBundleDirectory>target/bundled-plugins</pluginBundleDirectory>
    </properties>

The Webapp Descriptor (web.xml)

Now that our pom is all in order let’s look at the web.xml file.

The top of the web.xml is pretty standard as it defines the web-app tag and our application name.

Lines 11-16 define our list of Spring beans files we want to load. Notice that we’re only including the applicationContextPlugins.xml and not the bootstrap file.
Also note that this is where you can define any other app-specifc spring files to be loaded.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<?xml version="1.0" encoding="UTF-8"?>
    <web-app xmlns="http://java.sun.com/xml/ns/j2ee"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
             version="2.4">
 
        <description>The Atlassian Reference Application</description>
        <display-name>Atlassian RefApp</display-name>
 
        <context-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>
                classpath:/applicationContextPlugins.xml
            </param-value>
        </context-param>

Servlet Filters

Lines 19-62 setup some servlet filters. Each filter uses the class RefPlatformServletFilterModuleContainerFilter
This filter is used by the Atlassian® Plugins Framework to build a filter chain from any plugins that include servlet filters.

19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

    <filter>
        <filter-name>filter-plugin-dispatcher-after-encoding</filter-name>
        <filter-class>com.atlassian.refplatform.web.servlet.RefPlatformServletFilterModuleContainerFilter</filter-class>
        <init-param>
            <param-name>location</param-name>
            <param-value>after-encoding</param-value>
        </init-param>
    </filter>
 
    <filter>
        <filter-name>filter-plugin-dispatcher-before-decoration</filter-name>
        <filter-class>com.atlassian.refplatform.web.servlet.RefPlatformServletFilterModuleContainerFilter</filter-class>
        <init-param>
            <param-name>location</param-name>
            <param-value>before-decoration</param-value>
        </init-param>
    </filter>
 
 
    <filter>
        <filter-name>filter-plugin-dispatcher-before-dispatch</filter-name>
        <filter-class>com.atlassian.refplatform.web.servlet.RefPlatformServletFilterModuleContainerFilter</filter-class>
        <init-param>
            <param-name>location</param-name>
            <param-value>before-dispatch</param-value>
        </init-param>
    </filter>
 
 
    <filter-mapping>
        <filter-name>filter-plugin-dispatcher-after-encoding</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
 
    <filter-mapping>
        <filter-name>filter-plugin-dispatcher-before-decoration</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
 
 
    <filter-mapping>
        <filter-name>filter-plugin-dispatcher-before-dispatch</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

Listeners

Lines 64-73 setup 2 listeners. The first listener is a bootstrap listener which will be used to load the applicationContextBootstrap.xml context and bootstrap the application.
The next listener is a special Spring context loader that will be used to merge our bootstrap context with the rest of the files listed at the top of the web.xml
The second listener is also where we’ll initialize the plugins framework.

64
65
66
67
68
69
70
71
72
73

    <!-- ============ Listeners ============== -->
    <!-- Loads the Bootstrap context for minimal app startup -->
    <listener>
        <listener-class>com.atlassian.refplatform.web.listener.BootstrapLoaderListener</listener-class>
    </listener>
 
    <!-- Loads the Spring servlet context if / when the app has been setup -->
    <listener>
        <listener-class>com.atlassian.refplatform.web.listener.BootstrappedContextLoaderListener</listener-class>
    </listener>

Servlets and Mappings

At the end of our web.xml file we define a single servlet and a mapping for it as well as our welcome list.

The servlet is provided by the Atlassian® Plugins Framework and is used to enable any servlets that other plugins may contribute.
The servlet is mapped to /plugins/servlet/* This will be the base url where all other plugin servlets will be located.

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

    <servlet>
        <servlet-name>plugins</servlet-name>
        <servlet-class>com.atlassian.plugin.servlet.ServletModuleContainerServlet</servlet-class>
    </servlet>
 
    <servlet-mapping>
        <servlet-name>plugins</servlet-name>
        <url-pattern>/plugins/servlet/*</url-pattern>
    </servlet-mapping>
 
 
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
 
    </web-app>

Spring Context Files

The base platform requires 2 spring contexts; One for our bootstrapping process, and the other for the Atlassian® Plugins Framework.

applicationContextBootstrap.xml

This file holds all the beans we’ll need during the bootstrapping process of our application. Since all we need to do during bootstrap is ensure the application’s home directory exists, this file is rather small.

It’s also good to note that this file is loaded by the BootstrapLoaderListener servlet listener and not a “normal” context loader listener.

In this file we define 2 beans, the homeLocator, and the bootstrapManager that is wired up with the homeLocator. We’ll get into the specifics of these a bit later.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:plugin="http://atlassian.com/schema/spring/plugin"
           xsi:schemaLocation="
           http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
           http://atlassian.com/schema/spring/plugin http://atlassian.com/schema/spring/plugin.xsd">
 
        <bean id="homeLocator" class="com.atlassian.refplatform.core.DefaultHomeLocator" plugin:available="true">
            <property name="propertiesFile" value="refplatform-init.properties"/>
            <property name="initPropertyName" value="refplatform.home"/>
            <property name="configFileName" value="refplatform.cfg.xml"/>
        </bean>
 
 
        <bean id="bootstrapManager" class="com.atlassian.refplatform.web.setup.DefaultBootstrapManager">
            <property name="homeLocator">
                <ref local="homeLocator"/>
            </property>
        </bean>
 
    </beans>

applicationContextPlugins.xml

This file holds all the beans required by the Atlassian® Plugins Framework and gets loaded by our special BootstrappedContextLoaderListener.

Most of the beans listed in this file are provided by the plugins framework and have to do with iniializing the OSGi system. For that reason, I’ll only cover the customized beans in this file.

Lines 11-24 define the pluginManager. This is a very simple extension of the DefaultPluginManager provided by Atlassian® and is the class used to initialize the entire plugin system.

11
12
13
14
15
16
17
18
19
20
21
22
23
24

    <bean id="pluginManager" class="com.atlassian.refplatform.plugins.RefPlatformPluginManager" plugin:available="true">
        <constructor-arg index="0" ref="pluginStateStore"/>
        <constructor-arg index="1">
            <list>
                <ref bean="classpathPluginLoader"/>
                <ref bean="bundledPluginLoader"/>
                <ref bean="directoryPluginLoader"/>
            </list>
        </constructor-arg>
        <constructor-arg index="2" ref="moduleDescriptorFactory"/>
        <constructor-arg index="3" ref="pluginEventManager"/>
        <constructor-arg index="4" ref="hostContainer"/>
        <constructor-arg index="5" ref="pluginDirectoryLocator"/>
    </bean>

Lines 26-28 define the pluginDirectoryLocator. This interface/class provides methods for looking up the various plugin paths that the framework needs. i.e. bundled, plugins, and cache directories.

This is a convenience class that we’ll use in other beans instead of passing a bunch of strings around.

26
27
28

    <bean id="pluginDirectoryLocator" class="com.atlassian.refplatform.plugins.DefaultPluginDirectoryLocator">
        <constructor-arg ref="homeLocator"/>
    </bean>

A little futher down on line 83 we define the bundledPluginLoader. This is a factory bean that returns a provided BundledPluginLoader. We have created our own factory here that can make use of our pluginDirectoryLocator.

Note that the last constructor arg is the name of our bundled plugins zip file. If you change the finalName property in the pom (maven-seembly-plugin), you’ll need to update this arg as well.

83
84
85
86
87
88
89
90
91
92
93
94

    <bean id="bundledPluginLoader" class="com.atlassian.refplatform.plugins.loader.BundledPluginLoaderFactory">
        <constructor-arg index="0" ref="pluginDirectoryLocator"/>
        <constructor-arg index="1">
            <list>
                <ref bean="osgiPluginFactory"/>
                <ref bean="osgiBundleFactory"/>
                <ref bean="xmlDynamicPluginFactory"/>
            </list>
        </constructor-arg>
        <constructor-arg index="2" ref="pluginEventManager"/>
        <constructor-arg index="3" value="atlassian-bundled-plugins.zip"/>
    </bean>

Jumping to line 146 we define the servletContextFactory bean. This is just a simple implementation that can be autowired with and return the servletContext.

146

    <bean id="servletContextFactory" class="com.atlassian.refplatform.web.servlet.RefPlatformServletContextFactory" autowire="byType"/>

Line 150 defines the hostContainer This is a class reuiqred by the plugins framework to create and return plugin modules. Our implementation simply pulls them out of the spring context.

150

    <bean id="hostContainer" class="com.atlassian.refplatform.plugins.RefPlatformHostContainer"/>

Finally, lines 154-168 define some string values for use in other beans. All of these strings are created through various spring factory beans.

154
155
156
157
158
159
160
161
162
163
164
165
166
167
168

    <bean id="applicationKey" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
        <property name="staticField" value="com.atlassian.refplatform.util.RefPlatformUtils.APPLICATION_KEY"/>
    </bean>
 
    <bean id="pluginDescriptorFilename" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
        <property name="staticField" value="com.atlassian.refplatform.plugins.DefaultPluginDirectoryLocator.PLUGIN_DESCRIPTOR"/>
    </bean>
 
    <bean id="pluginCacheDirectory" factory-bean="pluginDirectoryLocator" factory-method="getPluginCachesDirectory"/>
 
    <bean id="pluginDirectory" factory-bean="pluginDirectoryLocator" factory-method="getPluginsDirectory"/>
 
    <bean id="characterEncoding" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
        <property name="staticField" value="com.atlassian.refplatform.util.RefPlatformUtils.DEFAULT_CHARACTER_ENCODING"/>
    </bean>

That wraps up the webapp module. Now on to the core module

The Core Module

As you can see, the core module contains a lot of files but don’t worry as most of these are simply default implementations/extensions of classes provided by the Atlassian® Plugins Framework.

I’ll save you the excruciatingly boring overview of every file and just jump right to the pom.

This makes the post look a bit uglier, but come on, take the .7 second and scroll dear reader, scroll.

Core POM

Once again, the top of the pom is pretty normal, just inherits the parent pom and sets the project details.

Running ANT inside of Maven? This is a joke, right??

No joke… On lines 16-44 we’re including the maven-ant-run plugin and telling it to run the build-utils.ant file located in our etc folder.

This is going to generate a new java source file in our generated-sources folder called BuildUtils.java

This class will be used by our other classes to grab the version number and build date of our app mainly for logging purposes.

pom.xml

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <executions>
                    <execution>
                        <id>generate-version-class</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <tasks>
                                <ant antfile="src/main/etc/build-utils.ant" inheritAll="false" inheritRefs="false">
                                    <property name="version" value="${project.version}"/>
                                    <property name="src.dir" value="${project.build.directory}/generated-sources"/>
                                </ant>
                            </tasks>
                            <sourceRoot>
                                ${project.build.directory}/generated-sources
                            </sourceRoot>
                        </configuration>
 
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

etc/build-utils.ant

The build-utils.ant file is a very simple script that simply echoes a small java source file to our generated-sources folder which will then be compiled by maven.

The script has a single target named generate-version which is the default target. The script expects the version and path to generated-sources to be passed in.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

<project basedir=".." default="generate-version">
    <target name="generate-version">
        <tstamp>
            <format property="build.date" pattern="MM/dd/yyyy HH:mm:ss"/>
        </tstamp>
 
        <mkdir dir="${src.dir}/com/atlassian/refplatform/core/util/"/>
        <echo file="${src.dir}/com/atlassian/refplatform/core/util/BuildUtils.java">package com.atlassian.refplatform.core.util;
            /** Automatically generated by ant. */
            public class BuildUtils {
            private static final String VERSION = "${version}";
            private static final String BUILD_DATE = "${build.date}";
 
            public static String getCurrentBuildDate()
            {
            return BUILD_DATE;
            }
 
            public static String getCurrentVersion()
            {
            return VERSION;
            }
 
            }
 
        </echo>
    </target>
</project>

Core Dependencies

The rest of our pom just contains the required dependencies for our core project.

These contain the Spring Framework, the Atlassian-Spring bridge, the Atlassian® Plugins Framework and some base plugins we need.

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

    <dependencies>
 
        <dependency>
            <groupId>com.atlassian.spring</groupId>
            <artifactId>atlassian-spring</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-core</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-webfragment</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-webresource</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-servlet</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-osgi</artifactId>
        </dependency>
 
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-spring</artifactId>
        </dependency>
 
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <scope>provided</scope>
        </dependency>
 
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring</artifactId>
        </dependency>
 
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-log4j12</artifactId>
        </dependency>
    </dependencies>

Onto the code… I’ll start with the BootstrapLoaderListener which is the starting point of our app.

BootstrapLoaderListener

This class runs when our webapp context is initialized. It’s responsible for doing any setup that our app needs to run. In our case it ensures our home directory exists, however this is the class to customize if you need to do database setup or other tasks.

Let’s take a look at the only functional method: contextInitialized:

line 25: Create a Spring context by loading our applicationContextBootstrap.xml file

line 28: Bootstrap the app with the help of our BootstrapUtils class.

30
31
32
33
34
35
36
37
38
39
40
41

    public void contextInitialized(ServletContextEvent event) {
        ApplicationContext bootstrapContext = new ClassPathXmlApplicationContext(new String[]{"applicationContextBootstrap.xml"});
 
        try {
            BootstrapUtils.init(bootstrapContext, event.getServletContext());
        } catch (BootstrapException e) {
            log.error("An error was encountered while bootstrapping atlas-webappkit (see below): \n" + e.getMessage(), e);
        }
 
        startupLog.info("Starting Atlassian RefPlatform " + BuildUtils.getCurrentVersion());
 
    }

BootstrapUtils

In the previous code, we delegated the bootstrapping to a BootstrapUtils class.

This is a convenience class to encapsulate the initialization of the bootstrapManager and the homeLocator and provides a place to store/retrieve our bootstrap spring context

Not a very interesting class, but the init method is worth reviewing.

line 27: Get our homeLocator and try to set the home path from the servlet context if available.

line 29: Store the bootstrap spring context so other classes can get to it easily.

lines 30-35:Get the bootstrapManager from the context and initialize it.

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

    public static void init(ApplicationContext bootstrapContext, ServletContext servletContext) throws BootstrapException
    {
        ((HomeLocator)bootstrapContext.getBean("homeLocator")).lookupServletHomeProperty(servletContext);
 
        setBootstrapContext(bootstrapContext);
        BootstrapManager bootstrapManager = getBootstrapManager();
        if (bootstrapManager == null){
            throw new BootstrapException("Could not initialise boostrap manager");
        }
 
        bootstrapManager.init();
 
        if (!bootstrapManager.isBootstrapped()){
            throw new BootstrapException("Unable to bootstrap application: " + bootstrapManager.getBootstrapFailureReason());
        }
    }

HomeLocator

It’s now time to review the HomeLocator. We have the HomeLocator interface and an implementation called DefaultHomeLocator.

This class is responsible for, as it’s name suggests, locating the application’s home directory. To do this it looks in the following places in the following order:

1. A System Property named refplatform.home (defined in applicationContextBootstrap.xml)
2. The refplatform.home property defined in refplatform-init.properties
3. The refplatform.home property defined as a servletContext init parameter.

Since this class simply returns the value found in one of these places and does not actually create the directory I won’t bother listing it’s contents here.

BootstrapManager

Like the HomeLocator, the BootstrapManager is and interface with a DefaultBootstrapManager implementation.

For our purposes, the BootstrapManager is simply responsible for getting the home path from the HomeLocator and creating the directory if it doesn’t already exist.

We’ve de-coupled all of this functionality so that custom implementations can be easily provided in case more steps are needed in the bootstrap process.

Again, this class is not listed here since it’s fairly straightforward. See the source provided for the full details.

BootstrappedContextLoaderListener

In the context of running the app, at this point the bootstrap is complete and an empty home directory has been created if needed. Now it’s time to init the plugin system and load any app-sepcific Spring contexts

This is the function of the BootstrappedContextLoaderListener which is an extension of the provided ContainerContextLoaderListener.

Our custom implementation provides some extra functionality to merge our bootstrap context with the other provided Spring contexts and initializes the plugin system.

lines 28-42 – canInitialiseContainer: simply ensure we’ve been bootstrapped before loading the contexts

28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

    @Override
    public boolean canInitialiseContainer() {
        BootstrapManager bootstrapManager = BootstrapUtils.getBootstrapManager();
 
        if (bootstrapManager == null) {
            return false;
        }
 
        if (!bootstrapManager.isBootstrapped()) {
            return false;
        }
 
 
        return true;
    }

lines 44-47 – override the getNewSpringContainerContext method to return a custom BootstrappedContainerContext (listed later)

44
45
46
47

    @Override
    protected SpringContainerContext getNewSpringContainerContext() {
        return new BootstrappedContainerContext();
    }

lines 52-55 – override the createContextLoader method to return a custom BootstrappedContextLoader (listed later)

52
53
54
55

    @Override
    public ContextLoader createContextLoader() {
        return new BootstrappedContextLoader();
    }

lines 57-65 – a little more interesting… Our context is initialized and so we pull our pluginManager bean out of the context and call it’s init method which kicks off the entire plugin framework initialization

58
59
60
61
62
63
64
65
66

    @Override
    protected void postInitialiseContext(ServletContextEvent event) {
        super.postInitialiseContext(event);
 
        ApplicationContext ctx = WebApplicationContextUtils.getWebApplicationContext(event.getServletContext());
        RefPlatformPluginManager pluginManager = (RefPlatformPluginManager) ctx.getBean("pluginManager");
 
        pluginManager.init();
    }

BootstrappedContainerContext

This is a simple extension of the provided SpringContainerContext in whic we simply override the refresh method so that we can use our custom BootstrappedContextLoader to reload the application context

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

    public synchronized void refresh()
    {
        ContextLoader loader = new BootstrappedContextLoader();
 
        // if we have an existing spring context, ensure we close it properly
        ApplicationContext ctx = WebApplicationContextUtils.getWebApplicationContext(getServletContext());
 
        if (ctx != null)
        {
            loader.closeWebApplicationContext(getServletContext());
        }
 
        loader.initWebApplicationContext(getServletContext());
 
        if (getApplicationContext() == null)
        {
            setApplicationContext(WebApplicationContextUtils.getWebApplicationContext(getServletContext()));
        }
 
        contextReloaded();
    }

BootstrappedContextLoader

This is a simple extension of the Spring provided ContextLoader class that overrides the loadParentContext and uses our BootstrapUtils class to return our previously loaded bootstrap context. This essentially makes the bootstrap context beans available to all other contexts.

17
18
19
20
21

    @Override
    protected ApplicationContext loadParentContext(ServletContext servletContext) throws BeansException
    {
        return BootstrapUtils.getBootstrapContext();
    }

The other custom classes

During the explanation of the applicationContextPlugins.xml file, I mentioned a few other custom classes that we haven;t covered. Specifically these are:

• BundledPluginLoaderFactory
• RefPlatformHostContainer
• RefPlatformPluginManager

I’m not going to go into detail on these classes since they are simple extensions of Atlassian® provided default classes that just add the ability to make use of our PluginDirectoryLocator.

That being said, it is worth covering the PluginDirectoryLocator itself…

DefaultPluginDirectoryLocator

This class is responsible for determining and creating the bundled plugins, user added plugins, and plugins cache directories.

This class gets the homeLocator injected into it to use as the base path for all of the above mentioned folders.

Although the implementation is very simple, I wanted to list it since this is the place you can customize where plugins get added/stored.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

    private static final String BUNDLED_PLUGINS_DIRECTORY = "bundled-plugins";
    private static final String DIRECTORY_PLUGINS_DIRECTORY = "plugins";
    private static final String PLUGIN_CACHES_DIR_NAME = "caches";
    public static final String PLUGIN_DESCRIPTOR = "atlassian-plugin.xml";
 
    private final HomeLocator homeLocator;
 
    public DefaultPluginDirectoryLocator(final HomeLocator homeLocator)
    {
        this.homeLocator = homeLocator;
    }
 
    public File getPluginsDirectory()
    {
        return getHomeSubDirectory(homeLocator, DIRECTORY_PLUGINS_DIRECTORY);
    }
 
    public File getBundledPluginsDirectory()
    {
        return getHomeSubDirectory(homeLocator, BUNDLED_PLUGINS_DIRECTORY);
    }
 
    public File getPluginCachesDirectory()
    {
        return getHomeSubDirectory(homeLocator, PLUGIN_CACHES_DIR_NAME);
    }
 
    public String getPluginDescriptorFilename() {
        return PLUGIN_DESCRIPTOR;
    }
 
    private File getHomeSubDirectory(HomeLocator homeLocator, String subDirectory)
    {
        File homePath = new File(homeLocator.getHomePath());
        File directory = new File(homePath, subDirectory);
 
        if (!directory.exists())
        {
            directory.mkdir();
        }
 
        return directory;
    }

Non-Used Classes

In the source tree there are 2 classes that aren’t currently used.

• RefPlatformModuleDescriptorFactory
• AbstractRefPlatformModuleDescrptor

These classes are here in case you want to add “built-in” plugins to your app.

To do so, simply replace the

<bean id="moduleDescriptorFactory" class="com.atlassian.plugin.DefaultModuleDescriptorFactory">

in the applicationContextPlugins.xml file with

<bean id="moduleDescriptorFactory" class="com.atlassian.refplatform.plugins.descriptor.RefPlatformModuleDescriptorFactory">

In the RefPlatformModuleDescriptorFactory you can then add any custom module descriptors you want to provide to your app

    public RefPlatformModuleDescriptorFactory(HostContainer hostContainer) {
        super(hostContainer);
 
        //you can add any custom plugins here:
        // addModuleDescriptor("myCustomPlugin",MyCustomModuleDescriptor.class);
    }

Each module descriptor you add should extend AbstractRefPlatformModuleDescriptor

For a (very) little more on module descriptors, see: http://confluence.atlassian.com/display/PLUGINFRAMEWORK/Quick+Start+Guide+to+Embedding

Building the app

So now that we have all the build and source files, you should be able to easily build and run this with a few short maven steps:

1. Run the install goal on atlas-webappkit-core
2. Run the package goal on atlas-webappkit-webapp
3. Run the cargo:start goal on atlas-webappkit-webapp

After cargo starts up you’ll be able to see the junk jsp at http://localhost:8080/atlas-webappkit/index.jsp

Added bonus… you can access the Felix Web Console at http://localhost:8080/atlas-webappkit/plugins/servlet/system/console/

Topics Not Covered

At this point you now have an app that can bootstrap itself, create a home directory, create the plugin directories, extract any bundled plugins, load the bundled plugins, load user added plugins, and process any Spring files. HOORAY!

There are however a few things not covered by this post that I’m going to leave for other posts or for you to figure out on your own:

• Assembling a zipped tomcat with the war already exploded and ready to run
• Enabling the webapp to show a first-time setup wizard
• Using AMPS to build plugins for your custom app
• Adding other various Atlassian® plugins (i.e. rest support)

Although the above topics were left out, I hope you’ve found this post helpful.

As always, any comments, suggestions or improvements are very welcomed.

This is really cool, however, while testing rest plugins is actually pretty easy, figuring out exactly how to do it can drive a person crazy. And so I thought I’d write this post in hopes of saving others hours of research time.

The Project

For this example we’re just going to create a really simple rest resource that returns a list of the projects in JIRA.
I’m not going to walk through plugin development step-by-step but I’ll get us started…

Create a project

Let’s create our project using the Atlassian Plugin SDK.
Just open a terminal and navigate to your base workspace folder. Then run:

atlas-create-jira-plugin

When asked for the plugin name, call it jira-projects-rest

Add some Maven Dependencies

We’ll need a few libraries to help us test, just add the following to the pom dependency list

        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>jsr311-api</artifactId>
            <version>1.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.1</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.atlassian.plugins.rest</groupId>
            <artifactId>atlassian-rest-common</artifactId>
            <version>1.0.2</version>
            <scope>provided</scope>
        </dependency>
 
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.3</version>
            <scope>provided</scope>
        </dependency>
 
        <dependency>
	    <groupId>com.sun.jersey</groupId>
	    <artifactId>jersey-test-framework</artifactId>
	    <version>1.1.2-ea</version>
	    <scope>test</scope>
	</dependency>

Add the rest descriptor

Once the project is created, edit the atlassian-plugin.xml and add our rest component:

<atlassian-plugin key="${project.groupId}.${project.artifactId}" name="${project.artifactId}" plugins-version="2">
    <plugin-info>
        <description>${project.description}</description>
        <version>${project.version}</version>
        <vendor name="${project.organization.name}" url="${project.organization.url}" />
        <application-version min="4.0"/>
        <bundle-instructions>
            <Import-Package>org.apache.commons.collections,*;resolution:=optional</Import-Package>
        </bundle-instructions>
    </plugin-info>
 
    <rest key="projectsService" path="/projectfinder" version="1.0">
        <description>Provides a service that lists JIRA projects</description>
    </rest>
 
    <component key="projectFinder"
        name="Project Finder"
        class="com.sysbliss.jira.plugins.util.ProjectFinder"/>
 
</atlassian-plugin>

The guts

So in the plugin descriptor you’ll notice we have a component named “projectFinder”.
This is a simple helper class that’s not really required, but it helps to decouple our service wrapper and would make sense in a more complex plugin.

The ProjectFinder is responsible for looking up and returning our project list:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package com.sysbliss.jira.plugins.util;
 
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
 
import com.atlassian.jira.project.Project;
import com.atlassian.jira.project.ProjectManager;
 
public class ProjectFinder {
 
    private final ProjectManager projectManager;
 
    public ProjectFinder(final ProjectManager projectManager) {
	this.projectManager = projectManager;
    }
 
    public List<Project> getProjects() {
	List<Project> projects = projectManager.getProjectObjects();
	if (projects == null) {
	    projects = Collections.<Project> emptyList();
	}
 
	return projects;
 
    }
}

The service wrapper

So now we need a service wrapper. This basically contains 2 classes:

• ProjectsResource – The class that will be our jersey Resource
• RestProject – a JAXB class that represents a single project

ProjectsResource.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

 
package com.sysbliss.jira.plugins.rest;
 
import java.util.ArrayList;
import java.util.List;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.Response;
 
import com.atlassian.jira.project.Project;
import com.atlassian.plugins.rest.common.security.AnonymousAllowed;
import com.sysbliss.jira.plugins.util.ProjectFinder;
 
@Path("")
@Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
public class ProjectsResource {
 
    private final ProjectFinder projectFinder;
 
    public ProjectsResource(final ProjectFinder projectFinder) {
	this.projectFinder = projectFinder;
    }
 
    @GET
    @Path("projects")
    @AnonymousAllowed
    @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML })
    public Response getProjects() {
 
	final List<Project> projectList = projectFinder.getProjects();
	final List<RestProject> restProjectList = new ArrayList<RestProject>();
	for (final Project project : projectList) {
	    restProjectList.add(new RestProject(project.getName()));
	}
 
	final GenericEntity<List<RestProject>> entities = new GenericEntity<List<RestProject>>(restProjectList) {};
 
	return Response.ok(entities).build();
    }
}

Let’s move on to the RestProject that represents a JIRA project.
For this example, I’m just going to include the name field, but you could add all the other stuff if needed.

RestProject.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

 
package com.sysbliss.jira.plugins.rest;
 
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
 
import net.jcip.annotations.Immutable;
 
@Immutable
@XmlRootElement
public class RestProject {
 
    @XmlElement
    public final String name;
 
    public RestProject() {
	this.name = "";
    }
 
    public RestProject(final String name) {
	this.name = name;
    }
}

Unit Testing

Although I gave you the implementation code first, this was actually written test-first and I highly advise all others to do the same

At this point if all is well, we have a simple rest service in JIRA that returns a list containing RestProject objects.
The first thing we want to test is our ProjectFinder class. These will be unit tests.

Since we will need to mock out JIRA Project objects, it’s handy to write a little test utility for that.
Note: All the test classes use the Mockito framework for making mocks.

ProjectMockUtils.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

 
package com.sysbliss.jira.plugins.test.util;
 
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
 
import java.util.Collection;
 
import com.atlassian.jira.project.Project;
 
 
public class ProjectMockUtils {
 
    public static Project createMockProject(final Long id, final String name, final String key) {
	final Project project = mock(Project.class);
 
	when(project.getId()).thenReturn(id);
	when(project.getName()).thenReturn(name);
	when(project.getKey()).thenReturn(key);
 
	return project;
    }
}

And now on to the unit tests. These are pretty simple and shouldn’t require too much explanation…
Note: The unit tests are using the TestNG framework.

ProjectFinderTest.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

 
package com.sysbliss.jira.plugins;
 
import static org.mockito.Matchers.anyLong;
import static org.mockito.Matchers.eq;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
 
import java.util.ArrayList;
import java.util.List;
 
import org.testng.annotations.Test;
 
import com.atlassian.jira.project.Project;
import com.atlassian.jira.project.ProjectManager;
import com.sysbliss.jira.plugins.test.util.ProjectMockUtils;
import com.sysbliss.jira.plugins.util.ProjectFinder;
 
public class ProjectFinderTest {
 
    @Test
    public void projectsAreFound() {
	final List<Project> projects = new ArrayList<Project>();
	projects.add(ProjectMockUtils.createMockProject(1L, "Project 1", "PRJ1"));
	projects.add(ProjectMockUtils.createMockProject(2L, "Project 2", "PRJ2"));
 
	final ProjectManager projectManager = mock(ProjectManager.class);
	when(projectManager.getProjectObjects()).thenReturn(projects);
 
	final ProjectFinder finder = new ProjectFinder(projectManager);
 
	final List<Project> found = finder.getProjects();
 
	assert found.size() == 2 : "Expected 2 projects but got " + found.size();
    }
 
}

So that’s that. I’m keeping it to that one method for this example. In real life, you’d have a bunch of boundry tests, etc, etc.

Next, and equally as exciting, almost the same exact test for the resource wrapper.

ProjectsResourceTest.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

 
package com.sysbliss.jira.plugins;
 
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
 
import java.util.ArrayList;
import java.util.List;
 
import javax.ws.rs.core.Response;
 
import org.testng.annotations.Test;
 
import com.atlassian.jira.project.Project;
import com.atlassian.jira.project.ProjectManager;
import com.sysbliss.jira.plugins.rest.RestProject;
import com.sysbliss.jira.plugins.rest.ProjectsResource;
import com.sysbliss.jira.plugins.test.util.ProjectMockUtils;
import com.sysbliss.jira.plugins.util.ProjectFinder;
 
public class ProjectsResourceTest {
 
    @Test
    public void resourceProjectsAreFound() {
 
	final List<Project> projects = new ArrayList<Project>();
	projects.add(ProjectMockUtils.createMockProject(1L, "Project 1", "PRJ1"));
	projects.add(ProjectMockUtils.createMockProject(2L, "Project 2", "PRJ2"));
 
	final ProjectManager projectManager = mock(ProjectManager.class);
	when(projectManager.getProjectObjects()).thenReturn(projects);
 
	final ProjectFinder finder = new ProjectFinder(projectManager);
 
	final ProjectsResource resource = new ProjectsResource(finder);
 
	final Response response = resource.getProjects();
 
	final GenericEntity<List<RestProject>> entities = (GenericEntity<List<RestProject>>) response.getEntity();
 
	final List<RestProject> restProjects = entities.getEntity();
 
	assert (restProjects.size() == 2) : "Expected 2 projects but got " + restProjects.size();
    }
 
}

The above test is a little more interesting in the fact that it’s using our jersey resource to test that our resource classes are working properly and that we are getting the correct model objects from the Response class.

So that’s it for the unit tests. Pretty simple and doesn’t require any external connections to anything.
On to the interesting parts….

Integration Testing

The new Atlassian Plugins SDK provides some really cool stuff to help with integration testing and coupled with a few little “tricks” it’s pretty painless.

The Goal

The goal of our integration test harness is to deploy our plugin into a running JIRA instance, provide a known set of data, and actually make http requests to our new resource to verify that everything is working properly.

Before we can get started writing our test, we need to do a little setup.

Creating a dataset

We’re going to need a known set of data in our JIRA instance; namely, 2 empty projects.
The first step in creating the data is to boot up JIRA. Once again, the plugins SDK makes this easy….

Running JIRA

In a terminal, navigate to the project root and run:

atlas-run

If you’ve never run this previously, get some coffee…. maven’s going to do some web surfing for a while.
Once maven has completed, the SDK will boot up JIRA and deploy our plugin. At this point, we don’t really care about our rest resource…. we’re just going to make use of JIRA.

So now just open a browser and point it at: http://localhost:2990/jira

This will bring up JIRA and put you at the dashboard. Login using admin/admin as user/pass.

Create Projects

Finally, go to the JIRA administration section and create 2 projects. It doesn’t matter what they’re called, and they don’t need to have any issues or anything, just be sure there are 2 and only 2 projects created.

After the projects are created, use the backup to xml tool to export the data to an xml file.
The file should be saved as: [project-root]/src/test/xml/it-data.xml

That’s it. Now just CTRL-C in the terminal to shutdown JIRA.

Test Properties

We’re going to be making use of the JiraWebTest class (more on that in a bit) which requires us to make a properties file for integration testing.

Create a file: [project-root]/src/test/resources/localtest.properties
The contents of the file should be:

jira.protocol = http
jira.host = localhost
jira.port = 2990
jira.context = /jira
jira.edition = all
# Please note jira.xml.data.location needs to be the full path
jira.xml.data.location = src/test/xml/
 
jira.release.info = unknown
#
# If the browser path is set then when a test fails the func test framework will try and start
# the browser with a temporary file of captured web output.  if its not set then no harm
# and System.out will be used to dump the web response.
#
browser.path=firefox

Now our integration harness setup is complete and we can finally move on to the interesting stuff.

The Test Suite

Since we’re going to make use of the JiraWebTest, we are forced to use JUnit for the integration tests.
This requires us to create a JUnit Test Suite which is liste below.

Note: ALL integration tests must be in a test package that starts with it.[rest.of.package]

AllTests.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

 
package it.com.sysbliss.jira.plugins;
 
import junit.framework.Test;
import junit.framework.TestSuite;
 
public class AllTests {
 
    public static Test suite() {
	final TestSuite suite = new TestSuite("Integration Test for it.com.sysbliss.jira.plugins");
 
	suite.addTestSuite(ProjectsRestTest.class);
 
	return suite;
    }
 
}

What’s this JiraWebTest anyway?

JiraWebTest is a class provided by the jira-func-test package that should have been added to your pom.xml by the plugins SDK when you created the project.

It’s a class that your test classes can extend that provides extra functionality when running integration tests.
That extra functionality comes at a price though, like being forced to use JUnit… But wait, that’s not all! You can read an entire post about the pros and cons of the web test framework.

That being said, we are going to make as little use of this class as possible in hope something better comes along, however it does provide something very useful: The ability to load our exported test data.

And so, we’ll put up with it for now.

Finally, the integration test!

So here I’ll just proved the entire class and provide explanations after it.

ProjectsRestTest.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

 
package it.com.sysbliss.jira.plugins;
 
import java.io.ByteArrayInputStream;
import java.io.InputStream;
 
import javax.xml.bind.JAXBContext;
import javax.xml.bind.Unmarshaller;
 
import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.GenericType;
import com.sun.jersey.api.client.WebResource;
 
import com.atlassian.jira.webtests.JIRAWebTest;
import com.sysbliss.jira.plugins.rest.RestProject;
import com.sysbliss.jira.plugins.rest.RestProjects;
 
public class ProjectsRestTest extends JIRAWebTest {
 
    public ProjectsRestTest(final String name) {
	super(name);
    }
 
    @Override
    public void setUp() {
	super.setUp();
	restoreData("it-data.xml");
    }
 
    @Override
    public void tearDown() {
	super.tearDown();
    }
 
    public void testRestProjectsFound() throws Exception {
	final Client client = Client.create();
	final WebResource resource = client.resource("http://localhost:2990/jira/rest/projectversions/1.0/projects.xml");
 
	final List<RestProject> projects = resource.get(new GenericType<List<RestProject>>() {});
	assertEquals(2, projects.size());
    }
}

Extend JiraWebTest

line 18:
we simply extend JiraWebTest to give us our data loading functionality

line 21:
make sure you call super() !

lines 24-28:

• override the setUp method
• call super.setUp()
• call restoreData(“it-data.xml”); – this loads our test data before each test

lines 30-33:
Make sure you override tearDown and call super.tearDown();

lines 36-37:

• create a jersey Client
• create a WebResource with our resource url

line 39:
Execute our GET request and cast the response to our model using the GenericType provided by jax-rs

line 40:
We can now use our model objects to assert that our request returned the 2 project objects we have in our test data.

Running the tests

whew, we’re finally ready to actually run the tests… plugins SDK anyone?

Drop out to a terminal in the project root and run:

atlas-integration-test

Sit back and enjoy as you watch the following whiz (well, maybe half-walk/half-jog) by you:

• Project is compiled and unit tests are run
• JIRA is started and the plugin is automatically deployed
• admin logs into JIRA and imports our test data
• we are welcomed to the Hotel California
• framework verifys JIRA is ready to run the integration tests
• The integration tests are run
• JIRA shuts down

The crowd rejoices

Although this article is a bit verbose, once you set this up, doing it again for other projects is a breeze and the feeling you get seeing the “build successful” at the end never get old.

Hope this was helpful…

For now, you can download the repository installer and poke around if you wish.

To install, download and extract the tar.gz file.  Move the extracted contents to the webserver you wish to use for your repository and run ant -f sysbliss-repo-installer.xml

Just follow the prompts and your repo will be setup.

More on using the system later.

Download Sysbliss Repo Installer

This post serves both as a quick tutorial on setting up bamboo as a release management system as well as a scenario that illustrates how the plugins can be used within a release workflow.

Scenario

Project Information

In our scenario, we will be building a fictitious web app project.
This project will be using an iterative/agile development process.
We will have:

• 3 development iterations
• 2 release candidates
• 1 production release
• 1 emergency bugfix release.

Bamboo Project Information:

Deployment

Since we’re building a webapp, we need to deployment workflow for when and where different builds get deployed.
Figure A. shows our logical deployment workflow. The actual physical deployment all happens from the Bamboo server via shell scripts.

Figure A. Logical Release Deployment

Versioning

Our project will use the following version number scheme:

[Major].[Minor].[Bugfix]-[type][iteration]-[build]

Using this scheme, our project will produce the following final version numbers (with multiple build versions in-between)

• 1.0.0-dev1 – development iteration 1
• 1.0.0-dev2 – development iteration 2
• 1.0.0-dev3 – development iteration 3
• 1.0.0-rc1 – release candidate 1
• 1.0.0-rc2 – release candidate 2
• 1.0.0 – first production release
• 1.0.1 – emergency production bugfix release

Installation

Installation is simple….
Assuming you already have Jira and Bamboo installed and running:

Just download the 3 distrubution jars from the respective plugin pages and drop them into your ${BAMBOO_INSTALL}/webapp/WEB-INF/lib folder.

• Jira Versions Plugin
• Bamboo Tagger Plugin
• Pre-Post Build Command Plugin

now just restart bamboo.

Project Setup

Version Your Package

Most software built today is compiled and packaged with some sort of automated tool. I’m sure there are a few die-hards that are still using vi and javac on the command-line but for the rest of us not living in the eighties, we’re using something like ant, maven, etc.

To that end, the jiraversions plugin was written to be compatible with almost every automated builder known today. This is accomplished by the use of parameters that can be passed to the builder of choice via the command-line. (how that gets done will be discussed shortly).

So the first thing we need to do is setup our build script to figure out which version it’s building and use it as part of the package name.

note: for simplicity’s sake, I’m going to use Ant in the examples, but the same method can be applied to anything that can run via a command line. I’m also going to use java as the language of choice, but again, bamboo and the plugins mentioned in this post can be used to build anything.

Assuming you already have targets that compile and jar up your project, we just need to add a target that gets the current version for the build and sets it as a property that can be used to append to the name of your jar file.

<target name="get-version" unless="version.name">
    <tstamp>
        <format property="build.time" pattern="yyyyMMdd_HHmmss" />
    </tstamp>
    <property name="version.name" value="${user.name}-${build.time}" />
    <property name="version.type" value="user" />
    <property name="version.released" value="false" />
</target>

Essentially this target is here to handle builds done on a local developer’s machine.
It’s saying that if version.name was not passed on the commandline (or set some other way) then set default version properties.
The most interesting property is the version.name which will be set to the user’s username and a timestamp.
i.e. if I do a build on my local machine, the version will look something like: jdoklovic-2008-Aug-01_130923

Now we need to make sure that our final artifact is named properly. Usually you’ll have some sort of package target that handles spitting out the final artifact.
In our case the packaging looks like this:

<target name="package" depends="create-war" />
 
<target name="create-war" depends="compile,get-version">
    <property name="warfile" value="${ant.project.name}-${version.name}.war"/>
    <property name="warfile.path" value="${dist.dir}/${warfile}"/>
    <war warfile="${warfile.path}">
        <!-- add the rest of the war task specifics here -->
    </war>
</target>
 
<target name="auto-build" depends="checkbamboo,test,package,publish" />

So there are a few things going on here.
First, we have a target called package that simply depends on a target called create-war.

Although this isn’t really neccessary, it’s useful to have common target names across multiple projects. So if I had another project that creates a jar or a zip file, you would simply adjust the depends on the package target in that project. This way the lazy developers can always rely on running the package target regardless of what it actually spits out.

Next we have our create-war target.
This target depends on a compile target (which aptly named, compiles our project) and the get-version target we defined previously.
When it creates the war, it uses the ant project name and the version.name as the name of the war file. (real exciting, huh?)

Finally we have a target called auto-build.
I include this target in any of my ant files that will be called from Bamboo. Again, this just makes it simpler to setup in bamboo since you don’t need to think about which target to run.
This target can do anything you want it to and in my example I’ve included the bare minimum that I usually need a build to do…..

• checkbamboo – this simply checks that ${user.name} is equal to the name of the user that bamboo runs as, and fails if it doesn’t.
• test – runs unit tests and generates reports
• package – runs our package target
• publish – publishes our artifact to our dependency management system (i.e. apache ivy, a maven repo, what have you)

Some may wonder why the checkbamboo target exists and if it’s really useful. Although it’s very easy to get around, it’s there as a sanity check when developers are doing builds on their local machines and ensures that a developer does not accidentally publish a locally built artifact to the repository.

Obviously this is not a real and/or complete build file. It’s simply here to illustrate a basic outline of what’s needed for the automation to work.

Got Versions?

Our next order of business is to get versions setup in Jira.

There’s nothing special here….  simply create a Jira Project, go into the manage versions screen and add the proper versions.
Make sure all of the versions start out as Unreleased and are in the proper order. Bamboo will use the order provided by Jira to determine the latest version.

For our scenario, I’ve setup a Jira Project named “My Web App” with the key WEBMYAPP

My versions initially end up looking like this: (note: waiting to add the bugfix version till later)

On To Bamboo

The last part of the setup is to configure our project in Bamboo. I’ve already setup my project with the Project Info listed at the beginning of this post, and have tied it to version control (specifically subversion).

Now it’s time to start configuring the JiraVersions plugin. The first screen we need is in the Configuration > Builder tab. Naviagte to there and click Edit Plan.

In the main Builder configuration, select Ant as your builder and put build.xml in the Build File box.
Now in the Target box, let’s add our build target and pass the version properties our build is expecting:

autobuild -Dversion.name=${bamboo.custom.jiraversion.name} -Dversion.released=${bamboo.custom.jiraversion.released} -Dversion.type=${bamboo.custom.jiraversion.type}

Our builder ends up looking something like:

Scrolling down on this same screen, click the “Enable Jira Versions” checkbox and the Jira Versions options will appear.

General Settings
First we need to let Bamboo know where to find our Jira Project by giving it the Jira Project key. You can click the test button to see if it Bamboo can find the project in the Jira server.

Next, set the Default Version Strategy to “Current Unreleased Version”. This tells Bamboo to ask Jira for the current unreleased version during “normal” operation. We’ll see how to override this later for a single build.

The Null Version strategy tells Bamboo what to do if Jira either has no versions setup, or none of the versions are unreleased (resulting in a null version returned).

The best idea is to set this value to “Skip and Pass Build” which will mark the build as successful but not actually build anything.

note: if we set it to fail the build, then builds that are fully released will fail just because there are no open/unreleased versions which might cause unwanted results in your project dependency chain.

In the future, you’ll have even more options…. (BJVER-6).

Now we can setup our version appenders. These let you append any string on to the version name before it gets expanded by any other fields. In our scenario, we’re going to append the full Bamboo build key (including the number) to the end of unreleased version names.

To do this, set the Unreleased Appender field to: -${bamboo.buildResultKey}
We’ll just leave the released appender field blank.

Version Types

The version types section allows you to add keywords that will be searched for in the version name and used as the type of release.
The searching uses a similar algorithm as the php version_compare function.

In our scenario we just need to setup dev and rc keywords.

We’re now done configuring the Builder section, so we can click the save button at the bottom of the screen and move on to the Post Actions tab.

Post Build Commands

Uner the Post Build Commands in the Post Actions tab, we need to add a Success Command.

This will be the absolute path on the Bamboo server to the shell script that will be responsible for deploying our app to the various servers.

We will setup the script to accept the properties set by the JiraVersions plugin as well as the Bamboo build result key so we need to pass them to the script here.

/opt/bamboo/deploy-scripts/deploy-webapp.sh -n ${bamboo.custom.jiraversion.name} -r ${bamboo.custom.jiraversion.released} -t ${bamboo.custom.jiraversion.type} -k ${bamboo.buildResultKey}

Tagging

Below the Post Build Commands, we can enable the Jira Versions Tagger which will allow us to make tags in our scm system based on some parameters.

In our scenario, we only want to tag successful builds, and since we’re using subversion, we’ll need to tell Bamboo where the tags should be made.

Finally, we only want Bamboo to tag Released versions of each version type.

That’s it for the configuration. Just one more thing to do before we get to the workflow:

Create the Deploy Script

Our deploy script will be responsible for figuring out which environment(s) to deploy to based on the input parameters. The deploy worflow image at the beginning of this post shows what gets deployed to where.

Create a file in the same path as we defined in the post build command. In our case, we will create: /opt/bamboo/deploy-scripts/deploy-webapp.sh

It should contain something similar to the following code:

#!/bin/bash
 
# parameter examples:
#  -n 1.2.0-dev1
#  -r false
#  -t dev
#  -k MY-WEBAPP-3
 
set -x
 
version=""
release=""
version_type=""
build_key=""
release_env=""
 
mypath=`dirname "$0"`
 
DEV_ENV="dev.mydomain.com"
QA_ENV="qa.mydomain.com"
BUG_ENV="bugfix.mydomain.com"
STAGE_ENV="staging.mydomain.com"
 
BAMBOO_HOME="/opt/bamboo/bamboo-home"
dist_dir="$BAMBOO_HOME/xml-data/build-dir/WEB-MYAPP/dist"
 
 
# ~~~~~~~~~~~~~~~~
#   Functions
#     
# ~~~~~~~~~~~~~~~~
 
usage(){
 
   cat <<EOF
    usage [-opts] deploy-webapp.sh
 
     -n [version number] (might be blank) (ex. 1.0.1-dev1)
     -r [released] (ex. true|false )
     -t [version type] (might be blank) (ex. dev, rc, blank for prod)
     -k [build key] 
 
EOF
 
}
 
deploy () {
 
   set -x
 
   env=$1
 
   cd $dist_dir
 
   box_list=$(eval echo \$"${env}_ENV")
 
   for i in $box_list
   do
 
    # Move new war file out and stop web services
    #
    scp $artifact_name tomcat@${i}:/var/tmp/
    ssh tomcat@${i} sudo monit stop tomcat_8080
    sleep 5s
 
    # Clean up any leftover Java processes (that were not killed by monit)
    # Move the new war file into the proper place
    #
    ssh tomcat@${i} killall -u tomcat java
    ssh tomcat@${i} mv /var/tmp/${artifact_name} /var/tomcat/apache-tomcat-6.0.16/webapps/my-webapp.war
    sleep 5s
 
    # Start up webapp
    #
    ssh tomcat@${i} sudo monit start tomcat_8080
 
   done
 
}
 
# ~~~~~~~~~~~~~~~~
#   Main
#
# ~~~~~~~~~~~~~~~~
 
# Get arguments (passed in from bamboo)
#
if [ $# -ge 1 ]; then
 
    while getopts :r:n:t:k: zz; do
        case $zz in
        n)   version=$2 ;;
        r)   release=$4   ;;
        t)   version_type=$6  ;;
        k)   build_key=$8 ;;
 
        *)   usage; exit 2 ;;
        esac
    done
    shift `expr $OPTIND - 1 `
fi
 
# If no version number, just exit
#
if [ ${#version} -eq 0 ]; then
 
   echo -e "(`date`) ERROR - no version number - exiting..."
   exit 1
fi
 
# Check if this is a release or not
#
if [ "${release}" == "true" ]; then
 
     artifact_name="my-webapp-${version}.war"
 
     case $version_type in
 
	#released non-production versions go to DEV and QA
        dev|rc)
              release_env="DEV,QA"
              ;;
 
	#released production versions go to STAGE
        *)
            release_env="STAGE"
              ;;
     esac
else
     case $version_type in
 
        #Un-Released non-production versions go to DEV
        dev|rc)
            release_env="DEV"
            ;;
 
        #UN-Released production versions go to BUGFIX
        *)
            release_env="BUG"
            ;;
     esac
 
fi
 
# Release code to requested environments
#
for i in $release_env
do
    echo -e "\t\t(`date`) Releasing to $i"
    deploy $i
done

Go With The Flow

Now that everything is setup, we’re ready to go through the basic development cycle workflow.

This is pretty straight forward with only a few things to watch out for…..

So let’s get started. Per our versions, we’re starting with iteration 1 of our webapp project.

Generally, we will be adding new features in our iterations based on User Stories that are entered into Jira.

As we close out Jira issues and commit code, Bamboo will build our unreleased dev1 version for us.

We can check the status of all version builds by going to the Jira Versions tab for our build plan. After the first checkin, the Jira Versions will look somethin like the following:

After our iteration is finished, it’s time to release dev1. This is a 2 step process.

First, go into the manage versions screen in Jira and click the release link next to the 1.0.0-dev1 version.

Second, go to the Jira Versions tab in Bamboo. We will now see the released dev1 version with a link that will let us do a manual build.

We need to kick off the build manually because Bamboo is now going to be building the un-released dev2 version when code commits happen. Thus, it is important to do this manual build as soon as you release the version in Jira to make sure that no commits happen after the release.

At this point, we just follow this same process for all of our iterations. When we are ready to release the final iteration version, we need to do one extra step: merge the dev versions into the first release candidate.

Merging will do a couple of things for us. It will allow users to see everything that has been included in the release candidate. It will also remove the merged version from the Jira Versions tab in Bamboo.  This makes it impossible for someone to accidentally re-build an already released dev version.

You can still get to the old builds by going to the Completed Builds tab in bamboo.

To merge, you simply use the merge links in the Manage Versions section of Jira.

Once our iterations are complete and we move on to the first release candidate, the workflow remains the same… commit, Babmoo builds, release when ready.

When we reach the point of releasing the final release candidate, we again need to merge. This time we will merge all of the rc versions into the production version. From here, we just go along the workflow as normal and release the production version when ready.

Throughout the development cycles, you shee see the following:

• Builds appearing in the Jira Versions tab
• Un-released versions being deployed to the development server.
• Released versions being deployed to the development and QA servers
• Released versions being tagged in subversion
• Un-released Production builds being deployed to the bugfix server
• Released Production build deployed to the staging server.

If everything is good to go on the staging server, we can then manually deploy it to the actual production server. This is left as a manual process just to ensure that a human is watching the process and making sure it goes ok.

Finally, if there are emergency bugs that need to be fixed in production without a full development cycle, we can simply add a new version in Jira called 1.0.1

From there, we just do the normal process of committing code, releasing when ready, manually building the released version and manually deploying from staging to production.

And there you have it. However, there’s more……

Beware of Null Versions
We have our build set to pass with success if there are no versions returned from Jira. This is useful for dependency builds that need to complete within a larger build tree, however, this means a new development rule must be followed:

No code should be committed to a project without an unreleased version.

If code is committed, bamboo will see the change in the scm and try to run a build, but since no version will be returned by Jira, it will simply do nothing but look successful.  This is not the optimal scenario and BJVER-6 aims to make this a little more fool proof.

It’s also a good idea to create a subversion commit hook that checks Jira for an unreleased version and fails the commit if it doesn’t find one.

I will post a link to the subversion pre-commit hook once I get it finished.

I hope this post was helpful.

From the announcement:
This is terrific plugin that enables all sorts of new possibilities for Bamboo. It’s one of those gateway plugins that opens up a whole new category of customizations.

The full announcement can be viewed on the Atlassian Blog

Finally, I found a solution that works…. here it is (Assuming you already have dovecot-sieve working):

Software:

Debian etch
Dovecot 1.0.13 (with dovecot common)
Horde 3.2-RC2
Ingo 1.2-RC2

Step 1: Setup proper permissions

For Ingo to be able to write out sieve scripts, the apache user needs permissions to write to the Maildir folders.
I did this by simply adding the www-data user to the vmail group.

:# adduser www-data vmail
:# /etc/init.d/apache2 restart

This will give www-data permissions to write to the Maildir folders (owned by vmail:vmail) but if we just let Ingo create the scripts from scratch, they will be owned by www-data:www-data and vmail won’t be able to use them.

To correct this, just make sure you create an empty .dovecot.sieve when the user’s Maildir folder is created.

I handled this by adding:

touch $2/Maildir/.dovecot.sieve

to my /usr/bin/maildirmake script.

Step 2: Setup Ingo Backend

In the horde/ingo/config directory, there is a file called backends.php. This file by default contains a bunch of different entries that tell Ingo how to store the mail filters.

For Ingo to actually work, there should only be one entry in this file (as I’m told). So for starters, just delete all of the entries in this file.

Now that we have a clean backends.php, we need to add an entry to tell Ingo where and how to save our .dovecot.sieve scripts.

There are many options for storage but the simplest for our purposes is to just use the filesystem.
To enable this, add the following entry to the file

$backends['dovecot'] = array(
    'driver' => 'vfs',
    'hordeauth' => true,
    'params' => array(
        'filename' => '.dovecot.sieve',
        'vfsroot' => '/var/vmail',
        'vfs_path' => '/example.com/%u/Maildir',
        'vfstype' => 'file'
    ),
    'script' => 'sieve',
    'scriptparams' => array(),
);

This should all be pretty self-explanatory, but you’ll notice on line 7, we’re hardcoding the domain. This is because Ingo will expand %u as the user, but it does not currently expand any variable as the domain. (i.e. %d)

See Domain Workaround Below

That’s it. If you now log into horde and create/edit filters, they should be saved to the .dovecot.sieve file in the user’s Maildir. Pretty simple, and now documented.

Enjoy.

The bamboo 1.2.4 version was updated so PRE-build commands can now be specified.

A new 2.0 version was created as well.

We use Atlassian Bamboo as our continuous build server and for a while I’ve wanted to kick off arbitrary command line commands after a build is completed. Apparently some other developers have been asking for this as well: BAM-679.

In response, I’ve written this plugin that can run an arbitrary command when a build passes or fails. The pass and fail commands are specified on the Post Actions configuration page.

The plugin is now hosted on the Atlassian Developer Network.
Please visit the plugin homepage.