Java eCommerce Application Development Guide
Overview Of eCommerce Enabling Activities
Defining Your Dynamic Web Content Processing
Example Of Single-User License Key Generation
Example Of Server License Key Generation (Professional Edition Only)
Example Of License Key Generation With OEM Key Customization (Professional Edition Only)
Communicating Keys To Your Customer
This document guides you through the specifics of the process of programmatically generating license keys with EasyLicenser. It adds detail to the overview of the license key generation API that is presented in the EasyLicenser Concepts guide.
In order to be able to programmatically generate keys with EasyLicenser, you need to be licensed for the eCommerce option.
The activities encompass:
1. Defining your dynamic content processing and HTML forms to obtain the necessary license parameter information from the user.
2. Coding against the API.
3. Defining a system for communicating the license key(s) to the paying customer.
According to your product mix and licensing requirements, you will either hard-code or obtain from your user information on license parameters. Together with credit card payment information, you will use this information to drive the license key generation upon successful credit card authorization. When you use J2EE technologies for this purpose, the interface with the key generation API’s is seamless. Otherwise, you will need to provide a Java bridge from your paging technology, and implement the API calls for key generation in the Java side of the bridge.
The specific details of the API are available in the Java ECommerce License Key Generation API Reference Java documentation. Some simple examples will be illustrated below that show how the API’s are used in typical application scenarios.
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 based on a User license model, of User license type, with soft enforcement. It is not time limited and does not have a quota limit defined on it. A set of “evaluation” and “edition” options are enabled in the product according to what the customer paid. These are to be presented to your application as a semicolon-separated list of name-value pairs, for example “eval=Y;edition=standard”.
// imports
import com.vs.ezlicrun.*;
import com.vs.ezlicgen.*;
// Create user name object through some means,
// for example by looking up a database
String userName = UserInfo.makeUniqueUserName();
// Assemble option string, for example from
// servlet request object.
String optionStr = “eval=” + request.getParameter(“eval”) +
“;edition=” + request.getParameter(“edition”);
// Set your product name. If your web site is a
// one-product site, hard-code it.
String product = “MyUtilProduct”;
// Set your company name
String company=”Me, Inc.”;
// Get your end customer’s company name, for example
// from sevlet request object
String endCustomerCompany=request.getParameter(“company”);
// Define license mode bitmap to indicate options are specified.
int licenseModeBitmap =
EzLicenseInfo.EZLIC_MODE_OPTIONS;
// Define and populate the license info object
EzLicenseFullInfo licInfo = new
EzLicenseFullInfo();
licInfo.setLicenseModeBitmap(licenseModeBitmap);
licInfo.setLicenseModelCode(EzLicenseInfo.EZLIC_MODEL_USER);
// hard-code license model to User
licInfo.setLicenseTypeCode(EzLicenseInfo.EZLIC_TYPE_U_USER);
// hard-code license type to named user
licInfo.setOptions(optionStr);
// set option string for later retrieval by application code
licInfo.setUserHostNetName(username); // set user name
licInfo.setCreationDate(new
Date());
// set creation date to today’s date for auditing purposes
// Set creator name to the user name assigned to
// you by easylicenser.com.
licInfo.setCreatorUsername(EzLicenseConfig.
loadConfig().getUserName());
// Set up product and company
licInfo.setProductName(product);
licInfo.setCompanyName(company);
// Set up your customer’s company name
licInfo.setEndCustomerCompanyName(endCustomerCompany);
:
// Generate key
String key = null;
try {
key = licInfo.generateKey(
EzLicenseConfig.loadConfig().
getUserName());
} catch (EzLicExceptionBase
eek) {
errMsg = eek.getMessage();
if (eek instanceof
EzLicExceptionExpired)
expired = true;
// your EasyLicenser eval
license
// has expired
else if (eek instanceof
EzLicExceptionExceededLimits)
quota = true; // out of EasyLicenser
quota
}
:
if (key == null) {
// Do appropriate error response –
// the problem is most likely yours,
// not your customer’s
} else {
// send the key to the customer, perhaps
// also display it on customer’s screen etc.
}
Suppose you have an application server product that you wish to license by the number of concurrent sessions on the application server, which runs on a Unix system. 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 key is generated with operating system enforcement: the host name is set to the information your customer provides on the intended server machine. The system administrator at the customer site provides this information in advance based on the output of an appropriate operating system command such as "uname -a".
The code is very similar. Instead of supplying a user name to the license info, provide a host name that you obtain from your customer. Instead of specifying the license model to be EZLIC_MODEL_USER, specify it to be EZLIC_MODEL_SERVER instead. Specify the license type be EZLIC_TYPE_SVR_CONC for concurrent-user licensing, instead of EZLIC_TYPE_U_USER. In addition, you need to specify the upper limit on the number of concurrent users. You do this by obtaining the limit value from your web environment, for example the servlet request object, and setting the “usageValue” attribute in the license info prior to key generation:
long usageValue = Long.parseLong(
request.getParameter(
“concurrentLimit”));
// Also get host name instead of user name
// Get the other attributes such as your customer’s
// company name, etc.
:
// In addition to setting company name etc., also
// set the usage limit value.
licInfo.setUsageValue(usageValue);
// Enable OS check for host name
licInfo.setEnforce();
:
// Now generate the key (no changes here
// from single-user scenario)
:
Suppose 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. You can embed the OEM key into a custom key in a name-value format. Then the only changes to the first example are the specification of the “custom key” bit in the license mode bitmap and the addition of the following line of code prior to key generation:
// The following line must come before setting
// the bitmap in the license info:
licenseModeBitmap |= EzLicenseInfo.EZLIC_MODE_CUSTOM_KEY;
:
// Set the various attributes of licInfo, including:
licInfo.setCustomKey(“oemkey=” + oemkey);
// oemkey is a string that you set to the OEM-provided key
:
// Now generate the key (no changes here from
// earlier examples)
You can choose any means suitable to your environment and product to communicate generated keys to your customers. For security reasons, however, you probably do not want to embed the key into the product prior to a product download.
If each customer purchase corresponds to a single key, you can feed the key back to the customer through a JSP response page, and / or email the key to the customer’s email address. If a purchase is for a number of keys, you can generate the list of keys in a suitable file format and email the list or a temporary URL to the list to the customer, who can retrieve the list manually or programmatically according to their preference via http. If the customer will manually process the list, human readable text is appropriate. Otherwise, for automated processing or import into a database, you can choose an XML or a comma / tab separated value format.
Refer to the Java ECommerce License Key Generation API Reference for specific information on the EasyLicenser API’s that you will use while writing the license key generation code for your web site.