Click to go to home page

Java eCommerce Application Development Guide


Preface

Overview Of eCommerce Enabling Activities

Defining Your Dynamic Web Content Processing

Coding Against The API

Example Of Single-User License Key Generation

Example Of Server License Key Generation

Example Of Orion Server License Key Generation (Orion-enabled Edition Only)

Example Of License Key Generation With OEM Key Customization

Programmatically Recharging Your EasyLicenser Installation

Communicating Keys To Your Customer

Next Steps


Preface

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. If your installation uses version 2.5 license keys, you are automatically enabled for this option.

Note that the Java key generation API is not the only mechanism available for automatic key generation. You can instead utilize the ezlmgenkey command line tool from a shell or CGI script. In addition, Agilis separately provides an http server for remote programmatic key generation from any programming language capable of issuing http post requests.

Overview Of eCommerce Enabling Activities

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.      Programmatically recharging your EasyLicenser installation.

4.      Defining a system for communicating the license key(s) to the paying customer.

Defining Your Dynamic Web Content Processing

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.

If your process involves obtaining node locking information from your end customer, and if your node locking policy is based on the built-in operating system level node locking mechanisms, you can distribute the ezlmgetmcinfo command line tool to your end customers and / or incorporate its source code into an applet on your web site so your end customers can accurately and conveniently report their node locking information.

Coding Against The API

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.

Example Of Single-User License Key Generation

Suppose you have a desktop application such as a file management utility program that you sell to end consumers. In your product definition, you specify that the application password for the key is "mysecret", because you want to generate access controlled keys in order to take advantage of the built-in security mechanisms.

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[] optionsVector = new String[2];

optionsVector[0] = "eval=" + request.getParameter("eval");

optionsVector[1] = "edition=" + request.getParameter("edition");

// Set your product name.  If your web site is a

// one-product site, hard-code it.

String product = "MyUtilProduct";

// Get your end customer’s company name, for example

// from sevlet request object

String endCustomerCompany=request.getParameter("company");

// Generate the license

EzLicenseFullInfo licInfo = null;

try {

licInfo = EzLicenseFullInfo.generateSingleUserKey(

null, // use current date/time as creation date/time

EzLicenseConfig.loadConfig().

getUserName(), // ISV username authorization

endCustomerCompany, // end-customer company name

productName, // protected product name

"mysecret", // protected product application password

userName, // licensed user/host name

false, // not a hostname-only specification ie. named-user

null, // no license expiration date

-1, // no quota limit

null, // no custom key

null, // no custom cookie

optionsVector, // licensed options

false); // no operating system level enforcement

} catch (EzLicExceptionBase eek) {

errMsg = eek.getMessage();

if (eek instanceof EzLicExceptionExpired)

expired = true;

// your EasyLicenser license has expired

else if (eek instanceof EzLicExceptionExceededLimits)

quota = true; // out of EasyLicenser quota

}

:

if (licInfo == null) {

// Do appropriate error response -

// the problem is most likely yours, not your customer’s

} else {

String generatedKey = licInfo.getLicenseKey(); // extract generated key

// send the key to the customer, perhaps

// also display it on customer’s screen etc.

}

Example Of Server License Key Generation

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 (for Unix / Linux) "uname -a", or the output obtained by running the ezlmgetmcinfo utility with the appropriate parameters.

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 using generateSingleUserKey, use the generateServerKey API call. Specify the license type parameter to this API call to be EzLicenseInfo.EZLIC_TYPE_SVR_CONC for concurrent-user licensing. 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.

:

// Now generate the key

:

EzLicenseFullInfo licInfo = null;

try {

licInfo = EzLicenseFullInfo.generateServerKey(

null, // use current date/time as creation date/time

EzLicenseConfig.loadConfig().

getUserName(), // ISV username authorization

endCustomerCompany, // end-customer company name

productName, // protected product name

"mysecret", // protected product application password

hostName, // licensed OS host name

usageValue, // concurrent-user limit

EzLicenseInfo.EZLIC_TYPE_SVR_CONC, // concurrent-user server license type

null, // no license expiration date

-1, // no quota limit

null, // no custom key

null, // no custom cookie

optionsVector, // licensed options

true); // operating system level enforcement

} catch (EzLicExceptionBase eek) {

errMsg = eek.getMessage();

if (eek instanceof EzLicExceptionExpired)

expired = true;

// your EasyLicenser license has expired

else if (eek instanceof EzLicExceptionExceededLimits)

quota = true; // out of EasyLicenser quota

}

:

