License Instance Initialization

The License.getInstance().getBuilder() method is your entry point for configuring every aspect of your software's licensing. This method returns an instance of the Builder class, which provides a fluent and intuitive API designed to simplify the setup process.

Through this Builder, you can define all the essential settings for your software license, ensuring it behaves precisely as required. This includes specifying critical details such as the product's unique identifier, the desired persistence mechanism and location for license data (e.g., a specific file path on disk or a key within the Windows Registry), parameters for generating a unique device fingerprint to bind licenses to specific hardware, and the network address of your license server for online validation and activation. By centralizing these configurations within the Builder, you gain a clear, organized, and robust way to prepare your license instance before it's used throughout your application.

// 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();

.product(String productHashValue): Within the LICENSE4J system, each product is uniquely identified by a hash value derived from its public key. This distinct hash plays a crucial role in the licensing process: it's used to efficiently locate and associate the correct product when a license activation request is received by the server. This mechanism ensures that incoming license keys are accurately matched to their corresponding software products for validation and activation.

.file(String file): method is used to explicitly define the precise location where the license data will be loaded from and saved to. If it is not specified, the system defaults to a structured path within the current user's home directory. This default path is constructed by appending a unique identifier derived from the product's hash code. Specifically, it uses the last eight characters of the product's hash code to create a distinct subfolder.

For instance, if a product's hash code is 94E1B381016BEE2CBC5F644B6F078C28 and the current username is john, the default license file location on a Windows operating system would be C:\Users\john\.6F078C28\license.l4j.

Programmatically, this default path is generated as: System.getProperty("user.home") + File.separator + "." + {last 8 characters of hash code} + File.separator + "license.l4j" This automatic fallback ensures that a consistent and isolated location is used for license persistence, even when a custom path is not explicitly provided.

.registry(String registryKey, String registryValue): method is specifically designed for Windows environments to designate the location within the system registry for loading and saving license data. If this method is not explicitly defined, the registry will not be utilized for license persistence on Windows systems; in such cases, the license data would typically default to file-based storage.

To leverage the Windows Registry, you must define a specific path where the license information will reside. A common and recommended approach is to use a subkey within HKEY_CURRENT_USER\SOFTWARE\. For instance, by calling registry("MySoftware", "license"), the license data will be saved and subsequently loaded from the HKEY_CURRENT_USER\SOFTWARE\MySoftware\ registry key. The actual license information will be stored as a REG_BINARY value named license within this path. This method provides a robust and centralized way to manage license data within the Windows operating system's native configuration store.

.feature(String key, Object value): method provides a powerful mechanism for embedding custom attributes or functionalities directly into your license definition. This method allows you to associate any key-value pair with a license, effectively extending its capabilities beyond standard parameters like expiry dates or user counts.

During license validation, the server checks if the features defined by this method on the client side match corresponding features configured on the license server for that specific license. If these custom feature checks align, the validation process proceeds successfully. Conversely, if there's a mismatch or the required feature is absent on the server-side license, the validation will fail.

.customFingerprint(String fingerprint): method offers powerful flexibility by allowing you to define a custom hardware fingerprint for license validation. While LICENSE4J provides its own robust fingerprinting mechanisms, this method enables you to integrate any unique identifier you choose to bind a license to a specific device or environment.

This custom fingerprint can be derived from various sources, such as: a username specific to a client machine, the system's hostname, a static IP address or a network block, or any other unique, programmatically generated string that consistently identifies the target device or even a virtual machine instance.

By using customFingerprint, you gain fine-grained control over how your licenses are locked to particular installations. This is especially beneficial for scenarios where standard hardware IDs might be insufficient, or when you need to align licensing with existing internal identification systems. During validation, the license server will check if the custom fingerprint provided by the client matches the one stored with the activated license, ensuring that the software is used only on the intended system.

.usbDongle(String vendorId, String productId, String licenseFileNamePath): method provides a highly flexible way to implement USB-based license dongles, allowing virtually any brand or model of USB stick or external disk to serve as a physical license key. This offers a tangible, portable licensing solution for your software.

You have the option to restrict license usage to specific USB devices by providing their unique vendorId and productId. This ensures that your license is tied to a particular type of USB dongle, enhancing security. Alternatively, you can omit these parameters if you wish to allow any USB device to act as the dongle.

To facilitate the identification of the USB device and the storage of license data, you must specify a license file path. This path indicates where a small, designated license file will be located on the USB device. It's important to note that even an empty file at this specified path will suffice before the initial validation; the actual encrypted license data will be written to this file upon successful activation. During subsequent validations, the system will look for this specific file on the connected USB device to confirm the license's presence and validity. This method provides a robust and portable licensing option, ideal for environments where physical control over license access is paramount. Example source about USB dongle usage is available at github.