License Client is the basic module in LicenseSpring implementation. For most use cases it's the only module required for a successful LicenseSpring implementation.
To include License Client to your Maven/Gradle project use this snippet:
Javadoc, Jar and OSGi bundle downloads can be found here.
Initializing the License Client
All of the methods are accessed via the LicenseManager singleton - this means you initialize the SDK only once and use it various places in your application. As soon as you initialize the SDK, it will contact the LicenseSpring server to check if there is an existing license for the current computer/product combination.
If there is a current license available, it will be immediately accessible as a License object.
At the minimum there are three parameters you will need to initialize the SDK:
apiKey, your company API key
sharedKey, company-specific encryption key, used when signing requests
productCode, an alphanumeric code identifying a specific product
The apiKey andsharedKey are available in the LicenseSpring Platform under "Setting -> Settings -> Keys tab". The productCode is tied to a specific product the license applies to and is defined while creating the product.
Optional Configuration parameters for initializing the License Client SDK:
licenseFilePath determines where the license file will be stored on user's computer. By default, it is set to current working directory of the application with the filename license.key
offlineMode enables offline mode. In this mode no requests are sent to LicenseSpring servers. Default is false.
enablePeriodicCheck indicates if the Consumption APIs should be invoked periodically. Use with Consumption type licenses - when caching license state is required.
checkPeriod period of invocation of the checkLicense method. Defaults to 1 hour if Duration object is not provided. Enabled by the enablePeriodicCheck flag.
requestLogging request logging for debug purposes, default is no request logging.
appName name of the application using the SDK.
appVersion manually set the version of the application that's using the SDK.
identityProvider set a custom IdentityProvider which generates unique keys for a particular device. Default implementation is based on Motherboard/CPU/Disk. See Java Hardware (Device) IDs for more information.
cacheHardwareId set to true to allow caching of hardware IDs. Default is false
gracePeriodDays period of days in which user can check License locally if API license check fails, this can either be a connection error or internal server error. Maximum of 30 days.
ignoreServerExceptions similar to gracePeriodDays, SDK will check License locally if API license check fails, but with no time limit
enableNegativeConsumptions enables the option to send negative consumptions, default is false.
proxyPort and proxyHost used to setup a forward proxy, see more in Java Advanced Usage.
requestTimeout set the timeout of requests make to API (in seconds), default is 10 seconds
storeMachineInfo - false by default. This toggles the collection of additional machine data, which includes:
hostname
ipAddress
macAddress
vmInfo
osInfo
infoToStore - specify what information to store, ignored if storeMachineInfo is false, defaults to ALL if left empty.
airGappedPublicKey - public key generated in the platform for air-gapped Licences
Java
|
// configuration with only required parameters// NOTE building a LicenseSpringConfiguration without required parameters will throw a LicenseSpringConfigurationExceptionLicenseSpringConfiguration configuration =LicenseSpringConfiguration.builder().apiKey("api_key").productCode("product_code").sharedKey("shared-key").build();// configuration with more parametersLicenseSpringConfiguration configuration =LicenseSpringConfiguration.builder().apiKey("api_key").productCode("product_code").sharedKey("shared-key").licenseFilePath("custom/path").enablePeriodicCheck(true).checkPeriod(Duration.ofHours(3)).requestLogging(Logger.Level.FULL).appName("MyApplication").appVersion("1.1.0").cacheHardwareID(true).gracePeriodDays(3).enableNegativeConsumptions(true).requestTimeout(60L).storeMachineInfo(true).infoToStore(InfoToStore.IP_ADDRESS).build();
LicenseManager
After setting up the SDK, there are a number of methods and objects available to the app developer. LicenseManager is a singleton that needs to be initialized once per runtime but can be retrieved using the getInstance method unlimited number of times.
Java
|
LicenseManager licenseManager =LicenseManager.getInstance();// initialize the manager once per runtime with the configuration// from the example above as a parametertry{
licenseManager.initialize(configuration);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// ortry{if(!licenseManager.isInitialized()){
licenseManager.initialize(configuration);}}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}
getCurrent()
In case no active license is available from the LicenseRepository, the return value will be null.
Java
|
License currentLicense = licenseManager.getCurrent();if(currentLicense ==null){// this means there are no active licenses on this device// actions taken in this if block depend on your needs// you can provide the user a new license (if user is a new user)// you can reactivate the license// you can prompt the user to pay to get a new license (if for example, his subscription ended and his previous license expired)// if the user is a first time user of your product you might wanna provide him a trial license if your product has a trial period// to figure out what you want to do here see other methods from the LicenseManager that are at your disposal and you might get a grasp of what your use case would be}else{// this means there is an active license for your product on the device// you can continue with your application flow}
getTrialLicense(String email)
You can generate a trial key directly from the app using the SDK, which will automatically associate this license key with the provided email. You can later use this data from the LicenseSpring platform to send out email campaigns targeting trial users for example.
After you generate a trial key - the UnactivatedTrialLicense object will be returned, you still need to activate it using a call to licenseManager.activateLicense()
Java
|
try{UnactivatedTrialLicense trial = licenseManager.getTrialLicense("someemail@gmail.com");License license = licenseManager.activateLicense(trial.createIdentity());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());return;}// if there weren't any exceptions // the LicenseManager will save the license // locally on the device using the LicenseRepository save() method
getTrialLicense(Customer customer)
You can generate a trial key directly from the app using the SDK, which will automatically associate this license key with the provided customer. Customer object can be built using the builder, only email is required.
Java
|
// customer with only required fieldCustomer customer =Customer.builder().email("someemail@gmail.com").build();// more verbose customer objectCustomer customer =Customer.builder().firstName("John").lastName("Doe").companyName("Company").email("someemail@gmail.com").phone("000-111-000").reference("reference1212").build();try{UnactivatedTrialLicense trial = licenseManager.getTrialLicense(customer);License license = licenseManager.activateLicense(trial.createIdentity());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());return;}
activateLicense(ActivationLicense identity)
Attempts to activate the product using provided ActivationIdentity. Returns the License object that has been activated.
Java
|
// keybasedActivationLicense keyBased =ActivationLicense.fromKey("license-key");try{License activated = licenseManager.activateLicense(keyBased);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// OR username/pass based - Note that this is the only API which requires the password.// LicenseSpring will never store user passwords via the SDK.ActivationLicense userBased =ActivationLicense.fromUsername("username","password");try{License activated = licenseManager.activateLicense(userBased);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}
deactivateLicense(LicenseIdentity identity)
License is deactivated using a method on the LicenseManager. You need to supply the current license identity.
Returns the latest valid installation file, if installation files are defined in the LicenseSpring platform. For more details please see Product Versioning.
Tracks device based variables for end uses. Can use the Variable builder as a utility.
Java
|
tr// KEY BASED// build your own Maptry{
licenseManager.trackVariables(LicenseIdentity.fromKey("sample-key"),newHashMap<>());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// use utility class to add some variables and track themDeviceVariables deviceVars =DeviceVariables.builder().variable("one","some value").variable("another_var","other_value").build();try{
licenseManager.trackVariables(LicenseIdentity.fromKey("sample-key"), deviceVars.getVariables());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// USER BASED// build your own Maptry{
licenseManager.trackVariables(ActivationLicense.fromUsername("username","password"),newHashMap<>());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// use utility class to add some variables and track themDeviceVariables deviceVars =DeviceVariables.builder().variable("one","some value").variable("another_var","other_value").build();try{
licenseManager.trackVariables(ActivationLicense.fromUsername("username","password"), deviceVars.getVariables());}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}
Generates an offline activation file which can be uploaded to LicenseSpring platform and activate the license. Default location for saving the file is Desktop, or if it can't be found, user home, this only applies if destination string is null. Default name of the file is "ls_activation.req". For more information, see Offline License Activation.
Java
|
tr// KEY BASED// build your own Maptry{
licenseManager.trackVariables(LicenseIdentity.fromKey("sample-key"),newHashMap<>());// key based with default file location try{
licenseManager.offlineActivationFile(LicenseIdentity.fromKey("key"),null);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// key based with custom file pathtry{
licenseManager.offlineActivationFile(LicenseIdentity.fromKey("key"),"/home/user/Downloads/offline/");}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with default file location try{
licenseManager.offlineActivationFile(ActivationLicense.fromUsername("username","password"),null);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with custom file pathtry{
licenseManager.offlineActivationFile(ActivationLicense.fromUsername("username","password"),"/home/user/Downloads/offline/");}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}
Generates an offline deactivation file which can be uploaded to LicenseSpring platform and deactivate the license. Default location for saving the file is Desktop, or if it can't be found, user home, this only applies if destination string is null. Default file name is ls_deactivation.req.
Java
|
// key based with default file location try{
licenseManager.offlineDeactivationFile(LicenseIdentity.fromKey("key"),null);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// key based with custom file pathtry{
licenseManager.offlineDeactivationFile(LicenseIdentity.fromKey("key"),"/home/user/Downloads/deactivate/");}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with default file location try{
licenseManager.offlineDeactivationFile(ActivationLicense.fromUsername("username","password"),null);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with custom file pathtry{
licenseManager.offlineDeactivationFile(ActivationLicense.fromUsername("username","password"),"/home/user/Downloads/deactivate/");}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());
Activates the license from a file that was generated on the LicenseSpring platform. If the filePath is null, SDK will look for the file ls_activation.lic in Desktop, or in user home.
Java
|
// key based with default file location try{License license = licenseManager.activateOfflineResponse(LicenseIdentity.fromKey("key"),null);}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// key based with custom file pathtry{License license = licenseManager.activateOfflineResponse(LicenseIdentity.fromKey("key"),"/home/user/Downloads/");}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with default file location License license = licenseManager.activateOfflineResponse(ActivationLicense.fromUsername("username","password"),null);try{}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}// user based with custom file pathLicense license = licenseManager.activateOfflineResponse(ActivationLicense.fromUsername("username","password"),"/home/user/Downloads/");try{}catch(LicenseSpringException e){
log.error(e.getCause().getMessage());}