Use license key for licensing operations

For an overview of consuming licenses using license keys, see the following sections in the 10Duke Scale documentation:

• Key Concepts: License consumers
• How To Consume Licenses
• Access the APIs: License keys

See also client concepts.

Workflow description

The client application first either prompts the user to enter a license key or reads the license key, for example, from configuration. Next, the client application requests information on the license(s) the license key entitles the user to use. This information can be used to communicate further with the user. The client application then checks out a license using the license key. The workflow continues with optional periodic heartbeat calls and concludes with a call to release the license.

Configuration

The minimum viable configuration requires setting the licensing API URL. HTTP request timeout is an optional configuration.

For more configuration options, see the configuration guide.

Example

First, let's look at the main program of this example, a Java CLI application that implements the following flow:

• initialize the application and 10Duke Scale SDK
• prompt the user to enter a license key
• query information on the license(s) that the key entitles the user to use
• check out a seat
• release the checkout

public static void main(final String[] args)
        throws IOException, InterruptedException, URISyntaxException {
 
    CliLicenseKeyExample example = new CliLicenseKeyExample();
 
    // Bootstrap the client app and sdk
    example.initClientApp();
 
    // Prompt for a license key
    example.promptLicenseKey();
    if (example.licenseKey == null) {
        System.out.println("No license key given, bye bye...");
        return;
    }
 
    // Query license information using the license key
    LicenseKeyLicensesStatus licenseInfo = example.describeLicenseKey();
 
    // pick the first license to demonstrate checkout
    example.selectedLicense = licenseInfo.getLicenses().get(0);
 
    // Checkout the license
    LicenseToken licenseToken = example.checkoutLicense();
    System.out.println(
            "License checkout made for product "
            + licenseToken.getProductName()
            + " with status: "
            + licenseToken.getStatus());
 
    // Release the license
    LicenseReleaseResult releaseResult
            = example.releaseLicense(licenseToken);
    if (releaseResult != null) {
        System.out.println(
                "License release made for product "
                + releaseResult.getProductName()
                + " with status: "
                + (releaseResult.getErrorCode() == null
                ? " success"
                : releaseResult.getErrorCode()));
    }
 
    // Example end
    System.out.println("All done, bye bye...");
}

Initialize the client application to use the 10Duke Scale SDK. The following example shows how to set up a client application to use license keys.

private void initClientApp() throws IOException, URISyntaxException {
    String configResource = "tenduke.conf";
    String userAgent
            = "tenduke-scale-sdk-java-cli-example/1.0.0";
    clientBuilder = new DesktopAppClientBuilder(
            configResource,
            userAgent);
    try {
        client = clientBuilder.initForLicenseKeyBasedLicensing();
    } catch (SdkException ex) {
        Logger
                .getLogger("CliLicenseKeyExample")
                .log(
                    Level.SEVERE,
                    """
                    Startup error, tip: check config file
                    and that APIs can be reached""",
                    ex);
        throw ex;
    }
}

Query which license(s) the license key entitles the user to use.

private LicenseKeyLicensesStatus describeLicenseKey() {
    LicenseKeyLicensesStatus result = client.getLicenseCheckoutClient()
            .describeLicenseKeyLicenses(licenseKey, true);
    if (result == null || result.getLicenses().isEmpty()) {
        throw ExceptionBuilder.internalError(
                """
                Expecting information about one license from
                call to describe license key, got none.""");
    }
    return result;
}

Check out a license, based on selecting the first license returned from the information query.

private LicenseToken checkoutLicense() {
    long qty = 1;
    if (!QuantityDimension.SEATS.equals(
            selectedLicense.getQtyDimension())) {
        System.out.println(
                "Enter quantity to consume,"
                + " mind that license has:"
                + selectedLicense.getQty()
                + " remaining.");
        qty = scanner.nextLong();
    }
    Map<String, String> claims = new HashMap<>();
    claims.put("cliHwId", hwId());
    LicenseCheckoutArguments checkoutArguments
            = LicenseCheckoutArguments
                    .builder()
                    .productName(
                            selectedLicense.getProductName())
                    .qty(qty)
                    .qtyDimension(
                            selectedLicense.getQtyDimension())
                    .build();
    List<LicenseToken> result = client.getLicenseCheckoutClient()
            .checkoutLicenseByKey(
                    licenseKey,
                    claims,
                    Collections.singletonList(
                            checkoutArguments));
    if (result.size() != 1) {
        throw ExceptionBuilder.internalError(
                "Expecting 1 license token from"
                + " checkout 1 license, got "
                + result.size()
                + " instead");
    } else {
        return result.get(0);
    }
}

Finally, release the license based on the current checkout.

private LicenseReleaseResult releaseLicense(
        final LicenseToken licenseToken) {
    if (licenseToken.getLeaseId() == null) {
        System.out.println(
                "Null lease id, nothing to release.");
        return null;
    }
    long qty = 1;
    if (!QuantityDimension.SEATS.equals(
            selectedLicense.getQtyDimension())) {
        System.out.println(
                "Enter final quantity that was consumed:");
        qty = scanner.nextLong();
    }
    Map<String, String> claims = new HashMap<>();
    LicenseReleaseArguments releaseArguments
            = LicenseReleaseArguments
                    .builder()
                    .finalUsedQty(qty)
                    .leaseId(licenseToken.getLeaseId())
                    .build();
    List<LicenseReleaseResult> result = client
            .getLicenseCheckoutClient()
            .releaseLicense(
                    claims,
                    licenseKey,
                    Collections.singletonList(
                            releaseArguments));
    if (result.size() != 1) {
        throw ExceptionBuilder.internalError(
                "Expecting 1 license release result"
                + " from release 1 license, got "
                + result.size()
                + " instead");
    } else {
        return result.get(0);
    }
}