Follow

Java API

The Java language API is built into the same jar used for the Command Line interface and relies on the subscription file deployed with your application.  The licensing.properties file should be in one of the following locations for the API to find it:

  • The user's home directory (if you application is a command-line)
  • The application server's user's home directory (if your web application is deployed to a JEE application server or servlet engine such as Websphere, Weblogic, JBOSS or Tomcat
  • The application server's application home directory (usually within the webapps directory)
The Java API consist of a single class, HCILicensing (contained in the package com.heirloomcomputing.ecc) , in the jar file HCILicensing.jar which has a single public static method checkLicense() defined.  Because this is a static class it need not be instantiated, its only methods are static.

LicenseCheck Method


public static String LicenseCheck(String product, Integer count)
  • product - the product GUID to check, as defined in your LaaS instance through the Administrators Interface.  If null the product id embedded in the licensing file is used
  • count - the transaction count which should be combined with the transaction count for the license to the product on the LaaS server, if null a count of 1 is assumed
The return will be the empty string ("") if the license checked OK or a non-empty string describing the problem.   There are two classes of these errors, the first is returned from the API itself regarding problems with the local environment:
  1. HCI907E Unable to verify your Heirloom Computing subscription, is HTTPS communication allowed from your location?
    • The client checking program uses HTTPS to communicate with your LaaS license server, some installations may prohibit Internet communication and/or SSL communication with an outside server.  In these cases a proxy-checker is required (see below)
  2. HCI102E License Error -- Unable to locate the licensing properties file containing your subscription information and cannot create a new one at 'xx'
    • The client checking program could not locate the licensing.properties file.  Each new installation of your product with the license checking API must have a properties file containing identifying customer information (e-mail address and subscription ID). If this information is provided to the API it will attempt to create a file in the current user's home directory.
  3. HCI103E License Error -- Unable to locate the licensing properties file containing your subscription information
    • Similar to above, but could not read any of 5 different locations where licensing.properties is typically stored 
  4. HCI106E License Error -- Customer subscription ID not specified
    • The licensing.properties file was found, but does not contain the subscription_id indicator 
  5. HCI107E License Error -- E-mail address not specified
    • The licensing.properties file was found, but does not contain the email_address indicator 
  6. HCI101E License Error -- Product code not specified
    • The licensing.properties file was found, but does not contain the product_id indicator and the API received a null product id
  7.  HCI108E License Error -- Unable to write license properties file '%s'
    • The licensing file must be writable to hold intermediate transaction count information between check-every intervals
  8. HCI109E License Error -- Corrupted transaction count within license properties file
    • The licensing.properties file was either copied over between invocations of the API or it was corrupted in some way such that the encrypted transaction count has been mutilated.  A "license reset" on the license server must be performed permitting the transaction count to be reset on the client
  9. HCI902E Failed checking Heirloom Computing subscription
    • The license checking Web service has determined there is an issue with the license for the product by the subscriber and the following section describes those.
The second class of errors accompany HCI902 error message and are returned from the licensecheck Web service and reflect issues with the license, restriction, etc:
  1. This license type has been disabled. 
    • The license or its associated restriction record has the Enabled attribute of False -- immediately revoking the license for the user
  2. This license type can only be used within an HCI cloud instance.
    • The associated restriction record indicates that this licensecheck request may only be issued from within the ELPaaS cloud
  3. Your signature does not match for this subscription / mac address
    • The associated restriction record of this license indicates a certain maximum number of unique network card addresses and this maximum has been reached.  A 'license reset' operation is required to erase all existing MAC addresses captured for this user
  4. You have exceeded the number of systems on which this product can be installed for this subscription
    • The associated restriction record of this license indicates a certain maximum number of unique systems addresses and this maximum has been reached.  A 'license reset' operation is required to erase all existing MAC addresses captured for this license
  5. You have exceeded the number of IP addresses from which this product can be invoked for this subscription
    • The associated restriction record of this license indicates a certain maximum number of unique gateway IP addresses and this maximum has been reached.  A 'license reset' operation is required to erase all existing IP associations captured for this license
  6. You have exceeded the number of host machines, or local IP addresses, from which this product can be invoked for this subscription
    • The associated restriction record of this license indicates a certain maximum number of unique local IP addresses and/or host machine names and this maximum has been reached.  A 'license reset' operation is required to erase all IP associations captured for this license
  7. Your subscription ended 'yyyy-mm-dd'
    • This license is expired and the grace period has run out
  8. Your subscription is restricted to a different system type
    • The associated restriction record for this license locks it down for use on certain machine types (e.g., Windows 64-bit) but the license request comes from a different machine type

 LastLicenseCheck Method


public static int LastLicenseCheck()

Returns the state of the most recent LicenseCheck operation:

  • 0 - not yet checked
  • 1 - checked and valid
  • 2 - checked but invalid (expired, comm error, etc -- returned on last LicenseCheck)

Offline Checking

You can run your application "offline" without the need of an Internet connection and use a "Proxy Checker" machine to synchronize the licensing file.  See the section Proxy Checker in the Command Line Interface article on Licensing-as-a-Service.

Example

Check License

Check the license for the product that is defined in the licensing.properties file and increase the transaction (usage) count by 1 from a program called BasicProduct.  

import com.heirloomcomputing.ecc.HCILicensing;
public class BasicProduct {
    public static boolean verify() {
        String reason = HCILicensing.LicenseCheck(null, null);
        if (reason.isEmpty()) {
            return true;
        } else {
            System.err.println("Sorry, your license could not be verified: "
                + reason);
            System.err.println("Please see our web site to renew your license");
            return false;
        }
    }

    public static void main(String [] args) {
        boolean result = verify();
        if (result) {
            System.out.println("Basic Product is working...");
        } else {
            System.out.println("Basic Product cannot continue operation");
        }
    }
}

Compile this program with the command:

javac -cp HCILicensing.jar BasicProduct.java

You may want to create a jar file with the contents of the HCILicensing.jar together with your program or combine your program into a .ear or .war file while referencing the enclosed HCILicensing.jar through the manifest's Class-Path directive.  HCILicensing.jar is redistributable to your customers to allow them to verify their license files and perform the proxy checker process.  Remember, you can customize the Error Messages within HCILicensing for your company.  To run this from the command line, issue the following command:

root@pineapple:~$ java -cp HCILicensing.jar:. BasicProduct
Basic Product is working...
root@pineapple:~$

The license properties file is created with the Command Line Interface and contains at minimum the subscription_id,email_address, license_domain and check_service elements.  The product_id may be supplied as a parameter to the command line or API method.

#Heirloom Computing, Inc - License and Transaction Checking
#Fri Mar 01 13:16:28 PST 2013
check_service=http://myco.instances.heirloomcomputing.com/rest/2013-03-01/licensecheck
license_domain=myco
645d7dce-1b35-49f2-adb4-d027e1abc165.count=\u0001\u0000
email_address=myco@myco.com
product_id=645d7dce-1b35-49f2-adb4-d027e1abc165
subscription_id=00000000-8181-616d-6b72-61686e796569

Licensing.properties files are personalized and updated the first time a license is checked against them.  At that point the file is "locked" to that machine and cannot be transmitted to another unless for proxy checking purposes.  The number of machines the initial licensing.properties files may be installed upon (before being personalized) is based on the restriction attributes associated with the license.  See the LaaS OverviewWeb Services and Administration Interface for more information.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk