SDKs
...
Java SDK
Java Modules

Java License Client

29min
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 \<dependencies> \<dependency> \<groupid>com licensespring\</groupid> \<artifactid>licensespring license client\</artifactid> \<version>2 16 1\</version> \</dependency> \</dependencies> \<repositories> \<repository> \<id>jdk java\</id> \<url>https //licensespring maven s3 eu central 1 amazonaws com/\</url> \</repository> \</repositories>repositories { mavenlocal() maven { url = 'https //licensespring maven s3 eu central 1 amazonaws com/' } } dependencies { implementation 'com licensespring\ licensespring license client 2 16 1' } 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 once and then use it throughout your application once initialized, the sdk contacts the licensespring server to check for an existing license for the current computer/product combination if a valid license is found, it becomes immediately available as a license object to initialize the sdk, you must supply authentication credentials and product information you can choose one of two authentication methods 1\ api key authentication apikey your company api key sharedkey a company specific encryption key used when signing requests 2\ oauth authorization clientid your client identifier clientsecret your client secret in addition to the authentication credentials, you must provide the productcode , an alphanumeric code identifying the specific product the apikey and sharedkey are available in the licensespring platform under "settings > settings > keys " for oauth authorization docid\ xhyzaual9qy4jerxkilmk , your clientid and clientsecret are available here oauth configuration docid\ q1yeced3kghzmwcsx2moj the productcode is defined when creating the product and ties the license to that specific 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 docid\ kinndeo4bghcv3azyvchm 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 docid\ mqlrngvkrepj5ivdgupt0 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 // configuration with only required parameters // note building a licensespringconfiguration without required parameters will throw a licensespringconfigurationexception licensespringconfiguration configuration = licensespringconfiguration builder() apikey("api key") sharedkey("shared key") productcode("product code") build(); // oauth minimum parameters licensespringconfiguration configuration = licensespringconfiguration builder() clientid("client id") clientsecret("client secret") productcode("product code") build(); // configuration with more parameters licensespringconfiguration 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 licensemanager licensemanager = licensemanager getinstance(); // initialize the manager once per runtime with the configuration // from the example above as a parameter try { &#x9;licensemanager initialize(configuration); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // or try { &#x9;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 license currentlicense = licensemanager getcurrent(); if (currentlicense == null) { // this means there are no active licenses on this device &#x9;// 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() 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 // customer with only required field customer customer = customer builder() email("someemail\@gmail com") build(); // more verbose customer object customer 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 // keybased activationlicense keybased = activationlicense fromkey("license key"); try { &#x9;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 { &#x9;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 // key based try { &#x9;boolean isdeactivated = licensemanager deactivatelicense(licenseidentity fromkey("sample key")); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based try { &#x9;boolean isdeactivated = licensemanager deactivatelicense(activationlicense fromusername("username", "password")); } catch (licensespringexception e) { log error(e getcause() getmessage()); } checklicense(license license) checks the license on the ls servers and syncs any consumptions made try { license updatedlicense = licensemanager checklicense(licensemanager getcurrent()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } getinstallationfile(licenseidentity identity) returns the latest valid installation file, if installation files are defined in the licensespring platform for more details please see product versioning docid\ sz5imovmj5qjawhelsoxt // key based try { &#x9;installationfile installationfile = licensemanager getinstallationfile(licenseidentity fromkey("sample key")); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based try { &#x9;installationfile installationfile = licensemanager getinstallationfile(activationlicense fromusername("username", "password")); } catch (licensespringexception e) { log error(e getcause() getmessage()); } getversions(licenseidentity identity) returns all the available versions for the product configured via configuration settings try { &#x9;string\[] versions = licensemanager getversions(licenseidentity fromkey("sample key")); } catch (licensespringexception e) { log error(e getcause() getmessage()); } trackvariables(licenseidentity identity, map\<string, string> variables) tracks device based variables for end uses can use the variable builder as a utility tr// key based // build your own map try { &#x9;licensemanager trackvariables(licenseidentity fromkey("sample key"), new hashmap<>()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // use utility class to add some variables and track them devicevariables devicevars = devicevariables builder() variable("one", "some value") variable("another var", "other value") build(); try { &#x9;licensemanager trackvariables(licenseidentity fromkey("sample key"), devicevars getvariables()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based // build your own map try { &#x9;licensemanager trackvariables(activationlicense fromusername("username", "password"), new hashmap<>()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // use utility class to add some variables and track them devicevariables devicevars = devicevariables builder() variable("one", "some value") variable("another var", "other value") build(); try { &#x9;licensemanager trackvariables(activationlicense fromusername("username", "password"), devicevars getvariables()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } getproductdetails() gets product details from licensespring servers try { product product = licensemanager getproductdetails(); log info(product getproductname()); log info(product getshortcode()); log info(product isallowtrial()); log info(product gettrialdays()); log info(product getauthorizationmethod()); } catch (licensespringexception e) { log error(e getcause() getmessage()); } offlineactivationfile(licenseidentity identity, string destination) 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 docid\ feyf5uic8a7rvjq9lcz3g tr// key based // build your own map try { &#x9;licensemanager trackvariables(licenseidentity fromkey("sample key"), new hashmap<>()); // key based with default file location try { &#x9;licensemanager offlineactivationfile(licenseidentity fromkey("key"), null); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // key based with custom file path try { &#x9;licensemanager offlineactivationfile(licenseidentity fromkey("key"), "/home/user/downloads/offline/"); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based with default file location try { &#x9;licensemanager offlineactivationfile(activationlicense fromusername("username", "password"), null); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based with custom file path try { &#x9;licensemanager offlineactivationfile(activationlicense fromusername("username", "password"), "/home/user/downloads/offline/"); } catch (licensespringexception e) { log error(e getcause() getmessage()); } offlinedeactivationfile(licenseidentity identity, string destination) 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 // key based with default file location try { &#x9;licensemanager offlinedeactivationfile(licenseidentity fromkey("key"), null); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // key based with custom file path try { &#x9;licensemanager offlinedeactivationfile(licenseidentity fromkey("key"), "/home/user/downloads/deactivate/"); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based with default file location try { &#x9;licensemanager offlinedeactivationfile(activationlicense fromusername("username", "password"), null); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // user based with custom file path try { &#x9;licensemanager offlinedeactivationfile(activationlicense fromusername("username", "password"), "/home/user/downloads/deactivate/"); } catch (licensespringexception e) { log error(e getcause() getmessage()); activateofflineresponse(licenseidentity identity, string filepath) 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 // key based with default file location try { &#x9;license license = licensemanager activateofflineresponse(licenseidentity fromkey("key"), null); } catch (licensespringexception e) { log error(e getcause() getmessage()); } // key based with custom file path try { &#x9;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 path license license = licensemanager activateofflineresponse(activationlicense fromusername("username", "password"), "/home/user/downloads/"); try { } catch (licensespringexception e) { log error(e getcause() getmessage()); } clearlocalstorage() clears all local license data try { &#x9;licensemanager clearlocalstorage(); } catch (licensespringexception e) { log error(e getcause() getmessage()); } setofflinemode(boolean offlinemode) changes the offline mode while the app is running while offline, no requests to ls servers are made try { &#x9;licensemanager setofflinemode(true); } catch (licensespringexception e) { log error(e getcause() getmessage()); } getairgapactivationcode gets the activation code use for air gapped license needs the licensespringconfiguration field airgappedpublickey to work with air gap licences airgappedactivation activation = licensemanager getairgapactivationcode( &#x9;licenseidentity fromkey("sample key"), "initializationcodefromplatform" ); log info(activation getactivationcode()); log info(activation gethardwareid()); log info(activation getlicensekey()); verifyairgapconfirmationcode verifies the confirmation code for air gapped license needs the licensespringconfiguration field airgappedpublickey to work with air gap licences boolean verified = licensemanager verifyairgapconfirmationcode( &#x9;licenseidentity fromkey("sample key"), "policyidfromplatform", "confirmationcodefromplatform" ); log info(verified); activateairgapresponse activates the air gapped license from the license policy file needs the licensespringconfiguration field airgappedpublickey to work with air gap licences license license = licensemanager activateairgapresponse( &#x9;licenseidentity fromkey("sample key"), "pathtopolicyfile", "policyid" ); log info(license gethardwareid()); log info(license getidentity() getlicensekey()); getairgapdeactivationcode gets the deactivation code use for air gapped license needs the licensespringconfiguration field airgappedpublickey to work with air gap licences airgappeddeactivation deactivation = licensemanager getairgapdeactivationcode( &#x9;licenseidentity fromkey("sample key"), "initializationcodefromplatform" ); log info(deactivation getdeactivationcode()); log info(deactivation gethardwareid()); log info(deactivation getlicensekey()); deactivateairgapresponse deactivates the air gapped license from the license policy file and deleted the local license file needs the licensespringconfiguration field airgappedpublickey to work with air gap licences boolean deactivated = licensemanager deactivateairgaplicense( &#x9;licenseidentity fromkey("sample key"), "pathtopolicyfile", "policyid" ); asserttrue(deactivated); license license = licensemanager getcurrent(); assertnull(license); getssourl gets the ssourl needed to activate the license using sso for more info, see single sign on url docid\ qbjwnphsdcs0l25uw6ptq note 1 the activation code is short lived and converts into a user based license after activation do not use the activationlicense object used to activate the license, rather use the license getidentity after activation note 2 the generated credentials are one time use, generating new ones will disable previous ssourl ssourl = licensemanager getssourl(customeraccountcode, ssoresponsetype code); //follow the url to get the "code" or "id token", this example is with "code" string customeraccountcode = "yourcustomeraccountcodewithssoconfigured"; string code = "codefromtheresponse"; //the activationlicense won't work after doing the activation //use license getidentity() for usage in other methods after activation activationlicense activationlicense = activationlicense fromssocode(code, customeraccountcode); license license = licensemanager activatelicense(activationlicense); license checkedlicense = licensemanager checklicense(license); boolean deactivated = licensemanager deactivatelicense(license getidentity()); changeoauthclientsecret changes the oauth client secret used for auth > in case you have a rotating secret licensemanager changeoauthclientsecret("otherclientsecret");