License Installation

Table Of Contents

License Keys
NFLicense.dat File
License Located Via CODEBASE
License Located Via CLASSPATH
LicenseURL Parameter
LicenseKeys Parameter
Embedded Applet License Keys
Trouble-Shooting Tips

Introduction

All NetCharts applets are licensed to operate off of one or more servers. Once a given server is licensed, any number of clients, using browsers, the Java Development Kit or standalone applications can use any of the NetCharts applets without restriction.

If a valid license cannot be found by the applets, then they operate in "Evaluation Copy" mode. The only difference between an Evaluation copy and a licensed copy is the display of a simple banner, which requires the user to press a button before proceeding. All other features are supported.

License Keys

License keys are generated based on the version of NetCharts being used and the IP address of the server from which they will be used. Generally, the IP address licensed is that of the Web server. License keys are formatted as follows:

NetCharts1.5  XFBP JYDK XFXD FFMD JJBM EPHJ HDHM XCMG  # 123.56.78.98
NetCharts1.5  GNPZ GYKG GACG ACPA NHMG EXGX BFDA XBGC  # 123.87.45.2
NetCharts1.4  AHGZ HDGF EXZN CPND DPZN HCDE AYAZ KNGF  # 123.89.7.134
License keys can be read and written using any common text editor, provided the order of the information on each line is not modified. Anything added after the '#' sign is considered a comment and is ignored.

NFLicense.dat

License keys are generally stored in the NFLicense.dat file, which is generally located in the $NETCHARTS/classes directory, where $NETCHARTS is the base directory of the NetCharts distribution. This is the most convenient way to access and maintain license keys, and has been successfully employed by most NetCharts users.

The NFLicense.dat file can contain any number of license keys, in any order. This allows system administrators to establish one license file that can service any number of servers.

The NFLicense.dat file should have the same file permissions set as the NetCharts class files. For most Web Servers, the files must be readable by the "everyone" to be retrieved using a browser. Write permission is NOT required for anyone except the Web/Java administrator.

Given a valid set of license keys and a properly formatted file, it remains for NetCharts applets to locate the license keys and process them. To that end, the following methods are provided to allow HTML and Java developers, using both applets and applications, to use licensed NetCharts applets.

License File Located Via CODEBASE Attribute

By default, all NetCharts applets attempt to read the NFLicense.dat file from the $NETCHARTS/classes directory located via the CODEBASE attribute.

When any applet is defined within an HTML document, it is defined using the <APPLET> tag, which contains the following important attributes:

The codebase attribute is particularly important, since it specifies the top-level directory containing the Java class files. When using NetCharts applets, the codebase attribute should point to the $NETCHARTS/classes directory, where $NETCHARTS depends on your specific Web server directory structure.

For example, if NetCharts is located at the top of your Web hierarchy, in the /NetCharts directory, the following applet tag would be correct:

	<applet codebase=/NetCharts/classes
	        code=NFPiechartApp.class
                width=400
                height=400>
On the other hand, if NetCharts is located in a directory that is relative to the current document directory, then the following applet tag could be used:
	<applet codebase=../../classes
	        code=NFPiechartApp.class
                width=400
                height=400>
In either case, if the NFLicense.dat file is located in the directory specified by the codebase attribute, then the license validation will succeed.

Most Web browsers are capable of viewing HTML documents in the local file system, by specifying a file path. In such cases, if relative addressing is used for the codebase attribute, then the license file processing will work as before.

However, if absolute addressing is specified in the codebase attribute (ie. the codebase value begins with a protocol or '/'), then the Java classes will not be located properly when the file is viewed directly using the Web browser.

License File Located Via CLASSPATH Environment Variable

In standalone Java applications, NetCharts applets automatically look for a valid NFLicense.dat file located ANYWHERE along the directory path specified in the Java standard $CLASSPATH environment variable. Generally, the $CLASSPATH variable specifies all of the directories on the system where Java class hierarchies are located. NOTE, the $CLASSPATH variable should point to the $NETCHARTS/classes directory in order to properly execute NetCharts applets.

