Atlassian® as a Web-App Framework

December 31, 2009, 1:11 pm

News Flash: I’m a big fan of Atlassian®.

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

Although I’ve called it the Atlas Webapp Kit, I am in no way associated with Atlassian®.
This Project is solely a result of my own tinkering.

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

refplatform-webapp-structure

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}

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

            <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

             <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

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

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

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

    <!-- ============ 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.

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

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

The bootstrap context only contains the required beans to create the home directory.
In a “real” app, you may add more beans to this file to handle things like database setup, etc.

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.

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

Note the reference to the homeLocator bean we defined in the previous bootstrap context.

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.

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

    <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

refplatform-core-structure

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

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

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

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

    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.

    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:

A System Property named refplatform.home (defined in applicationContextBootstrap.xml)
The refplatform.home property defined in refplatform-init.properties
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

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

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

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

    @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

    @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

    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.

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

    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:

Run the install goal on atlas-webappkit-core
Run the package goal on atlas-webappkit-webapp
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.

Share this post:

Category: General Development, atlassian | Comment (RSS) | Trackback

7 Comments

Jessica Doklovic:

spoiler alert U == dork
December 31, 2009, 1:41 pm
cburleson:

This is a great post, overflowing with value. Thanks so much for taking the time to share your detailed journey. I intend to go through this carefully soon to see what parts might be applicable to a J2EE Reference Architecture I am working on. It seems that you may be a little too closely tied to some Atlassian dependencies for my taste. But… this is very educational.
January 1, 2010, 7:02 pm
Wim Deblauwe:

Why are you creating this Java class on the fly? I am doing something simular, but just put the version in a properties file using the filtering of the resource plugin and then loading that properties file in the application.

Great post!
January 4, 2010, 2:44 pm
jdoklovic:

I create the version class on the fly so that I can override the version used at runtime via a maven property.
Essentially this let’s me pass a version on the command line when building.
This is useful if you use an external system (say, JIRA) to get your version/build numbers.

Using JIRA + Bamboo in this manner is outlined in another post:
http://blog.sysbliss.com/uncategorized/release-management-with-atlassian-bamboo-and-jira.html
January 4, 2010, 3:28 pm
bqlr:

stupid! so complicated configuration, where is business model ? where is Domain-driven Design, sorry, do you know DDD?

see another true light-weight framework, so simple: DI + AOP + DDD = jdonframework, http://jdon.dev.java.net
January 4, 2010, 9:19 pm
tunaranch:

Rather than ant, if you want to generate a class on the fly, why not use maven-resources-plugin to filter it during the generate-sources maven phase?
February 4, 2010, 8:20 pm
jdoklovic:

maven-resources-plugin might work, however I’m not sure what maven does if it sees a .java file in src/main/resources. I’m guessing it may try to compile it if it’s on the classpath. An easy workaround would be to put it in some other directory though and still use maven-resources-plugin.

I’ll give it a shot and see what happens.
February 5, 2010, 9:44 am

Sysbliss Blog