Chapter 2. Understanding the Plugin Framework

In this chapter, we will cover more details on the JIRA architecture and the plugin framework. We will also cover the following recipes:

Modifying Atlassian bundled plugins
Converting plugins from v1 to v2
Adding resources into plugins
Adding web resources into plugins
Building JIRA from source
Adding new webwork actions to JIRA
Extending a webwork action in JIRA
Capturing plugin installation/uninstallation events

Introduction

As we saw in the previous chapter, the JIRA plugin development process is probably an easier task than we expected it to be. With the help of Atlassian Plugin SDK, developers can spend more time worrying about the plugin logic than on the troublesome deployment activities. And yes, after all, it is the plugin logic that is going to make an impact!

This chapter details how the various components fit into JIRA's architecture and how JIRA exposes the various pluggable points. We will also look at an overview of JIRA's system plugins to find out how JIRA uses the plugin architecture to its own benefit, followed by some useful recipes.

JIRA architecture

We will quickly see how the various components within JIRA fit in to form the JIRA we know. It is best described in a diagram, and Atlassian has a neat one along with a detailed explanation at https://developer.atlassian.com/display/JIRADEV/JIRA+Architectural+Overview. We will redraw the diagram a little bit to explain it in a brief...

Architecture explained

It is best to learn the intricacies of system architecture with the help of a diagram. For the benefit of a brief but meaningful explanation on the JIRA architecture, let us have a quick look (or a long stare, whichever you are more comfortable with!) at the following diagram:

JIRA is a web application built using the MVC architecture. It is fully written in Java and is deployed as a WAR file into a Java Servlet Container such as Tomcat.

The majority of the JIRA core functionality revolves around the JIRA Utility and Manager Classes, which thus becomes the heart of JIRA. It also interacts with a lot of third-party components, which we saw earlier, to deliver powerful functionalities such as workflows, permissions, user management, and searching.

As with any other web application, let us start with the incoming requests. Users interact with JIRA using web browsers, but there are other ways to interact with JIRA, such as using the Jelly scripts or by making remote calls...

Types of plugin modules

Let us briefly see the different types of plugin modules supported in JIRA5. All these modules are various extension points, using which we can not only add new functionalities in to JIRA, but also extend some of the existing functionalities.

Let us group them based on functionality instead of seeing them all together!

Reporting

Module type	Description
`Gadget`	Adds new Gadgets into the user's dashboard. These gadgets can also be accessed from other applications.
`Report`	Adds new reports in to JIRA.

Workflows

Module type	Description
`workflow-condition`	Adds new workflow conditions to the JIRA workflow. It can then be used to limit the workflow actions to users, based on pre-defined conditions.
`workflow-validator`	Adds new workflow validations to the JIRA workflow. Validations can be used to prevent certain workflow actions when certain criteria are not met.
`workflow-function`	Adds new workflow post functions to the JIRA workflow. These can be used to...

Working with the Plugins1 and Plugins2 versions

Let us also quickly see how to deal with the Plugins1 and Plugins2 versions.

Before we go on to the details, it is essential to understand the importance of both these versions. Pre 4.x, JIRA used to support only the Plugins1 version. So why do we need the Plugins2 version?

