com.vs.ezlicrun
Class EzLicenseExtendedAPI

java.lang.Object
  extended by com.vs.ezlicrun.EzLicenseInfo
      extended by com.vs.ezlicrun.EzLicenseExtendedAPI
All Implemented Interfaces:
java.io.Serializable

public class EzLicenseExtendedAPI
extends EzLicenseInfo

The class provides an extended API that provides higher-level functionality, reducing the level of development effort involved in integrating an application. The extended functionality includes:
1. Optional deferred node locking.
2. Optional deferred time-limited licensing (requires an appropriate time-limited-trial-generator license key from Agilis).
The extended API provides high level mechanisms for:
1. Activation - use during product installation or activation upon first use.
2. Steady state license check - use wherever license checks are to be performed during normal license operations.
3. Deactivation - use during product uninstallation or explicit deactivation.

The API's extends the EzLicenseInfo class. How to use for activation:
Invoke the "activate" static factory method: EzLicenseExtendedAPI api = EzLicenseExtendedAPI.activateLicense(licenseKey, auxKey, flags, etc.);
The returned api class can then be introspected in the same manner as the underlying EzLicenseInfo, as well as to obtain the created key cookie and warning status code.
How to use for checking a license in the steady state:
Invoke the "check" static factory method: EzLicenseExtendedAPI api = EzLicenseExtendedAPI.checkLicense(key-cookie, flags, etc.);
The returned api class can then be introspected in the same manner as the underlying EzLicenseInfo, as well as to obtain the warning status code.

How to use for deactivating a license:
Invoke the "deactivate" static method: int warningBitmap = EzLicenseExtendedAPI.deactivateLicense(key-cookie, flags, etc.);
The returned warning bitmap contains the appropriate EzLicenseInfo warning codes, or 0 if success. How to use for deferred time limited licensing, then later switch to perpetual licensing:
1. Generate a single perpetual key with the EZLM:KEY-EXPIRE-DAYS option described below, set to the desired relative expiration days. The key is not node-locked.
2. Use the above key together with the Agilis-supplied enabling key in the activation API call.
3. When re-activating with a perpetual key:
(a) the perpetual key must not have the above option specified.
(b) invoke the deactivation API call, then invoke the activation API call, this time with the new key. The enabling key need not be specified in this call, and if it is, it is ignored upon detection of the perpetual key.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class com.vs.ezlicrun.EzLicenseInfo
EzLicenseInfo.Hfile, EzLicenseInfo.Util
 
Field Summary
static java.lang.String EZLM_EXPDAYS_OPTION_NAME
           
static java.lang.String EZLM_SHELFLIFE_OPTION_NAME
           
 
Fields inherited from class com.vs.ezlicrun.EzLicenseInfo
EZLIC_DEFAULT_TIME_TOLERANCE_HRS, EZLIC_KEY_VSN, EZLIC_KEY_VSN_CURR, EZLIC_KEY_VSN_CURR_S, EZLIC_KEY_VSN_NEXT, EZLIC_MODE_CUSTOM_COOKIE, EZLIC_MODE_CUSTOM_KEY, EZLIC_MODE_METERED, EZLIC_MODE_OPTIONS, EZLIC_MODE_TIME, EZLIC_MODEL_SERVER, EZLIC_MODEL_USER, EZLIC_TYPE_SVR_CONC, EZLIC_TYPE_SVR_CPU, EZLIC_TYPE_SVR_MHZ, EZLIC_TYPE_SVR_NMU, EZLIC_TYPE_U_FLOAT, EZLIC_TYPE_U_NODE, EZLIC_TYPE_U_USER, EZLM_MAJOR_VERSION_NUMBER, EZLM_MINOR_VERSION_NUMBER
 
Constructor Summary
EzLicenseExtendedAPI()
           
 
Method Summary
static EzLicenseExtendedAPI activateLicense(java.lang.String licenseKey, java.lang.String auxKey, EzLicCustomLicenseInterface customKeyHandler, java.lang.Object customKeyContext, java.lang.String userHostNet, java.lang.String product, java.lang.String appPassword, java.lang.String userAppstate, java.lang.String hfileDirectory, boolean alwaysCheckTimestamp, boolean deferredNodeLock)
          Activate the specified license key in the current machine under the current operating system account.
static EzLicenseExtendedAPI checkLicense(java.lang.String keyCookie, EzLicCustomLicenseInterface customKeyHandler, java.lang.Object customKeyContext, int daysLeftThreshold, long quotaUsageToDate, long quotaThreshold, int daysGracePeriod, long quotaGrace, java.lang.String userHostNet, long currUsageValue, java.lang.String product, java.lang.String appPassword, java.lang.String appState, java.lang.String hfileDirectory, boolean alwaysCheckTimestamp)
          Check the specified license key cookie against the provided info for key violations, and set the class context based on the key.