if (licInfo == null) {

// Do appropriate error response -

// the problem is most likely yours, not your customer’s

} else {

String generatedKey = licInfo.getLicenseKey(); // extract generated key

// send the key to the customer, perhaps

// also display it on customer’s screen etc.

}

Example Of Orion Server License Key Generation (Orion-enabled Edition Only)

Suppose you are licensing a desktop product based on a limit on the number of concurrent users that can be active irrespective of the number and location of desktop application installations. Accordingly, you redistribute the Orion server to your customers, and you integrate your application with the Orion client libraries. As part of order fulfillment, you generate a floating license key for the Orion server itself rather than keys for your application. At the time of generating the key, you specify an upper limit on the number of concurrent floating 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 user/host name is set to the information your customer provides on the intended server machine and the intended operating system account under which the Orion server will be run. The system administrator at the customer site provides this information in advance based on the output obtained by running the ezlmgetmcinfo utility with the appropriate parameters. The information has a syntax username@hostname.

The code is very similar to the server license generation example.  Instead of supplying a user name to the license info, provide a user/host name that you obtain from your customer. Instead of using generateServerKey, use the generateFloatingKey API call. As for the server licensing example, 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. In addition, you may want to specify Orion-specific system options such as ILS:INHIBIT-DB-RESTORE to control the Orion server security at your end customer site (refer to Orion documentation for the complete information on available Orion system options). The license key generation code will look like:

long usageValue = Long.parseLong(

request.getParameter(

"concurrentLimit"));

// Also get user/host name instead of just the user name or hostname

// Get the other attributes such as your customer’s

// company name, etc.

// Assemble option string, for example from

// servlet request object.

String[] optionsVector = new String[3];

optionsVector[0] = "eval=" + request.getParameter("eval");

optionsVector[1] = "edition=" + request.getParameter("edition");

optionsVector[2] = "ILS:INHIBIT-DB-RESTORE=1";

:

// Now generate the key

:

EzLicenseFullInfo licInfo = null;

try {

licInfo = EzLicenseFullInfo.generateFloatingKey(

null, // use current date/time as creation date/time

EzLicenseConfig.loadConfig().

getUserName(), // ISV username authorization

endCustomerCompany, // end-customer company name

"default", // key is for the default Orion service

productName, // protected product name

"mysecret", // protected product application password

userHostName, // licensed username and OS host name

usageValue, // floating concurrent-user limit

null, // no license expiration date

-1, // no quota limit

optionsVector, // licensed options

true); // operating system level enforcement

} catch (EzLicExceptionBase eek) {

errMsg = eek.getMessage();

if (eek instanceof EzLicExceptionExpired)

expired = true;

// your EasyLicenser license has expired

else if (eek instanceof EzLicExceptionExceededLimits)

quota = true; // out of EasyLicenser quota

}

:

if (licInfo == null) {

// Do appropriate error response -

// the problem is most likely yours, not your customer’s

} else {

String generatedKey = licInfo.getLicenseKey(); // extract generated key

// send the key to the customer, perhaps

// also display it on customer’s screen etc.

}

Example Of License Key Generation With OEM Key Customization

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 parameter to generateSingleUserKey. Correspondingly, your application provides a custom key handler to the license checking API call, and the implementation of the custom key handler performs the license check against the OEM key using the appropriate runtime library (which could be EasyLicenser itself, if the OEM key is generated using EasyLicenser).

Programmatically Recharging Your EasyLicenser Installation

Although you can use the License Manager GUI in order to add license units to your eCommerce installation, you may prefer to do so programmatically from your web application. If your web application is hosted remotely, this may be your only option if you cannot run a graphical user interface application on the remote hosted machine.

To recharge your license units programmatically, use the rechargeEzlmKey static method in the EzLicenseFullInfo class and provide an exception handler to catch the EasyLicenser base exception class. When invoked on a new eCommerce installation having no prior EasyLicenser keys, the EasyLicenser configuration is automatically initialized based on the EasyLicenser key provided. Otherwise, it is cross-checked against the new key, and if compatible, the configuration is recharged with the new key to define a new quota.

The code to perform the recharge is illustrated below:

EzLicenseFullInfo.rechargeEzlmKey(

newEzlmKey, // new EasyLicenser key

myUserName); // your EasyLicenser username

Communicating Keys To Your Customer

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.

Another way to automate the management and distribution of keys to your customers is to use a hosted Orion server to store licenses under named users and configure its event alerter to automatically email the generated keys to end users.

Next Steps

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 or back office system.


Copyright © 2002+ Agilis Software LLC, Santa Clara, CA, USA. All rights reserved.