public interface

MutatingApplicationLinkService

implements ApplicationLinkService
com.atlassian.applinks.spi.link.MutatingApplicationLinkService
Known Indirect Subclasses

Class Overview

This interface adds methods for adding, updating and deleting ApplicationLinks.

Summary

Public Methods
abstract MutableApplicationLink addApplicationLink(ApplicationId id, ApplicationType type, ApplicationLinkDetails details)
Register an outgoing ApplicationLink
abstract void changeApplicationId(ApplicationId oldId, ApplicationId newId)
Changes the value of an application link's ID.
abstract void configureAuthenticationForApplicationLink(ApplicationLink applicationLink, AuthenticationScenario authenticationScenario, String username, String password)
Configures authentication on an application link
abstract ApplicationLink createApplicationLink(ApplicationType type, ApplicationLinkDetails linkDetails)
Creates an application link from this application to a remote application.
abstract void createReciprocalLink(URI remoteRpcUrl, URI customLocalRpcUrl, String username, String password)
Creates a reciprocal application link from a remote application to this application.
abstract URI createSelfLinkFor(ApplicationId id)
Returns the URI of the application link resource exposed to a remote application.
abstract void deleteApplicationLink(ApplicationLink link)
Deletes an outgoing ApplicationLink
abstract void deleteReciprocatedApplicationLink(ApplicationLink link)
Delete the outgoing and incoming ApplicationLinks to and from a linked application.
abstract MutableApplicationLink getApplicationLink(ApplicationId id)
Retrieves an ApplicationLink by its ApplicationId.
abstract boolean isAdminUserInRemoteApplication(URI url, String username, String password)
Determines whether a set of credentials belong to an administrator of a remote application.
abstract boolean isNameInUse(String name, ApplicationId id)
Checks whether an application link already exists with this name
abstract void makePrimary(ApplicationId id)
Make the specified ApplicationLink the primary link of its ApplicationType.
[Expand]
Inherited Methods
From interface com.atlassian.applinks.api.ApplicationLinkService

Public Methods

public abstract MutableApplicationLink addApplicationLink (ApplicationId id, ApplicationType type, ApplicationLinkDetails details)

Register an outgoing ApplicationLink

Parameters
id the ApplicationId of the application to create a link to
type the ApplicationType of the link (use the TypeAccessor to access registered ApplicationTypes)
details an ApplicationLinkDetails object initialised with the ApplicationLink's details. Note that another name may be used if an application link with this name already exists.
Returns

public abstract void changeApplicationId (ApplicationId oldId, ApplicationId newId)

Changes the value of an application link's ID. This operation does NOT emit an event.

Throws
IllegalArgumentException if oldId does not exist.
TypeNotInstalledException

public abstract void configureAuthenticationForApplicationLink (ApplicationLink applicationLink, AuthenticationScenario authenticationScenario, String username, String password)

Configures authentication on an application link

Parameters
applicationLink The application link to configure
authenticationScenario holder for details that are used to determine the most appropriate AuthenticationProvider, which will be configured by this method (e.g. if isCommonUserBase() and isTrusted() are both true, Trusted Applications will be configured).
username The username of an administrator on the remote application
password The password of the administrator on the remote application
Throws
AuthenticationConfigurationException if authentication could not be configured

public abstract ApplicationLink createApplicationLink (ApplicationType type, ApplicationLinkDetails linkDetails)

Creates an application link from this application to a remote application. Similar to addApplicationLink but doesn't retrieves or automatically generates the ApplicationId for you (depending on the ApplicationType's ManifestRetriever implementation.

Parameters
type The type of the remote application
linkDetails The details of the link to create
Returns
  • The newly created application link
Throws
ManifestNotFoundException
ManifestNotFoundException

public abstract void createReciprocalLink (URI remoteRpcUrl, URI customLocalRpcUrl, String username, String password)

Creates a reciprocal application link from a remote application to this application.

Parameters
remoteRpcUrl The base URI of the remote application, for RPC purposes
customLocalRpcUrl The base URI of the local application, for display purposes, or null to use the configured base URL
username The username of an administrator of the remote system
password The password of the administrator on the remote system
Throws
NotAdministratorException if the supplied credentials are not those of an administrator on the remote system
LinkCreationResponseException if the link creation response from the remote system was invalid
AuthenticationResponseException if the authentication response from the remote system was invalid
RemoteErrorListException if the remote system reported one or more errors
ReciprocalActionException

public abstract URI createSelfLinkFor (ApplicationId id)

Returns the URI of the application link resource exposed to a remote application.

Parameters
id The ID of the remote application
Returns
  • the URI

public abstract void deleteApplicationLink (ApplicationLink link)

Deletes an outgoing ApplicationLink

Parameters
link the ApplicationLink to delete

public abstract void deleteReciprocatedApplicationLink (ApplicationLink link)

Delete the outgoing and incoming ApplicationLinks to and from a linked application. If the (incoming) link deletion in the remote application fails, the local (outgoing) link will not be deleted. Use deleteApplicationLink(ApplicationLink) to delete just the outgoing ApplicationLink if such behaviour is desired.

Parameters
link the ApplicationLink to delete
Throws
ReciprocalActionException if there was an issue deleting the link from the remote application
CredentialsRequiredException if a request to delete the remote application link could not be created as the current user has not provided credentials for the remote application. See createRequest(Request.MethodType, String) for more details.

public abstract MutableApplicationLink getApplicationLink (ApplicationId id)

Retrieves an ApplicationLink by its ApplicationId. Use this method only if you know the ApplicationId of an existing ApplicationLink. If you storing an ApplicationId for future look-ups using this method, you should listen for the ApplicationLinksIDChangedEvent to ensure your stored ApplicationId is kept current.

Parameters
id the ApplicationId of a stored ApplicationLink
Returns
Throws
TypeNotInstalledException if the specified ApplicationLink's ApplicationType is not currently installed.

public abstract boolean isAdminUserInRemoteApplication (URI url, String username, String password)

Determines whether a set of credentials belong to an administrator of a remote application.

Parameters
url The base URI of the remote application
username A username to check
password A password to check
Returns
  • true if the supplied credentials belong to administator of the remote application. false otherwise.
Throws
ResponseException if the response from the remote application was invalid

public abstract boolean isNameInUse (String name, ApplicationId id)

Checks whether an application link already exists with this name

Parameters
name Name of the application link
id Applink to be excluded from the result. If null, it means no link will be excluded.
Returns
  • true if an Applink already exist with this name and another 'id'.

public abstract void makePrimary (ApplicationId id)

Make the specified ApplicationLink the primary link of its ApplicationType. Note that exactly one primary link of each type is allowed, so this method will remove the primary flag from the current primary link of the link's type.

Parameters
id the ApplicationId of a stored ApplicationLink
Throws
TypeNotInstalledException if the specified ApplicationLink's ApplicationType is not currently installed.