com.atlassian.applinks.spi.link

Interface MutatingApplicationLinkService

All Superinterfaces:

ApplicationLinkService

public interface MutatingApplicationLinkService
extends ApplicationLinkService

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

Since:

3.0

Method Summary

Modifier and Type	Method and Description
MutableApplicationLink	addApplicationLink(ApplicationId id, ApplicationType type, ApplicationLinkDetails details) Register an outgoing ApplicationLink
void	changeApplicationId(ApplicationId oldId, ApplicationId newId) Changes the value of an application link's ID.
void	configureAuthenticationForApplicationLink(ApplicationLink applicationLink, AuthenticationScenario authenticationScenario, String username, String password) Configures authentication on an application link
ApplicationLink	createApplicationLink(ApplicationType type, ApplicationLinkDetails linkDetails) Creates an application link from this application to a remote application.
void	createReciprocalLink(URI remoteRpcUrl, URI customLocalRpcUrl, String username, String password) Deprecated. will be removed in a future version, should only be used by test code
URI	createSelfLinkFor(ApplicationId id) Returns the URI of the application link resource exposed to a remote application.
void	deleteApplicationLink(ApplicationLink link) Deletes an outgoing ApplicationLink
void	deleteReciprocatedApplicationLink(ApplicationLink link) Delete the outgoing and incoming ApplicationLinks to and from a linked application.
MutableApplicationLink	getApplicationLink(ApplicationId id)
boolean	isAdminUserInRemoteApplication(URI url, String username, String password) Determines whether a set of credentials belong to an administrator of a remote application.
boolean	isNameInUse(String name, ApplicationId id) Checks whether an application link already exists with this name
void	makePrimary(ApplicationId id) Make the specified ApplicationLink the primary link of its ApplicationType.
void	setSystem(ApplicationId id, boolean isSystem) Make the ApplicationLink specified by ApplicationId a system link.

Methods inherited from interface com.atlassian.applinks.api.ApplicationLinkService

getApplicationLinks, getApplicationLinks, getPrimaryApplicationLink

Method Detail

addApplicationLink

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:

the created ApplicationLink

deleteReciprocatedApplicationLink

void deleteReciprocatedApplicationLink(ApplicationLink link)
                                throws ReciprocalActionException,
                                       CredentialsRequiredException

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 ApplicationLinkRequestFactory.createRequest(com.atlassian.sal.api.net.Request.MethodType, java.lang.String) for more details.

deleteApplicationLink

void deleteApplicationLink(ApplicationLink link)

Deletes an outgoing ApplicationLink

Parameters:

link - the ApplicationLink to delete

getApplicationLink

MutableApplicationLink getApplicationLink(ApplicationId id)
                                   throws TypeNotInstalledException

Specified by:

getApplicationLink in interface ApplicationLinkService

Parameters:

id - the ApplicationId of a stored ApplicationLink

Returns:

a mutable MutableApplicationLink object, specified by the id, or null if it does not exist

Throws:

TypeNotInstalledException - if the specified ApplicationLink's ApplicationType is not currently installed.

makePrimary

void makePrimary(ApplicationId id)
          throws TypeNotInstalledException

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.

setSystem

void setSystem(ApplicationId id,
               boolean isSystem)
        throws TypeNotInstalledException

Make the ApplicationLink specified by ApplicationId a system link. A system link is invisible to non-sysadmin users which is controlled in the UI.

Parameters:

id - the ApplicationId of a stored ApplicationLink

Throws:

TypeNotInstalledException - if the specified ApplicationLink's ApplicationType is not currently installed.

changeApplicationId

void changeApplicationId(ApplicationId oldId,
                         ApplicationId newId)
                  throws TypeNotInstalledException

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

Throws:

IllegalArgumentException - if oldId does not exist.

TypeNotInstalledException

createApplicationLink

ApplicationLink createApplicationLink(ApplicationType type,
                                      ApplicationLinkDetails linkDetails)
                               throws ManifestNotFoundException

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 - for manifest not found

Since:

3.4

createReciprocalLink

@Deprecated
void createReciprocalLink(URI remoteRpcUrl,
                                      URI customLocalRpcUrl,
                                      String username,
                                      String password)
                               throws ReciprocalActionException

Deprecated. will be removed in a future version, should only be used by test code

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

Since:

3.4

isAdminUserInRemoteApplication

boolean isAdminUserInRemoteApplication(URI url,
                                       String username,
                                       String password)
                                throws com.atlassian.sal.api.net.ResponseException

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:

com.atlassian.sal.api.net.ResponseException - if the response from the remote application was invalid

Since:

3.4

configureAuthenticationForApplicationLink

void configureAuthenticationForApplicationLink(ApplicationLink applicationLink,
                                               AuthenticationScenario authenticationScenario,
                                               String username,
                                               String password)
                                        throws AuthenticationConfigurationException

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 AuthenticationScenario.isCommonUserBase() and AuthenticationScenario.isTrusted() are both true, 2LOi 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

Since:

3.4

createSelfLinkFor

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

isNameInUse

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'.