com.atlassian.sal.api.license

Interface LicenseHandler

@PublicApi
public interface LicenseHandler

Interface into the license system for the underlying application.

Licenses and products across Atlassian vary considerably with respect to the number of licenses that any given product may accept (1-many), but also in terms of the number of products that may be granted within license (also 1-many). This interface provides both a single product view of license details (regardless of the actual number of licenses and products present), as well as a MultiProductLicenseDetails.

Since:

2.0

See Also:

MultiProductLicenseDetails

Method Summary

Modifier and Type	Method and Description
void	addProductLicense(String productKey, String license) Adds the given product license to the host application.
void	addProductLicenses(Set<RawProductLicense> rawProductLicenses) The addProductLicenses is similar to addProductLicense(String, String) except that it able to verify and add multiple products in the same request.
MultiProductLicenseDetails	decodeLicenseDetails(String license) Decodes a Platform Product License from the raw license String.
Collection<MultiProductLicenseDetails>	getAllProductLicenses() Returns all the product licenses on a platform.
SortedSet<String>	getAllSupportEntitlementNumbers() Gets the Support Entitlement Numbers (SENs) for all licenses in the currently running application.
Set<String>	getProductKeys() Returns the list of currently available products in this host application whether these products are currently licensed or not.
SingleProductLicenseDetailsView	getProductLicenseDetails(String productKey) Returns an individual product view of the license details for the product identified by the given product key, or null if the product does not exist in any license.
String	getRawProductLicense(String productKey) Returns the raw license String for a given product on a platform.
String	getServerId() Gets the server ID of the currently running application.
String	getSupportEntitlementNumber() Deprecated. Get the license details and call BaseLicenseDetails.getSupportEntitlementNumber(). Since 3.0.
boolean	hostAllowsCustomProducts() Returns true if it is possible to add custom products on top of this platform.
boolean	hostAllowsMultipleLicenses() Use this to figure out if this host application uses a single global license, or if it is a platform that can take multiple Product licenses.
void	removeProductLicense(String productKey) Removes the product license for the given productKey.
void	setLicense(String license) Deprecated. Use addProductLicense(String, String) instead. Since 3.0.
MultipleLicensesValidationResult	validateMultipleProductLicenses(Set<RawProductLicense> rawProductLicenses, Locale locale) Validates that the given licenses are valid to add for the given product.
ValidationResult	validateProductLicense(String productKey, String license, Locale locale) Validates that the given license is valid to add for the given product.

Method Detail

setLicense

@Deprecated
void setLicense(String license)

Deprecated. Use addProductLicense(String, String) instead. Since 3.0.

Sets the license string for the currently running application.

This method will fire a LicenseChangedEvent upon successfully setting the license.

This method is not suitable for platforms.

Parameters:

license - The raw license string

Throws:

IllegalArgumentException - if the license string is not a valid license

UnsupportedOperationException - if this is a platform that allows multiple licenses

hostAllowsMultipleLicenses

boolean hostAllowsMultipleLicenses()

Use this to figure out if this host application uses a single global license, or if it is a platform that can take multiple Product licenses.

Most applications would return false here but Fisheye/Crucible will return true, and JIRA 7.0 will return true.

Returns:

true if this application is a platform that accepts multiple product licenses, false if it just takes a single global license.

Since:

3.0

See Also:

hostAllowsCustomProducts()

hostAllowsCustomProducts

boolean hostAllowsCustomProducts()

Returns true if it is possible to add custom products on top of this platform.

Most applications would return false here. Confluence returns true because it has Spaces and Questions, JIRA 7.0 will return true, but Fisheye/Crucible will return false - although it has separate licenses for FishEye and Crucible, you cannot add new custom products.

Returns:

true if this application is a platform that accepts multiple product licenses, false if it just takes a single global license.

Since:

3.0

See Also:

hostAllowsMultipleLicenses()

getProductKeys

Set<String> getProductKeys()

Returns the list of currently available products in this host application whether these products are currently licensed or not.

For FishEye/Crucible this will return both "fisheye" and "crucible".
For JIRA, it will return the list of products that are currently installed (eg "com.atlassian.servicedesk").
For simple applications that only take a single license, it will return a single application name where that name is the ID used by HAMS to define the application in the license eg "bamboo", "conf".

Returns:

the list of currently available products in this host application

addProductLicense

void addProductLicense(@Nonnull
                       String productKey,
                       @Nonnull
                       String license)
                throws InvalidOperationException

Adds the given product license to the host application.

For a platform that can take multiple license, the platform will figure out which product this is for and replace the current license for that product if one exists.

This method will fire a LicenseChangedEvent upon successfully adding the license.

Parameters:

productKey - The product to add this license to

license - The license string

Throws:

InvalidOperationException - if the license string is not valid for any reason. The InvalidOperationException should be localised for the currently logged in user and consumers are encouraged to call InvalidOperationException.getLocalizedMessage()

Since:

3.0

addProductLicenses

