1 package com.atlassian.sal.api.license;
2
3 import com.atlassian.annotations.PublicApi;
4 import com.atlassian.sal.api.i18n.InvalidOperationException;
5 import com.atlassian.sal.api.validate.ValidationResult;
6
7 import java.util.Collection;
8 import java.util.Locale;
9 import javax.annotation.Nonnull;
10 import javax.annotation.Nullable;
11
12 /**
13 * Interface into the license system for the underlying application.
14 * <p>
15 * Most applications will take a single global license for the entire application, but some are actually a platform
16 * with multiple "products" installed each with its own product license.
17 * </p>
18 *
19 * @since 2.0
20 */
21 @SuppressWarnings ("UnusedDeclaration")
22 @PublicApi
23 public interface LicenseHandler
24 {
25 /**
26 * Sets the license string for the currently running application.
27 *
28 * This method will fire a {@link com.atlassian.sal.api.license.LicenseChangedEvent} upon successfully setting
29 * the license.
30 *
31 * <p>
32 * This method is not suitable for platforms.
33 *
34 * @param license The raw license string
35 *
36 * @throws IllegalArgumentException if the license string is not a valid license
37 * @throws java.lang.UnsupportedOperationException if this is a platform that allows multiple licenses
38 *
39 * @deprecated Use {@link #addProductLicense(String, String)} instead. Since 3.0.
40 */
41 @Deprecated
42 void setLicense(String license);
43
44 /**
45 * Use this to figure out if this host application uses a single global license, or if it is a platform that can take
46 * multiple Product licenses.
47 * <p>
48 * Most applications would return false here but Fisheye/Crucible will return true, and JIRA 7.0 will return true.
49 *
50 * @return {@code true} if this application is a platform that accepts multiple product licenses, {@code false} if it just takes a single global license.
51 * @since 3.0
52 * @see #hostAllowsCustomProducts()
53 */
54 boolean hostAllowsMultipleLicenses();
55
56 /**
57 * Returns true if it is possible to add custom products on top of this platform.
58 * <p>
59 * Most applications would return false here.
60 * Confluence returns true because it has Spaces and Questions, JIRA 7.0 will return true, but Fisheye/Crucible will
61 * return false - although it has separate licenses for FishEye and Crucible, you cannot add new custom products.
62 *
63 * @return {@code true} if this application is a platform that accepts multiple product licenses, {@code false} if it just takes a single global license.
64 * @since 3.0
65 * @see #hostAllowsMultipleLicenses()
66 */
67 boolean hostAllowsCustomProducts();
68
69 /**
70 * Returns the list of currently available products in this host application whether these products are currently licensed or not.
71 *
72 * <p>
73 * For FishEye/Crucible this will return both "fisheye" and "crucible".
74 * <br>
75 * For JIRA, it will return the list of products that are currently installed (eg "com.atlassian.servicedesk").
76 * <br>
77 * For simple applications that only take a single license, it will return a single application name where that
78 * name is the ID used by HAMS to define the application in the license eg "bamboo", "conf".
79 * <br>
80 *
81 * @return the list of currently available products in this host application
82 */
83 Collection<String> getProductKeys();
84
85 /**
86 * Adds the given product license to the host application.
87 *
88 * <p>
89 * For a platform that can take multiple license, the platform will figure out which product this is for and
90 * replace the current license for that product if one exists.
91 * </p>
92 *
93 * This method will fire a {@link com.atlassian.sal.api.license.LicenseChangedEvent} upon successfully adding
94 * the license.
95 *
96 * @param productKey The product to add this license to
97 * @param license The license string
98 *
99 * @throws InvalidOperationException if the license string is not valid for any reason.
100 * The InvalidOperationException should be localised for the currently logged in user and consumers are
101 * encouraged to call {@link InvalidOperationException#getLocalizedMessage()}
102 * @since 3.0
103 */
104 void addProductLicense(@Nonnull String productKey, @Nonnull String license) throws InvalidOperationException;
105
106 /**
107 * Removes the product license for the given productKey.
108 *
109 * <p>
110 * If the given product is in a multi-product license, it will remove that license and so all those products will
111 * become unlicensed.
112 * You can use {@code #getAllProductLicenses} to find multi-product licenses.
113 *
114 * <p>
115 * This method will fire a {@link com.atlassian.sal.api.license.LicenseChangedEvent} upon successfully removing
116 * the license.
117 * <p>
118 * If the passed productKey does not exist or is not licensed, the method will no-op and return successfully.
119 *
120 * @param productKey The product to remove the license of
121 *
122 * @throws InvalidOperationException if the host application vetoes this operation - eg JIRA will not let you remove
123 * the very last license. The InvalidOperationException should be localised for the currently logged in
124 * user and consumers are encouraged to call {@link InvalidOperationException#getLocalizedMessage()}
125 *
126 * @since 3.0
127 */
128 void removeProductLicense(@Nonnull String productKey) throws InvalidOperationException;
129
130 /**
131 * Validates that the given license is valid to add for the given product.
132 *
133 * @param productKey The product to add this license to
134 * @param license the raw license String
135 * @param locale locale of the end user - this is used to internationalise the error messages if any.
136 */
137 @Nonnull
138 ValidationResult validateProductLicense(@Nonnull String productKey, @Nonnull String license, @Nullable Locale locale);
139
140 /**
141 * Gets the server ID of the currently running application. The server ID format is four quadruples of
142 * alphanumeric characters, each separated by a dash (<tt>-</tt>).
143 *
144 * @return the server ID, or {@code null} if the server ID has not yet
145 * been set for the currently running application.
146 *
147 * @since 2.7
148 */
149 @Nullable
150 String getServerId();
151
152 /**
153 * Gets the Support Entitlement Number (SEN) for the single license in the currently running application.
154 * <p>
155 * This method is not suitable for platforms because these may have multiple licenses and hence multiple SENs.
156 *
157 * @return the Support Entitlement Number, or {@code null} if there is no current support entitlement.
158 *
159 * @throws java.lang.UnsupportedOperationException if this is a platform that allows multiple licenses
160 * @since 2.7
161 *
162 * @deprecated Get the license details and call {@link BaseLicenseDetails#getSupportEntitlementNumber()}. Since 3.0.
163 */
164 @Nullable
165 @Deprecated
166 String getSupportEntitlementNumber();
167
168 /**
169 * Returns the raw license String for a given product on a platform.
170 *
171 * @param productKey the product key.
172 * @return the raw license String for the given product key.
173 *
174 * @see #getProductLicenseDetails(String)
175 * @since 3.0
176 */
177 @Nullable
178 String getRawProductLicense(String productKey);
179
180 /**
181 * Returns the license details for a given individual product.
182 *
183 * @param productKey the product key.
184 * @return the license details for the given product key.
185 *
186 * @see #getRawProductLicense(String)
187 * @see #decodeLicenseDetails(String)
188 * @see #getAllProductLicenses()
189 * @since 3.0
190 */
191 @Nullable
192 SingleProductLicenseDetailsView getProductLicenseDetails(@Nonnull String productKey);
193
194 /**
195 * Returns all the product licenses on a platform.
196 * <p>
197 * A platform may return multiple licenses, a simple application will return 0 or 1.
198 * </p>
199 *
200 * @return all the product licenses on a platform.
201 *
202 * @see #getProductLicenseDetails(String)
203 * @since 3.0
204 */
205 @Nonnull
206 Collection<MultiProductLicenseDetails> getAllProductLicenses();
207
208 /**
209 * Decodes a Platform Product License from the raw license String.
210 * This can be used to validate an entered license String before attempting to save it to the application.
211 *
212 * @param license the raw license String
213 * @return the license details for the given product key.
214 *
215 * @throws java.lang.IllegalArgumentException if the license string is not able to be decoded in this host application
216 * @see #getProductLicenseDetails(String)
217 * @since 3.0
218 */
219 @Nonnull
220 MultiProductLicenseDetails decodeLicenseDetails(@Nonnull String license);
221 }