The key motive behind version2 plugins is to keep the plugins as a bundle isolated from the other plugins and the JIRA core classes. It makes use of the OSGi platform (http://www.osgi.org/) to achieve this. While it keeps the plugins isolated, it also gives you a way to define dependencies between plugins, leaving it to the plugin developer's convenience. It even lets you import or export selected packages within the plugin giving increased flexibility.

The fact that the version2 plugins are deployed as OSGi bundles also means that the plugins are dynamic in nature. They may be installed, started, updated, stopped, and uninstalled at any time during the running of the framework...

JIRA system plugins

In this section, we will see a brief overview of the JIRA system plugins.

A lot of JIRA's functionality is written in the form of plugins. This not only showcases what we can achieve using plugins, but also helps us, as developers, to understand how the various pieces fit together.

If it is the atlassian-plugin.xml file that describes the plugin functionalities, JIRA maintains the information in *.xml files placed under WEB-INF/classes. You will also find the related classes in the exploded folders under WEB-INF/classes.

Let us have a quick look at the various system plugin XMLs that can be found in WEB-INF/classes and the functionality they support:

System plugin XML	Functionality
`system-contentlinkresolvers-plugin.xml`	System content link resolvers: Resolves parsed content links into link objects. Attachment link resolver Anchor link resolver JIRA issue link resolver User profile link resolver
`system-customfieldtypes-plugin.xml`	JIRA system custom fields: All the...

Stable and core APIs

So, we are in to coding. If you are familiar with JIRA plugin development or have been using them prior to JIRA 5, one thing you might have noticed is that there are quite a few versions of every plugin out there! There are not many plugin versions that work on all JIRA versions. You might also know the reason behind this: JIRA has been evolving a lot in terms of its APIs.

With JIRA 5, Atlassian has introduced stable and core APIs, and with great interest, the development community read the following blog written by Rich Manalang: http://blogs.atlassian.com/2012/03/stable-apis-yes-we-have-them/

The earlier atlassian-jira dependency, which was used in JIRA plugins prior to JIRA 5, is now replaced by two different dependencies: jira-api and jira-core. jira-api (aka the stable API) is a set of classes or interfaces that will not be changed without prior notice. Atlassian will maintain binary compatibility for these classes and interfaces.

jira-core, on the other hand,...

Modifying Atlassian bundled plugins

As we discussed earlier, more and more standard functionalities are pushed into bundled plugins as opposed to the JIRA core product. There is no better way to showcase the plugin architecture, I must admit! But that does make the life of high end users who want to modify those functionalities a bit difficult.

Let me take a once simple scenario such as "I want to display the description before the issue details in the View Issue page."

This used to be pretty easy, because all you needed to do was to modify the relevant JSP file and that's it! But now, the View Issue screen rendering is done by jira-view-issue-plugin and it is an Atlassian system plugin. Although the actual work is simple—we only need to modify the atlassian-plugin.xml file—making those changes effective is not as simple as editing the jira-view-issue-plugin-xxx.jar file from the JIRA_Home/.plugins/bundled-plugins folder.

Let us see why!

How to do it…

The reason is pretty simple. All the system...

Converting plugins from v1 to v2

If you are moving to JIRA 4.x+ from JIRA 3.13.x or earlier versions, one of the important differences is the introduction of v2 plugins. While designing the upgrade to JIRA 4.x+, it makes perfect sense to sometimes migrate the plugins from v1 to v2, although it is not a mandatory step. In this recipe, we will see how to convert a version1 plugin to a version2 plugin.

Getting ready

There are a couple of questions we need to ask before the plugin is converted:

Are all the packages used by the plugin available to OSGi plugins?
This is very important because JIRA doesn't expose all the packages to OSGi plugins.
Note
The list of packages exported and made available to the Plugins2 version can be found in the com.atlassian.jira.plugin.DefaultPackageScannerConfiguration class.
Are all the components used by the plugin available to OSGi plugins?
Similar to the previous question, we need to make sure the components are also exposed to the OSGi plugins.
Note
Unfortunately,...

Adding resources into plugins

It is often required to add static resources such as JavaScript files, CSS files, and so on in to our plugins. To enable JIRA to serve these additional static files, they should be defined as downloadable resources.

Getting ready

A resource can be of different types. It is normally defined as a non-Java file that the plugin requires to operate.

Examples of resources that you will come across during JIRA plugin development include, but are not restricted to, the following:

Velocity (*.vm) files required to render a view
JavaScript files
CSS files
Property files for localization

How to do it…

To include a resource, add the resource module to the atlassian-plugin.xml file. The resource module can be added as part of the entire plugin or can be included within another module, restricting it just for that module.

The following are the attributes and elements available for the resource module and their uses:

Name	Description
`name`	The name of the resource. This is used...

Adding web resources into plugins

The web resources plugin module, like the resource module we just saw, allows for the defining of downloadable resources. The difference is that the web resources are added at the top of the page in the header with the cache-related headers set to never expire.

An additional advantage of using the web resources module is that we can specify the resources to be included in specific contexts within the application.

How to do it…

The root element for the web resource plugin module is web-resource. It supports the following attributes:

Name	Description
`key`	The only mandatory attribute. This should be unique within the plugin.
`state`	This indicates whether the plugin module should be disabled by default or not. The default value `enabled`. `value="disabled"` will keep the plugin disabled at startup.
`i18n-name-key`	The localization key for the human-readable name of the plugin module.
`name`	The human-readable name of the web resource.
`system`	This indicates...

Building JIRA from source

One of the best things about JIRA, if you have a valid license, is that you get to see the source code. You can see it, modify it, break it… err? In this recipe we will modify it, because you have the license to do it!

Getting ready

Following are some of the prerequisites prior to building JIRA from the source:

A valid JIRA license to get access to the source code.
An environment with JDK 1.5 or higher for JIRA 4.2 and lower versions. JDK 1.6.x is required for JIRA 4.3 and above versions.
You will need both Maven 1 and Maven 2 if you are building versions prior to JIRA 4.3. Download Maven version 1.0.x and 2.1.x from http://maven.apache.org/. JIRA 4.3 and above versions only need Maven 2.1.0.
Note
You need both Maven 1 and Maven 2 for versions prior to JIRA 4.3, because Maven 1 is required to build the JIRA source and Maven 2 is required to build plugins for JIRA. JIRA has bundled plugins that need to be built along with JIRA, and so Maven 2 is also a must.
Maven 2.1.0...

Adding new webwork actions to JIRA

Most of the time, plugin developers will find themselves writing new actions in JIRA to introduce new functionality. Usually these actions are invoked from new web-item links configured at different places in the UI. It could also be from customized JSPs or other parts of the JIRA framework.

New actions can be added to JIRA with the help of the webwork plugin module.

Getting ready

Before we start, it probably makes sense to have a look at the webwork plugin module. Following are the key attributes that are supported:

Name	Description
`key`	A unique key within the plugin. It will be used as the identifier for the plugin.
`class`	This will be `java.lang.Object` as the real logic will reside in the action, Class.
`i18n-name-key`	The localization key for the human-readable name of the plugin module.
`name`	The human-readable name of the webwork action.

The following are the key elements supported:

Name	Description
`description`	The description of the...

Extending a webwork action in JIRA

There are so many user stories for this one! How do you override some of the JIRA built-in actions? How do you do some additional stuff in the JIRA built-in action? Like doing some crazy things immediately after logging work on a ticket, or doing some innovative validations on some of those actions.

Extending the existing JIRA action is an answer to all these questions. Let us see in detail how to do that.

How to do it…

Extending a JIRA action is done with the help of the webwork plugin module. Most of it is very similar to writing new webwork actions.

Let us take the case of the AddProject action. What should we do if we need to extend this action? Say, to do some additional validation during the creation of a project?

Let us consider an example where we want to prevent users from creating project keys using reserved words.

The following are the steps to do this:

Identify the action to be overridden by looking up the actions.xml file under WEB-INF/classes in...

Capturing plugin installation/uninstallation events

We have seen plugins that are great in terms of functionality but come with a big list of configuration steps. Its much like a treadmill; a great asset but very hard to assemble!

Is there a way we can handle these configurations automatically (like creating custom fields, adding options, creating listeners, services, and so on), when the plugin is installed? The answer is "Yes".

How to do it…

It is simple. Really! Let us look at creating a custom field automatically during a plugin installation and deleting it while uninstalling. The same logic applies as for the enabling/disabling of the plugin. All you need to do is two simple steps:

Write an event listener. We will use the atlassian-event library here.
Implement the Spring interfaces InitializingBean and DisposableBean to capture the plugin lifecycle events.

Writing an event listener in JIRA is quite easy. Just perform the following steps: