Storing plugin settings

Overview

Plugin settings are part of the Shared Access Layer (SAL) component of the Atlassian plugin framework. These settings provide a cross-product mechanism for persisting values relied upon by plugins. Learn more about the plugin development framework

PluginSettings objects for Confluence, Jira, and other products are created with a PluginSettingsFactory interface that uses the abstract factory pattern. The type of PluginSettingsFactory in use depends on the particular product. For example, in Confluence, it will be ConfluencePluginSettingsFactory.

Using the abstract factory pattern has the following advantages:

No matter what is your target product, you can use one syntax to interact with plugin settings. You don't have to learn and remember multiple, distinct settings storage syntax for different products.
A particular plugin could potentially have multiple target products without special handling, at least as far as plugin settings are concerned.

These are benefits often seen when using factories for object creation:

Users of the object are insulated from the specific objects used and their implementations.
Maintenance changes only need to occur in one location rather than in each client.

How to store plugin settings

The PluginSettingsFactory has two methods that allow storing plugin settings in Atlassian applications:

createGlobalSettings(): gets all global configuration data.
createSettingsForKey(java.lang.String key): gets all settings for a key, for which valid values are application-specific.

We don't recommend storing volatile plugin data (like user, issue, or project properties in Jira) together with global configuration data. This will affect the performance of your Atlassian application.

Instead of using the createGlobalSettings(), create a reference to your plugin settings by using the PluginSettingsFactory#createSettingsForKey, where the key is the project or space the configuration data should be associated with.

Examples of using `PluginSettingsFactory` to store plugin data

PluginSettings objects are created with a PluginSettingsFactory, like this:

1
2
PluginSettings pluginSettings = pluginSettingsFactory.createGlobalSettings();

In this example, the PluginSettingsFactory interface includes the createGlobalSettings() method, which returns a PluginSettings object.

Behind the scenes, settings are stored in a product-specific way, as presented in the following examples.

Example in Confluence

In a Confluence plugin, the pluginSettingsFactory will be a ConfluencePluginSettingsFactory. The createGlobalSettings() will return a ConfluencePluginSettings object.

The ConfluencePluginSettings object uses the Bandana framework to internally to store the plugin settings. Learn more about Bandana

For a Jira plugin, the JiraPluginSettingsFactory interface returns JiraPluginSettings objects that use the PropertySet framework to store the settings. Learn more about Atlassian Shared Access Layer services

Example in Jira

Learn more about global Jira configuration in this article: Advanced Jira application configuration