Licensing Library Quick Start

Getting the Licensing Library

To integrate the LICENSE4J licensing functionality into your project, the initial step is to add the licensing library to your project's dependencies. The library is conveniently hosted on , the central repository for Java libraries.

For Maven users, you'll need to add a dependency entry to your pom.xml file. If you're using Gradle, you'll include a similar entry in your build.gradle file. This ensures that your build tool automatically downloads and includes the LICENSE4J library and all its necessary components, allowing you to begin implementing licensing features without manual setup.

Early Initialization of the License Instance

It's crucial to initialize the license instance at the very beginning of your software's execution lifecycle, ideally within the initial lines of your main method or an equivalent application bootstrap process. This ensures that the licensing framework is set up and ready before any license-dependent features are accessed.

During this initialization phase, you'll use the builder class to configure all necessary settings. This includes specifying critical details such as product identifiers, the desired location for saving and loading license data (e.g., file system path or Windows Registry key), parameters for generating a unique device fingerprint, and the network address of your license server. Performing this setup early guarantees that the license object is globally available as a singleton throughout your application, providing seamless access to licensing validation and management functions whenever needed.

// The minimal license builder
License.getInstance().getBuilder()
        .product("product-hash-code") // the only required argument
        .build();

// All options used.
License.getInstance().getBuilder()
        .product("product-hash-code") // the only required argument
        .file(System.getProperty("user.home") + "/MyProduct/license.l4j") // license file location to save and load 
        .registry("MyProduct", "license") // on Windows, save and load license to registry
        .feature("edition", mySoftwareEdition) // a feature if needed
        .feature("version", "1.1.0") // a feature if needed
        .feature("some-feature-name", "enabled") // any custom feature
        .server("https://license.company.com") // if using on-premises license server
        .build();

Initial License Validation on Startup

Following the successful initialization of your license instance, the next crucial step is to invoke the validate method without any arguments. This call serves a vital purpose: it instructs the licensing library to search for a previously activated and saved license on the user's system, either on the local disk or within the Windows Registry, as configured during the builder setup.

If a saved license is found, the validate method will then proceed to validate its integrity and current status. This includes checking against the device fingerprint, license expiration, and any other defined parameters to confirm the license remains valid for continued use. This process ensures that legitimate users with existing licenses can seamlessly launch and operate the software without needing to re-enter their license key every time.

// Validate previously activated license
License.getInstance()
        .validate() // validate previously activated license

Handling New or Missing Licenses

If the initial call to the validate method (without arguments) does not find a valid, previously activated license—which is typically the case during the software's first run or after a system change—your application should then prompt the user for a license key. This is the critical juncture where the user provides their purchased or trial license.

Once you've successfully obtained the license key from the user, you must immediately invoke the validate method again, this time passing the provided license key as an argument. This action is pivotal as it instructs the library to both validate the authenticity of the key against the configured license server and, upon successful verification, activate the license for the current device. This step should always be performed whenever a new license key is supplied by the user, ensuring the software becomes fully functional based on the entitlements of that key.

// Validate the given license key
License.getInstance()
        .validate("12345-12345-12345-12345") // validate the license key obtained from user

Retrieving License Status and Error Information

After attempting to validate or activate a license, it's essential to ascertain the outcome of that operation. The getStatus method is specifically designed for this purpose. By calling this method, you can retrieve comprehensive information regarding the license's current state, including its validity and any specific error messages that may have occurred during the validation or activation process. This granular feedback is crucial for both debugging potential issues and providing clear, actionable information to the end-user. The getStatus method ensures you have immediate access to the license's operational status and any associated diagnostics.

// Validate previously activated license
License.getInstance()
        .validate() // validate previously activated license

// License status and errors if found
License.getInstance()
                .getStatus()
                .isValid(); // returns boolean

License.getInstance()
                .getStatus()
                .getCode(); // return error code

 License.getInstance()
                .getStatus()
                .getMessage(); // returns a simple descriptive string