License File Specified Using LicenseURL Parameter

In situations where it is not convenient or possible to place the NFLicense.dat file in the CODEBASE directory, it may be placed anywhere that is accessible via a Web browser, including another Web server if desired. This is accomplished by specifying the "LicenseURL" parameter within the applet tag that defines a NetCharts applet.

For example, the following applet tag defines a simple piechart, that uses a LicenseURL that is different from the codebase path:

<applet codebase=../classes
	code=NFPiechartApp.class
	width=200 height=100>

<param name=NFParamScript value = '

LicenseURL  = "/admin/NFLicense.dat";
Slices      = (12), (34), (56), (78);

'>
</applet>

Note, the LicenseURL uses an absolute address to specify the location of the license file, while the codebase uses a relative address to locate the NetCharts class files.

Any URL can be used, including a CGI command, provided the resulting data stream is a text/plain file containing a valid license key for the IP address of the Web Server. (The data stream can contain any number of license keys, with each one being checked.)

NOTE, the LicenseURL method only works for HTML documents that are viewed from a Web server. Web browsers restrict URL access whenever an HTML document is viewed directly from the file system.

License Keys Specified Using LicenseKeys Parameter

In situations where it is not possible to access a URL automatically from within the applet (usually because of proxy servers or firewalls), one or more license keys can be specified directly in the HTML document using the LicenseKeys parameter. (This method requires the entries to be made in every HTML document using a NetCharts applet, which may not be easily administered, but it may be required because of development or production restrictions.)

The LicenseKeys parameter defines one or more quoted strings, separated by commas, each of which specifies a license entry. For example, the following parameter definition specifies keys for three different servers, thereby enabling this document to run off of those servers:

<applet codebase=../classes
	code=NFPiechartApp.class
	width=200 height=100>

<param name=NFParamScript value = '

LicenseKeys = "NetCharts1.5 XFBP JYDK XFXD FFMD JJBM EPHJ HDHM XCMG",
	      "NetCharts1.5 GNPZ GYKG GACG ACPA NHMG EXGX BFDA XBGC",
	      "NetCharts1.4 AHGZ HDGF EXZN CPND DPZN HCDE AYAZ KNGG";

Slices      = (12), (34), (56), (78);

'>
</applet>

Note, the leading version indicator is optional. If not specified for a given key entry, the current NetCharts version will be assumed.

License Keys Specified In Embedded Applet

When a NetCharts applet is embedded within another applet or in a standalone application, by default it attempts to locate the NFLicense.dat file via the CODEBASE or CLASSPATH as described above. If this mode is desired, no extra coding is necessary, other than that required to embed the applet and specify its normal parameters, using the loadParams() method. (See Embedded Applets for more details.)

Since license validation is performed prior to parameter processing when a NetCharts applet is embedded, it is NOT possible to specify the LicenseURL or LicenseKeys parameters.

If the standard license file processing modes are not desired, one or more license keys can be specified directly using the NFLicense.setKey() method from within the application or applet. This allows Java programmers to "hardcode" the license keys for a given application, even if that application will be used on multiple hosts. (Note, you will still need a unique license key for each host on which the application will run. Contact the NetFactory for a custom license solution, involving a single "master-key" if your application will be deployed to a large number of customers or hosts.)

In the following example, the setKey() method is used to specify a single license key for an embedded applet:

import java.awt.*;
import netcharts.graphics.*;

public class lictest
{
    public static void main (String args[])
    {
        Frame           frame = new Frame("License Test");
        NFPiechartApp   pie = new NFPiechartApp();

        frame.setLayout (new BorderLayout());
        frame.add ("Center", pie);
        frame.resize (200,100);

        NFLicense.setKey ("XFBP JYDK XFXD FFMD JJBM EPHJ HDHM XCMG");

        pie.init();
        pie.loadParams ("Header = ('License Test', black);");
        pie.loadParams ("Update;");
        pie.start();

        frame.show();
    }
}

Note, the setKey() method is called BEFORE the first call to loadParams().

In this example, a vector of license keys (with leading version numbers) is passed to the setKey() method:

import java.util.*;

Vector keys = new Vector();

keys.addElement("NetCharts1.5 XFBP JYDK XFXD FFMD JJBM EPHJ HDHM XCMG");
keys.addElement("NetCharts1.5 GNPZ GYKG GACG ACPA NHMG EXGX BFDA XBGC");
keys.addElement("NetCharts1.4 AHGZ HDGF EXZN CPND DPZN HCDE AYAZ KNGG");

NFLicense.setKey (keys);

In either case, the setKey() method must be called prior to the first loadParams() method being called. Also, since setKey() is a static method, it need only be called once, regardless of the number of applets started within the application. The license keys will be automatically re-used for each new applet.

Trouble-Shooting Tips

The diversity of the Web/Java world is a blessing to developers, but an increasing nightmare for administrators. To help reduce the number of sleepless hours, we offer the following tips for trouble-shooting license problems.

  1. Place the NFLicense.dat file (spelled properly with upper and lower case) in the $NETCHARTS/classes directory. If it's in the same place as NFPiechartApp.class, it's in the right place.

  2. Begin checking the license file configuration by using the example documents in the $NETCHARTS/examples directory. Those documents use relative addressing for the CODEBASE attribute and should work when accessed directly from the file system using a Web browser or via a Web server provided the NFLicense.dat file is in the $NETCHARTS/classes directory.

  3. If the evaluation banner is not displayed, then the applet itself is probably not running. This is usually the result of a Web browser or server misconfiguration. Check the Java Console for any error messages. In the Netscape Navigator, this is done using the Show Java Console option in the Options menu. In the Internet Explorer, you will need to enable Java logging via the View-Options-Advanced menu. Normally, such log information is written to the C:\Windows\Java\javalog.txt file.

    All Web browsers provide some form of file caching to reduce network load. Unfortunately, the browser doesn't always know when to re-load a Java class file that has changed. Therefore, whenever making changes to the $NETCHARTS/classes hierarchy, such as when upgrading to a new release, you should remember to flush your browser cache, exit your browser and restart it. That will assure that the old class files are no longer in the cache and the new ones will be located, along with any new license file.

    Use the following menu in Netscape Navigator to flush the cache:

    • Options
    • Network Preferences
    • Clear Memory Cache Now, Clear Disk Cache Now

    Use the following menu in Microsoft Internet Explorer to flush the cache:

    • View
    • Options
    • Advanced
    • Temporary Internet Files
    • Settings
    • Empty Folder


  4. If the evaluation banner is still displayed, but you believe that you have a valid license file, you can add the following Parameter definition to your NetCharts applet to print out debug information on the Java Console:
    	DebugSet = LICENSE;
    

    For your convenience, the Barchart1.html file in the $NETCHARTS/examples directory defines that parameter and can be used for initial trouble-shooting.

  5. If the debug output shows an IP address that is different than the one that was licensed, you should contact the NetFactory to get a valid license entry for that IP address. In some environments, hosts are assigned multiple IP addresses and you may need to license another one or all of them to work properly.

  6. If the debug output shows that the license file is not being located properly, review the options described above and re-check any CODEBASE or CLASSPATH variables. If the NetCharts applets are located on the CLASSPATH of the browser AND the CODEBASE points to someplace else, then the applets will execute, but the license file will not be found.

    Developers sometimes use the CLASSPATH variable to speed-up access to Java applets, but that practice leads to confusion when Java applets are accessed by normal users via the Web server. Also, security restrictions imposed by most browsers prevent an applet that is loaded from the local file system (via the CLASSPATH) from accessing files via a URL (which is how the license file is usually accessed.) In such situations, an alternative license scheme should be used, such as the LicenseKeys parameter. (Note, the LicenseURL method will NOT work either, because of the same security restriction.)

  7. If you still can't solve the dreaded license problem, feel free to email, fax or call the NetFactory for assistance. (See www.netcharts.com for up-to-date contact information.) For fastest assistance, please be prepared to provide the following information: