Java
ISV Application Development Guide
Overview Of License Enabling Activities
Defining Your License Management Policies
Example Of Single-User License Key Check
Example Of Server License Key Check (Professional Edition Only)
Example Of License Key Check With Customization For OEM Key (Professional Edition Only)
This document guides you through the specifics of the process of license-enabling your Java product with EasyLicenser. It adds detail to the overview of the EasyLicenser Java Run Time Library API that is presented in the EasyLicenser Concepts guide.
The activities encompass:
A (no pun intended) key decision you need to make at the onset is whether you wish to enforce locking your license keys to specific hardware and / or operating system. Although locking your key provides a high degree of protection, it is also a sales inhibitor, as it subjects your end-customer to onerous procedures both at the time you take their order and whenever customers want to relocate their product installation. The approach is also less portable across platforms. The next decision you need to make is what you want to lock your key to: proprietary hardware, or the logical operating system runtime environment. If the former, you will need to implement or obtain hardware and operating system specific code and plug it into the EasyLicenser runtime framework. If the latter, you can utilize EasyLicenser's built-in enforcement facilities.
When your product is licensed for time limited or metered use, you can decide on what you want to have happen when a license key check indicates an expiring or expired key. You can define thresholds for generating warnings on expiring keys and grace periods or quotas to suppress generating errors when a quota or expiration date is exceeded.
EasyLicenser has built-in license management models, types and parameters. If you have a specialized need for your own variation to the built-in policies, you can accomplish this by defining your own custom handler.
The specific mechanics of accomplishing these tasks are described below.
Four API calls are available with the EzLicenseInfo class for checking a license key:
If your application does not require customized or highly secure license management, you can use either of the first two API’s according to whether your product is a user or server product. Otherwise, you will find it convenient to use one of the functionally complete APIs.
The specific details of the API are available in the Java Run Time Library API Reference Java documentation. Some simple examples will be illustrated below that show how the API’s are used in typical application scenarios. Source and binary code for additional examples are available in the “demo” and "samples" directories. In particular, the "jdemo.java" application is a simple "Hello World" application that performs a simple check on a license key provided as an input parameter based on a specified user / host name. For details on the demo program and how to run it, see the description of the directory structure in the Setup, Management And Deployment Guide. The "jdemosecure.java" application is similar to "jdemo.java", but illustrates the use of the secure API.
Suppose you have a desktop application such as a file management utility program that you sell to end consumers.
Whenever a new customer visits your web site and downloads your application and pays by credit card for a perpetual license to use it, your web site defines a serial number or user id, which is also used as the EasyLicenser user name input to a key your web site programmatically generates and emails to your customer. The key that you generate is a User license model, of User license type. It is not time limited and does not have a quota limit defined on it.
At product installation time, your product asks the user for the key, which is then stored in the operating system registry. Subsequently, each time the user runs your product, it prompts your user for the user id authentication information. Your code can take that user name input, retrieve the license key from the registry, and perform the license key check as follows:
// imports
import com.vs.ezlicrun.*;
// First, prompt for the login name
String userName =
(String) JOptionPane.showInputDialog(
null,
"Enter User Name:", "Login",
JOptionPane.PLAIN_MESSAGE);
userName = userName.trim();
:
// Check the license key that is already obtained
// from the registry into a “config” class.
EzLicenseInfo licenseInfo = new
EzLicenseInfo();
try {
int warnings =
licenseInfo.checkSingleUserLicenseKeyBasic(
config.getLicenseKey(),0, 0, 0,
0, 0,userName);
} catch (EzLicExceptionBase eek)
{
JOptionPane.showMessageDialog(
(JComponent)null,
"You are not licensed to use this product. " +
"Please contact technical support.",
"Licensing Error",
JOptionPane.ERROR_MESSAGE);
System.exit(1);
}
Suppose you have a Unix-based application server product that you wish to license by the number of concurrent sessions on the application server. You wish to lock the user into a specific host machine, therefore you adopt an enforced host naming policy that requires your customer to provide you with the DNS host name for their server machine at the time of accepting an order and generating a key.
The key that you generate is of a Server license model, and Concurrent User license type. At the time of generating the key, you specify an upper limit on the number of concurrent users according to what your customer paid for. It is not time limited, and you do not define a quota limit on it. The host name that you specify is based on what your customer tells you. Your customer obtains this information through a "uname -a" shell command on the server machine targeted for deployment of your application.
Your server application is designed to load at startup time an application property text file that includes, among other items, the license key and the host name, similar to the following:
:
LicenseKey=tFy67+h=…
HostName=licensedHostName1
:
At run time, either periodically or in response to specific events such as session initiation, your product code can interrogate its environment to obtain the number of active sessions and the application properties and check the license:
// imports
import com.vs.ezlicrun.*;
// First, get the host name and license key,
// and the active sessionCount
String hostName = AppProperty.getProperty(“HostName”);
String licenseKey = AppProperty.getProperty(“LicenseKey”);
long sessionCount = App.getActiveSessionCount(); // the current value
:
// Check the license key
EzLicenseInfo licenseInfo = new
EzLicenseInfo();
try {
int warnings =
licenseInfo.checkMultiUserLicenseKeyBasic(
licenseKey, 0, 0, 0, 0, 0,
hostName, sessionCount);
} catch (EzLicExceptionBase eek)
{
// log warning and / or throw exception
// according to your preference
}
Suppose you are an OEM reseller and your desktop product embeds infrastructure GUI technology obtained from an OEM. Your OEM would like to ensure that their embedded product can only be used in the context of your product. It should not be possible for your customer to decompose your product to extract the OEM’s product and make unlicensed use of the latter. At the same time, you do not wish to impose an additional license management burden on your customer – you wish to distribute a single key to your customer.
Your OEM can provide you with their key, which may or may not be based on EasyLicenser. At the time of key composition, you can go to the Custom tab and provide the OEM key value in the Custom Key text area as follows:
oemkey=tFyU6h7G….
Your application code that checks for the license key will include a custom key handler that extracts the name-value pair and puts it into a hash table that is maintained by the EasyLicenser run time:
// imports
import com.vs.ezlicrun.*;
EzLicenseInfo licenseInfo = new EzLicenseInfo();
try {
int warnings =
licenseInfo.checkLicenseKey(
licenseKey,
// Built-in custom key handler,
// defined in EasyLicenser
Run Time Library
(new EzLicCustomKeyHandler()),
// No application context needed
for this handler
null,
0, 0, 0, 0, 0,
username, 0);
} catch (EzLicExceptionBase eek)
{
JOptionPane.showMessageDialog(
(JComponent)null,
"You are not licensed to use
this product. " +
"Please contact technical support.",
"Licensing Error",
JOptionPane.ERROR_MESSAGE);
System.exit(1);
}
You instruct your OEM to make the following call the first time it is invoked by your code (which necessarily follows the above code fragment in time):
String oemkey = (new EzLicCustomKeyHandler()).
getCustomKeyValue("oemkey");
At this point, your OEM can perform the necessary license key check according to the technology that was used to generate the key. Suppose the OEM used EasyLicenser to generate the OEM key. Then the OEM’s code would be similar to the following:
EzLicenseInfo oemLicenseInfo = new
EzLicenseInfo();
int oemwarnings =
oemLicenseInfo.checkSingleUserLicenseKeyBasic(
oemkey,0, 0, 0, 0, 0,
// User name is based on the product /
// company being OEM’ed to
"YourProductName");
The above approach can be extended to any number of embedded OEM keys, possibly in combination with other customizations. To accomplish this, simply provide a list of name-value pairs instead of a single name-value pair. The only constraint is that the names should be unique, and the separator (or any text anywhere in the custom key field) should not be a ‘:’ character.
It is sufficient to copy lib/ezlicrunVV.jar from the EasyLicenser installation root directory into your build environment and include it in your class path.
When you package your Java product, include the above jar file in your zip file or executable Jar in the usual fashion.
Refer to the Java Run Time Library API Reference for specific information on the EasyLicenser Java Run Time Library API that you will use while writing your Java product’s license-enabling code.