void addProductLicenses(@Nonnull
                        Set<RawProductLicense> rawProductLicenses)
                 throws InvalidOperationException

The addProductLicenses is similar to addProductLicense(String, String) except that it able to verify and add multiple products in the same request. Adds the given licenses to the host application.

For a platform that can take multiple licenses, the platform will figure out which product this is for and replace the current license for that product if one exists.

This method will fire a LicenseChangedEvent upon successfully adding the licenses.

Parameters:

rawProductLicenses - the licenses to add

Throws:

InvalidOperationException

Since:

4.2

removeProductLicense

void removeProductLicense(@Nonnull
                          String productKey)
                   throws InvalidOperationException

Removes the product license for the given productKey.

If the given product is in a multi-product license, it will remove that license and so all those products will become unlicensed. You can use #getAllProductLicenses to find multi-product licenses.

This method will fire a LicenseChangedEvent upon successfully removing the license.

If the passed productKey does not exist or is not licensed, the method will no-op and return successfully.

Parameters:

productKey - The product to remove the license of

Throws:

InvalidOperationException - if the host application vetoes this operation - eg JIRA will not let you remove the very last license. The InvalidOperationException should be localised for the currently logged in user and consumers are encouraged to call InvalidOperationException.getLocalizedMessage()

Since:

3.0

validateProductLicense

@Nonnull
ValidationResult validateProductLicense(@Nonnull
                                                 String productKey,
                                                 @Nonnull
                                                 String license,
                                                 @Nullable
                                                 Locale locale)

Validates that the given license is valid to add for the given product.

Parameters:

productKey - The product to add this license to

license - the raw license String

locale - locale of the end user - this is used to internationalise the error messages if any.

validateMultipleProductLicenses

@Nonnull
MultipleLicensesValidationResult validateMultipleProductLicenses(@Nonnull
                                                                          Set<RawProductLicense> rawProductLicenses,
                                                                          @Nullable
                                                                          Locale locale)

Validates that the given licenses are valid to add for the given product.

Parameters:

rawProductLicenses - The products to add these licenses to

locale - locale of the end user - this is used to internationalise the error messages if any.

Returns:

Validation results

Since:

4.2

getServerId

@Nullable
String getServerId()

Gets the server ID of the currently running application. The server ID format is four quadruples of alphanumeric characters, each separated by a dash (-).

Returns:

the server ID, or null if the server ID has not yet been set for the currently running application.

Since:

2.7

getSupportEntitlementNumber

@Nullable
 @Deprecated
String getSupportEntitlementNumber()

Deprecated. Get the license details and call BaseLicenseDetails.getSupportEntitlementNumber(). Since 3.0.

Gets the Support Entitlement Number (SEN) for the single license in the currently running application.

This method is not suitable for platforms because these may have multiple licenses and hence multiple SENs.

Returns:

the Support Entitlement Number, or null if there is no current support entitlement.

Throws:

UnsupportedOperationException - if this is a platform that allows multiple licenses

Since:

2.7

getAllSupportEntitlementNumbers

@Nonnull
SortedSet<String> getAllSupportEntitlementNumbers()

Gets the Support Entitlement Numbers (SENs) for all licenses in the currently running application. The SENs are in an ordered set, guaranteeing to return the SEN in the same order until the installed license state changes.

Note that licensed plugin SENs are not included in the results, unless they are being treated as application licenses.

Returns:

an ordered set of all the SENs. The set does not contain any empty or null SEN strings. If there is no SEN it will return an empty set. Non-platform products may return a set with only one SEN.

Since:

3.0

getRawProductLicense

@Nullable
String getRawProductLicense(String productKey)

Returns the raw license String for a given product on a platform.

Parameters:

productKey - the product key.

Returns:

the raw license String for the given product key.

Since:

3.0

See Also:

getProductLicenseDetails(String)

getProductLicenseDetails

@Nullable
SingleProductLicenseDetailsView getProductLicenseDetails(@Nonnull
                                                                   String productKey)

Returns an individual product view of the license details for the product identified by the given product key, or null if the product does not exist in any license.

Parameters:

productKey - the product key.

Returns:

the license details for the given product key.

Since:

3.0

See Also:

getRawProductLicense(String), decodeLicenseDetails(String), getAllProductLicenses()

getAllProductLicenses

@Nonnull
Collection<MultiProductLicenseDetails> getAllProductLicenses()

Returns all the product licenses on a platform.

A platform may return multiple licenses, a simple application will return 0 or 1.

Returns:

all the product licenses on a platform.

Since:

3.0

See Also:

getProductLicenseDetails(String)

decodeLicenseDetails

@Nonnull
MultiProductLicenseDetails decodeLicenseDetails(@Nonnull
                                                         String license)

Decodes a Platform Product License from the raw license String. This can be used to validate an entered license String before attempting to save it to the application.

Parameters:

license - the raw license String

Returns:

the license details for the given product key.

Throws:

IllegalArgumentException - if the license string is not able to be decoded in this host application

Since:

3.0

See Also:

getProductLicenseDetails(String)