Package 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:

  • Method Details

    • 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

      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:

    • 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 - if the licenses are not valid
      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

      @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:

    • 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:

    • 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: