*

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 (Professional Edition Only)

Example Of License Key Generation With OEM Key Customization (Professional Edition Only)

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.

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.      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.

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.

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.

}

Example Of Server License Key Generation (Professional Edition Only)

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)

:

Example Of License Key Generation With OEM Key Customization (Professional Edition Only)

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)

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.

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.