com.atlassian.applinks.api
Interface ApplicationLink

All Superinterfaces:

PropertySet

public interface ApplicationLink
extends PropertySet

Represents a link to a remote application-level entity (JIRA, Confluence, Bamboo, etc). You can store simple data against ApplicationLinks using the methods provided by the PropertySet interface. Note that these properties are shared between all plugins in the local application, so be careful to namespace your property keys carefully.

Since:

3.0

See Also:

PropertySet

Method Summary

ApplicationLinkRequestFactory	createAuthenticatedRequestFactory() The ApplicationLinkRequestFactory returned by this method will choose a single AuthenticationProvider for automatically authenticating created Request objects.
ApplicationLinkRequestFactory	createAuthenticatedRequestFactory(java.lang.Class<? extends AuthenticationProvider> providerClass) This method returns a ApplicationLinkRequestFactory initialised by the specified AuthenticationProvider.
java.net.URI	getDisplayUrl()
ApplicationId	getId() This ApplicationId is subject to change if an administrator: upgrades the remote application to use Unified Application Links (and this link was created prior to the upgrade); or the remote application does not have Unified Application Links deployed, and its RPC URL changes. If you are storing the ApplicationId for any reason, your plugin should listen for the ApplicationLinksIDChangedEvent.
java.lang.String	getName()
java.net.URI	getRpcUrl()
ApplicationType	getType() See the com.atlassian.applinks.api.application package for a list of ApplicationTypes bundled with the Unified Application Links plugin.
boolean	isPrimary()

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

getProperty, putProperty, removeProperty

Method Detail

getId

ApplicationId getId()

This ApplicationId is subject to change if an administrator:

• upgrades the remote application to use Unified Application Links (and this link was created prior to the upgrade); or
• the remote application does not have Unified Application Links deployed, and its RPC URL changes.

If you are storing the ApplicationId for any reason, your plugin should listen for the ApplicationLinksIDChangedEvent.

Returns:

the globally unique ID of the server at the other end of this link.

getType

ApplicationType getType()

See the com.atlassian.applinks.api.application package for a list of ApplicationTypes bundled with the Unified Application Links plugin. Additional types can be added via the extension APIs in the applinks-spi module.

Returns:

the type of the application e.g. JiraApplicationType

getName

java.lang.String getName()

Returns:

a brief identifier for the linked application e.g. "My FishEye". Note that this property is never guaranteed to be unique or immutable. Do not use as primary key (use ID instead).

getDisplayUrl

java.net.URI getDisplayUrl()

Returns:

the base URL to be used when constructing links that are sent to clients, e.g. web browsers. The URI returned by this method will have no trailing slash. e.g. "https://mydomain.com/jira"

getRpcUrl

java.net.URI getRpcUrl()

Returns:

the base URL to be used when constructing URIs to be used for RPC calls to this application (e.g. xml-rpc, SOAP or REST requests). The returned URI will have no trailing slash. e.g. "http://localhost:8080/jira"

isPrimary

boolean isPrimary()

Returns:

true if this is the primary ApplicationLink of its type, false otherwise

createAuthenticatedRequestFactory

ApplicationLinkRequestFactory createAuthenticatedRequestFactory()

The ApplicationLinkRequestFactory returned by this method will choose a single AuthenticationProvider for automatically authenticating created Request objects. The selection algorithm is as follows:

• If one or more ImpersonatingAuthenticationProviders are configured (for example, OAuth or Trusted Applications), one will be used. Trusted Applications will be returned in preference to OAuth if both are configured;
• else if one or more NonImpersonatingAuthenticationProviders are configured (for example, Basic Auth), one will be used
• else the request will be unauthenticated, and processed in the remote application anonymously.

Additional AuthenticationProviders can be implemented via the extension APIs in the applinks-spi module. If your feature only supports a single authentication method, you should use createAuthenticatedRequestFactory(Class)}.

Returns:

an ApplicationLinkRequestFactory for creating requests that are authenticated for this ApplicationLink.

See Also:

ApplicationLinkRequestFactory, ImpersonatingAuthenticationProvider, NonImpersonatingAuthenticationProvider, createAuthenticatedRequestFactory(Class)

createAuthenticatedRequestFactory

ApplicationLinkRequestFactory createAuthenticatedRequestFactory(java.lang.Class<? extends AuthenticationProvider> providerClass)

This method returns a ApplicationLinkRequestFactory initialised by the specified AuthenticationProvider. You should use this method only if your feature requires a specific AuthenticationProvider implementation. Note that this method will return null if an administrator of the local application has not configured the specified AuthenticationProvider for this ApplicationLink.

Parameters:

providerClass - the AuthenticationProvider type to use for the RequestFactory

Returns:

a RequestFactory for creating requests that are authenticated for this ApplicationLink using an AuthenticationProvider implementation that conforms to the supplied providerClass, or null if no AuthenticationProvider is configured for this ApplicationLink. If the supplied providerClass is AuthenticationProvider.class this method will bind the RequestFactory to any available AuthenticationProvider, or return null if there are no AuthenticationProviders configured. This method will only return an unauthenticated RequestFactory if the supplied providerClass is Anonymous.

See Also:

createAuthenticatedRequestFactory()