Quick Start Guide to Embedding
If you want to get the plugin framework into your application with little fuss, this is the guide for you.
Before you start, ensure your application requires recent versions of Java 5 or Java 6.
Step 1: Add the Framework and Dependency JARs to your Webapp
If you already use Maven 2, the easiest way to add the Atlassian Plugins JAR files to your build is to add this dependency:
In your dependency declaration, replace RELEASE with the latest version.
Alternatively, you can add the individual JAR files, paying attention to their dependencies as defined in their pom.xml. At a minimum, you will want these jars:
You can find them in the Maven repository: http://maven.atlassian.com/public/com/atlassian/plugins
Step 2: Start the Plugin Framework during Application Initialisation
The primary class to configure and use to manage the plugin framework is
com.atlassian.plugin.main.AtlassianPlugins. This is an example of how to construct and start an instance of it:
myServiceInstance could be any interface and implementation, respectively, that you want to share with plugins. The only requirement is any object instances you share must have an interface.
Step 3: Add a New Module Descriptor
Plugin modules are the extension points your application exposes to plugins. The module descriptors are how a plugin tells the framework that it implements one of those extension points.
Here is a simple module descriptor that allows a plugin to define code that will be ran on startup:
Next, your application needs to use this extension point. In our example, we would need to add this code to at the end of our application intialisation code:
Step 4: Write a Simple Test Plugin
Finally, we need to write a simple plugin to ensure everything is working correctly. A plugin generally is composed of Java code and a single
atlassian-plugin.xml descriptor file sitting at the root of the jar. Since it is a jar, ensure that it has a valid manifest.
To test the 'on-start' plugin module type described in this guide, let's write a 'himom-plugin' that will print "Hi Mom!" on startup. This plugin will consist of a Runnable class that does the work and a plugin descriptor for configuration:
To deploy this plugin, we can drop it into the "plugins" directory we configured in step 2 and the plugin framework should find it within 2 seconds and install the plugin automatically.