static int deactivateLicense(java.lang.String keyCookie, java.lang.String productName, java.lang.String appPassword, java.lang.String hfileDirectory, boolean check)
          Deactivate license.
 long getActTs()
          getActTs: returns activation timestamp embedded in key cookie state, 0 if not activated.
 long getExpTs()
          getExpTs: returns expiration timestamp embedded in key cookie state, 0 if not relative-time-limited.
 java.lang.String getKeyCookie()
          getKeyCookie: returns key cookie string
 java.lang.String getLicKey()
          getLicKey: returns license key embedded in key cookie state, null if none.
 int getStatusCode()
          getStatusCode: returns status code from last operation.
 java.lang.String getUserAppstate()
          getUserAppstate: returns user-defined application state embedded in key cookie state, null if none.
 java.lang.String getUserhost()
          getUserhost: returns user/host name embedded in key cookie state, null if none.
 
Methods inherited from class com.vs.ezlicrun.EzLicenseInfo
checkLicenseKey, checkLicenseKey, checkLicenseKey, checkLicenseKey, checkLicenseKey, checkLicenseKeySecure, checkLicenseKeySecure, checkLicenseKeySecure, checkLicenseKeySecure, checkLicenseKeySecure, checkMultiUserLicenseKeyBasic, checkMultiUserLicenseKeyBasic, checkMultiUserLicenseKeyBasic, checkSingleUserLicenseKeyBasic, checkSingleUserLicenseKeyBasic, checkSingleUserLicenseKeyBasic, cleanupKeyCookie, cleanupKeyCookie, createKeyCookieSeed, createKeyCookieSeed, createKeyCookieSeed, getAppPwd, getChainedKeyId, getCustomCookie, getCustomKey, getEnforce, getExpirationDate, getExpirationTs, getEzlmVersionInfo, getKeyCookieAppState, getKeyCookieQuotaToDate, getKeyCookieTs, getKeyVersion, getLicenseKey, getLicenseModeBitmap, getLicenseModelCode, getLicenseTypeCode, getOptions, getQuotaValue, getTimeToleranceHrs, getUsageValue, getUserHostNetName, getWarningsBitmap, setCustomCookie, setCustomKey, setEnforce, setExpirationDate, setKeyVersion, setLicenseKey, setLicenseModeBitmap, setLicenseModelCode, setLicenseTypeCode, setOptions, setQuotaValue, setTimeToleranceHrs, setUsageValue, setUserHostNetName, setWarningsBitmap
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EZLM_EXPDAYS_OPTION_NAME

public static final java.lang.String EZLM_EXPDAYS_OPTION_NAME
See Also:
Constant Field Values

EZLM_SHELFLIFE_OPTION_NAME

public static final java.lang.String EZLM_SHELFLIFE_OPTION_NAME
See Also:
Constant Field Values
Constructor Detail

EzLicenseExtendedAPI

public EzLicenseExtendedAPI()
Method Detail

getKeyCookie

public java.lang.String getKeyCookie()
getKeyCookie: returns key cookie string

Returns:
key cookie string

getStatusCode

public int getStatusCode()
getStatusCode: returns status code from last operation.

Returns:
status code, always a success code or warning bitmap.

getLicKey

public java.lang.String getLicKey()
getLicKey: returns license key embedded in key cookie state, null if none.

Returns:
license key string embedded in key cookie state.

getUserAppstate

public java.lang.String getUserAppstate()
getUserAppstate: returns user-defined application state embedded in key cookie state, null if none.

Returns:
user-defined application state string embedded in key cookie state.

getUserhost

public java.lang.String getUserhost()
getUserhost: returns user/host name embedded in key cookie state, null if none.

Returns:
user/host name string embedded in key cookie state.

getActTs

public long getActTs()
getActTs: returns activation timestamp embedded in key cookie state, 0 if not activated.

Returns:
activation timestamp embedded in key cookie state.

getExpTs

public long getExpTs()
getExpTs: returns expiration timestamp embedded in key cookie state, 0 if not relative-time-limited.

Returns:
expiration timestamp embedded in key cookie state.

activateLicense

public static EzLicenseExtendedAPI activateLicense(java.lang.String licenseKey,
                                                   java.lang.String auxKey,
                                                   EzLicCustomLicenseInterface customKeyHandler,
                                                   java.lang.Object customKeyContext,
                                                   java.lang.String userHostNet,
                                                   java.lang.String product,
                                                   java.lang.String appPassword,
                                                   java.lang.String userAppstate,
                                                   java.lang.String hfileDirectory,
                                                   boolean alwaysCheckTimestamp,
                                                   boolean deferredNodeLock)
                                            throws EzLicExceptionBase
Activate the specified license key in the current machine under the current operating system account. Validate the specified license key, and initialize the activation state according to the input parameters for the purpose of starting the clock ticking if this is a deferred time-limited license (an auxiliary time-limited-license key is specified as an input parameter) and initializing usage counts for metered licensing.

