SAL services

Below is a list of the services provided by the Atlassian Shared Access Layer. You will find more developer help in the Javadoc.

Service Descriptions and Examples

com.atlassian.sal.api

ApplicationProperties

Exposes key application settings such as the base URL, application name, build information and version number.

Example -- Obtaining base url of the application:

1
2
public class DefaultStudioInfo
{
private final ApplicationProperties applicationProperties;

public DefaultStudioInfo(final ApplicationProperties applicationProperties)
{
this.applicationProperties = applicationProperties;
}

public String getCurrentAppBaseUrl()
{
return applicationProperties.getBaseUrl();
}
}

com.atlassian.sal.api.auth

AuthenticationController

Allows the host application to communicate about when authentication should be performed and users allowed to login.

AuthenticationListener

Allows the underlying framework to take some actions on authentication events.

Authenticator

Marker interface for classes that can authenticate requests.

LoginUriProvider

Provides the URI to redirect users to so that they can log in before they can authorise consumer requests to access their data.

com.atlassian.sal.api.component

ComponentLocator

Gives access to the application's component container instances.

com.atlassian.sal.api.executor

ThreadLocalDelegateExecutorFactory

Factory to create Executor instances that delegate to a specific Executor and ensure the executed code runs in the same thread local context.

com.atlassian.sal.api.license

LicenseHandler

Handles setting and retrieving the application's license.

com.atlassian.sal.api.lifecycle

LifecycleAware

Marks a class that wants to execute code on certain application-level lifecycle stages.

LifecycleManager

Interface to be used to trigger lifecycle events. Handles lifecycle events by calling LifecycleAware methods on registered beans.

com.atlassian.sal.api.message

I18nResolver

Resolves an internationalisation key or key/argument pair to its internationalised message.

LocaleResolver

Used to retrieve the user's locale, based on the remote users preferences, or the preferred locale as specified in the request or finally defaulting to the system locale if no preferred locale is set.

Message

Encapsulates a message before it has been resolved via an I18N resolver.

MessageCollection

A collection of messages that have not been resolved.

com.atlassian.sal.api.net

Request

Represents a request to retrieve data. To execute a request call Request#execute(ResponseHandler).

RequestFactory

Provides a factory for making HTTP requests with optional authentication.

Example -- Running remote search:

1
2
public class RemoteSearcher
{
private final String url;
private static final String SEARCH_PLUGIN_PATH = "/plugins/servlet/studio/search";
private final RequestFactory<?> requestFactory;

public RemoteSearcher(final String url, final RequestFactory<?> requestFactory)
{
this.url = url;
this.requestFactory = requestFactory;
}

public SearchResults search(final String remoteUser, final String query)
{
final String fullUrl = url + SEARCH_PLUGIN_PATH + "?query=" + URIUtil.encodeWithinQuery(query);

final Request<?> request = requestFactory.createRequest(MethodType.GET, fullUrl);
request.addTrustedTokenAuthentication(); // this takes username from ThreadLocal
try
{
// parse the response
final String responseString = request.execute();
return (SearchResults) XStreamUtils.fromXML(responseString);
}
catch (final ResponseException e)
{
throw new RuntimeException("Search for " + query + " on " + fullUrl + " failed.", e);
}
}
}

Response

Represents the response when calling Request#execute(ResponseHandler).

ResponseException

Exception thrown by Request#execute(ResponseHandler) and Request#handle(ResponseHandler).

ResponseHandler

Callback interface used by Request#execute(ResponseHandler) method. Implementation of this interface performs actual handling of the response.

com.atlassian.sal.api.net.auth

Authenticator

Marker interface for an authenticator.

com.atlassian.sal.api.pluginsettings

PluginSettings

Provides access to settings globally or per project/space/repository.

Example -- Saving and retrieving custom settings per project:

1
2
public class CustomProjectSettings
{
    private final PluginSettingsFactory pluginSettingsFactory;
    private final String projectKey;

    public CustomProjectSettings(final PluginSettingsFactory pluginSettingsFactory, final String projectKey)
    {
    this.pluginSettingsFactory = pluginSettingsFactory;
    this.projectKey = projectKey;
    }

    public void setValue(final String key, final String value)
    {
    final PluginSettings settings = pluginSettingsFactory.createSettingsForKey(projectKey);
    settings.put(key, value);
    }

    public Object getValue(final String key)
    {
    final PluginSettings settings = pluginSettingsFactory.createSettingsForKey(projectKey);
    return settings.get(key);
    }
}

PluginSettingsFactory

One feature provided by SAL is storage of plugin settings, for global and project-specific settings. You will create a PluginSettings object via a PluginSettingsFactory, which uses the abstract factory pattern. Refer to the developer blog post on Storing plugin settings with the abstract factory pattern.

com.atlassian.sal.api.project

ProjectManager

Provides a list of projects. A project may represent different things depending on the application. For example, in Confluence it is a space, in Bamboo it is a build plan, and in JIRA it is a project.

com.atlassian.sal.api.scheduling

PluginJob

A job to be executed by the PluginScheduler.

PluginScheduler

Schedules plugin jobs programmatically.

com.atlassian.sal.api.search

ResourceType

Defines the more information about the search resource (e.g. JIRA, wiki).

SearchMatch

A single match for a query (e.g. an issue, a wiki page, a commit). The match contains a URL, title and possibly an excerpt. The resourceType contains more information about the source of this searchMatch.

SearchProvider

Executes search queries. Allows for simple string based searches in an application.

SearchResults

Provides searchresults for a query.

com.atlassian.sal.api.search.parameter

SearchParameter

Allows you to specify additional properties for a search as string value pairs. For example this could specify a fixforversion=3.12 in JIRA, or application=crucible in FishEye.

com.atlassian.sal.api.search.query

SearchQuery

Utility to help with creating a query string.

SearchQueryParser

Parses a search query.

com.atlassian.sal.api.transaction

TransactionCallback

A simple callback that needs to be provided with an action to run in the doInTransaction method. It is assumed that if anything goes wrong, doInTransaction will throw a RuntimeException and the calling transactionTemplate will roll back the transaction.

TransactionTemplate

com.atlassian.sal.api.timezone

TimeZoneManager

Available since SAL 2.6.
Provides timezone information about the users and about the application.

com.atlassian.sal.api.upgrade

PluginUpgradeManager

Provides a plugin upgrade framework that will recognise PluginUpgradeTask tasks and run them on startup.

PluginUpgradeTask

com.atlassian.sal.api.user

UserManager

Provides simplified access to users across various applications, and performs user authentication checks.

UserResolutionException

Services Available per Application

The matrix below shows the services available to each version of the Atlassian applications that support the Shared Access Layer. The applications are listed horizontally across the top and the SAL versions are listed vertically on the left.

• Version numbers in brackets indicate a future application release expected to support the relevant SAL services.
• YES shows that the SAL service is available to the relevant version of the application.
• NO means that the service is not available to the relevant version of the application.

com.atlassian.sal.api

 com.atlassian.sal.api.auth

 com.atlassian.sal.api.executor

 com.atlassian.sal.api.license

 com.atlassian.sal.api.lifecycle

com.atlassian.sal.api.message

 com.atlassian.sal.api.net

 com.atlassian.sal.api.net.auth

 com.atlassian.sal.api.project

 com.atlassian.sal.api.scheduling

 com.atlassian.sal.api.search

 com.atlassian.sal.api.search.parameter

 com.atlassian.sal.api.search.query

 com.atlassian.sal.api.transaction

 com.atlassian.sal.api.upgrade

com.atlassian.sal.api.user

RELATED TOPICS

Javadoc
About SAL Development