Storing plugin settings for Fisheye

Overview

This tutorial demonstrates how to use SAL (Shared Access Layer) to let your plugin store its configuration settings.SAL offers a product independent way to store and retrieve settings.

Configuring your Plugin

When you are developing against Fisheye/Crucible 2.1.x, the SAL library is already configured as a maven dependency, which means you won't need to configure anything when you use an IDE with maven integration.

Prior to Fisheye/Crucibe 2.1, the SAL library did not come as a pre-configured maven dependency and you will need to manually add it to your pom.xml file:

pom.xml

1
2
<dependency>
    <!-- This dependency is only required for Fisheye/Crucible 2.0.x, NOT 2.1 or later. -->
    <groupId>com.atlassian.sal</groupId>
    <artifactId>sal-api</artifactId>
    <version>2.0.6</version>
    <scope>provided</scope>
</dependency>

Next thing to do is to import the SAL service we are going to use by declaring it in our atlassian-plugin.xml file. SAL services that are not explicitly declared will not be available:

atlassian-plugin.xml

1
2
<component-import key="pluginSettingsFactory" interface="com.atlassian.sal.api.pluginsettings.PluginSettingsFactory" />

Data Storage and Retrieval

With SAL configured, you can now get Fisheye/Crucible to inject the com.atlassian.sal.api.pluginsettings.PluginSettingsFactory into your plugin modules. This factory gives access to plugin settings.

In Fisheye/Crucible, plugin settings are linked to repositories. This allows plugins to use different settings per repository. Per-repository settings are accessed through the PluginSettingsFactory.createSettingsForKey(String repoKey) method.

In addition to the per-repository settings there is a global settings pool where your plugin can store settings that are not repository dependent. This is used by the example below:

1
2
package com.atlassian.contrib;

import com.atlassian.sal.api.pluginsettings.PluginSettingsFactory;
import com.atlassian.sal.api.pluginsettings.PluginSettings;

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.ServletException;
import java.io.IOException;
import java.util.List;
import java.util.ArrayList;

public class ExampleServlet extends HttpServlet {

    private final PluginSettingsFactory settingsFactory;

    public ExampleServlet(PluginSettingsFactory settingsFactory) {
        this.settingsFactory = settingsFactory;
    }

    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {

        PluginSettings settings = settingsFactory.createGlobalSettings();
        String value1 = (String)settings.get("myPlugin.value1");
        List<String> value2 = (List<String>) settings.get("myPlugin.value2");

        ...
    }

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException {

        PluginSettings settings = settingsFactory.createGlobalSettings();
        settings.put("myPlugin.value1", "foo");

        List<String> value2 = new ArrayList<String>();
        value2.add("foo");
        value2.add("bar");
        settings.put("myPlugin.value2", value2);

        ...
    }
}

SAL's PluginSettings service supports the following value types:

• java.lang.String - stored as-is
• java.util.List - calls toString() on the list items
• java.util.Map - calls toString() on both the keys and values in the Map
• java.util.Properties - uses Properties.store() to let the Properties object serialize itself

Limitations

SAL's PluginSettings mechanism is suitable for storing simple string-based key/value pairs, but should generally not be used to store large amounts of data.

Plugin configuration properties are not isolated from other plugins, but all share the same storage area. As a result, your plugin settings could be retrieved by other plugins if they knew which keys you are using. Consequently, you must be careful not to accidentally overwrite other plugins' settings by using the same property keys. Instead, always prefix your configuration keys with a unique string. Your plugin's unique key string makes a good prefix.