Parameters:
licenseKey - vendor-provided license key.
auxKey - Agilis-provided auxiliary license key needed to enable certain functions such as deferred-time-limited licensing and deferred node locking.
customKeyHandler - optional custom license key handler for processing custom key in an ISV specific manner. Null if not specified.
customKeyContext - optional run time context for custom license key handler above.
userHostNet - user or host or network name, for a user / node locked / floating license. This is required to match what is in the license key. It may be null if the key was generated with "enforce os check" set to true. When using deferred node locking, the supplied key does not have to be node locked, and the userHostNet parameter does not have to match the user/machine on which the application is running.
product - product name. Must match what's in the key if specified. If not specified, app password can't be specified either.
appPassword - application password's public key. One must be supplied if the key contains a password.
userAppstate - stringified generic license related application state to embed in the key cookie for later retrieval. If specified, the only way to later retrieve the state is with this same extended API. That is, the information is inaccessible from the normal key cookie API's that are ordinarily used with the core API's.
hfileDirectory - preferred hidden-file directory. If null, and if hidden-file checking is enabled, the Java "user.home" property is used.
alwaysCheckTimestamp - whether to unconditionally check the hidden file's timestamp against the system clock. If false, the timestamp is checked only for time limited licenses.
deferredNodeLock - whether to perform deferred node locking, so as to prevent the activated key cookie from being transported to multiple machines for multiple concurrent uses. The flag is ignored if an enabling key is not supplied.
Returns:
an instantiated EzLicenseExtendedAPI instance containing the key cookie, warning status code etc, if the license key check is successful.
Throws:
EzLicExceptionBase - in the event of a malformed key or invalid license.
See Also:
EzLicExceptionBase

deactivateLicense

public static int deactivateLicense(java.lang.String keyCookie,
                                    java.lang.String productName,
                                    java.lang.String appPassword,
                                    java.lang.String hfileDirectory,
                                    boolean check)
                             throws EzLicExceptionBase
Deactivate license. Typically invoked at uninstallation time or immediately prior to reactivation.

Parameters:
keyCookie - last-valid key cookie
productName - product name
appPassword - application password, same as that specified to activateLicense() and checkLicense().
hfileDirectory - directory where hidden file is supposed to be
check - whether to do a timestamp check
Returns:
warning code bitmap.
Throws:
EzLicExceptionBase - or a subclass if an error condition is encountered.

checkLicense

public static EzLicenseExtendedAPI checkLicense(java.lang.String keyCookie,
                                                EzLicCustomLicenseInterface customKeyHandler,
                                                java.lang.Object customKeyContext,
                                                int daysLeftThreshold,
                                                long quotaUsageToDate,
                                                long quotaThreshold,
                                                int daysGracePeriod,
                                                long quotaGrace,
                                                java.lang.String userHostNet,
                                                long currUsageValue,
                                                java.lang.String product,
                                                java.lang.String appPassword,
                                                java.lang.String appState,
                                                java.lang.String hfileDirectory,
                                                boolean alwaysCheckTimestamp)
                                         throws EzLicExceptionBase
Check the specified license key cookie against the provided info for key violations, and set the class context based on the key. This version matches product name and application password, and also accepts an application context for embedding into the key cookie. Throw an appropriate exception if the key is invalid or there is a license violation. Returns warning code bitmap to indicate almost-out-of-quota, expiring, etc. conditions that are not yet errors.

Parameters:
keyCookie - the key cookie that was returned from the previous call to this method for this key, or from the activateLicense() method if none.
customKeyHandler - optional custom license key handler for processing custom key in an ISV specific manner. Null if not specified.
customKeyContext - optional run time context for custom license key handler above.
daysLeftThreshold - threshold for # of days remaining in a time-limited license in order to trigger an "about-to-expire" warning.
quotaUsageToDate - amount of consumed quota, if this is expected to be a metered license and the value is positive. If the value is negative, it represents the incremental quota consumption by which to reduce the available balance that is stored in the key cookie.
quotaThreshold - threshold for # of license units remaining in a metered license in order to trigger an "about-to-expire" warning.
daysGracePeriod - grace period for time limited license - if today is past expiration date by less than this many days, set a warning instead of throwing an exception.
quotaGrace - grace quota - if quota is exceeded by less than this amount, set a warning instead of throwing an exception.
userHostNet - user or host or network name, for a user / node locked / floating license.
currUsageValue - current usage value for floating / concurrent-user / cpu / mhz usage models.
product - product name. Must match what's in the key if specified. If not specified, app password can't be specified either.
appPassword - application password's public key. One must be supplied if the key contains a password.
appState - stringified generic license related application state to embed in the key cookie for later retrieval.
hfileDirectory - preferred hidden-file directory. If null, and if hidden-file checking is enabled, the Java "user.home" property is used.
alwaysCheckTimestamp - whether to unconditionally check the hidden file's timestamp against the system clock.
Returns:
an instantiated EzLicenseExtendedAPI instance containing a new key cookie value, warning status code etc, if the license key check is successful.
Throws:
EzLicExceptionBase - in the event of a malformed key or invalid license
See Also:
EzLicExceptionBase