LED Sign Installation instructions

Since you are reading this document, you have completed the first step,
unarchiving the distribution file. 

PLEASE... read this document through. The time you devote will be more
than rewarded in avoiding problems later. THIS PACKAGE WILL RUN ON YOUR
COMPUTER AND WEB SERVER. If you have problems, don't look elsewhere for
solutions, look right on your own system, and at yourself. Try to
discover the mistake you made. Don't bother sending me email telling me
that the applet is totally broken or mangled, I'll just laugh. I know
this seems harsh, but the number of lame people I have dealt with in the
past is amazing.

PLEASE NOTE!
===========

If you used a program that destroys the case of file names or mangles
them into old DOS 8.3 names, STOP NOW. Get a proper dearchiver, delete
everything and do it again. On Windows NT and Windows 95, you can use
the WinZip 6.0 (or later) program to dearchive this kit successfully.
You can get this program from most download sites, or at 
http://www.winzip.com/.

If you did not preserve directories when dearchiving, STOP NOW. Delete
everything and do it again, this time preserving directories.

THIS IS A PACKAGED APPLET
=========================

If you have successfully dearchived the kit, and the file names and
directory paths are preserved, you will notice that the applet files are
deep within a directory hierarchy starding with a directory named "com".
This is intentional. Sun has recommended that all Java classes be
"packaged" to avoid name conflicts. For more information on class naming
see the Java site at http://java.sun.com/. 

If you are new to the global class name hierarchy, you need to make a
decision now: Where are you going to store your web-visible Java
classes? Pick a WEB-VISIBLE directory for your Java class root. Add that
directory to your CLASSPATH. Use the equivalent URL path for that
directory in your CODEBASE parameter. 

Now move the "com" directory tree into your chosen root.

Congratulations! You read at least _this_ far... Open open the LED Sign
home page with a URL like:

  http://my.sys.tem/java/com/dc3/applet/LEDSign/doc/LED.html
                   ^^^^^^
  URL to your root---||

There is a sample sign and script that should run when you open the
document. If not, check the Java console of the browser and see what
happened. Some newer browsers will let you run the applet (as coded in
the doc home page) if LED.html is opened as a file also. If it doesn't
work, open it via your web server URL.

If things go smoothly, you should run the regression test suite. Use the
test.html document.


PACKAGE BACKGROUND INFORMATION
==============================

All classes will have a globally unique "fully qualified" dotted name.
The convention is to use your domain's DNS name in reverse. For example,
my machines are in the "dc3.com" domain, so I use "com.dc3" as the
beginning of the fully-qualified name for my classes. No one else's
class names will clash with mine. Beyond this, I choose to classify my
classes into usage groups, for example, "applet", "utility", etc.

The package name for the LED Sign applet is:

  com.dc3.applet.LEDSign

Each individual class used by the applet then has a name like

  com.dc3.applet.LEDSign.Script.class

The Java remote class loader uses the following algorithm to locate
classes:

(1) Take note of three things:

    (a) The CODEBASE URL path, if any
    (b) The applet container's URL path
    (3) The fully-qualified class name

(2) Determine the class root URL path. Use CODEBASE if present, else 
strip the document name off of the applet container's URL and use this
in place of CODEBASE as the root URL. For example, if the current
document has a URL of /java/docs/stuff.html and there was no CODEBASE 
present, then the class root is /java/docs.

(3) Convert the fully qualified class name into a URL path by
replacing all dots except the one preceding "class" into URL path
separator characters (/). For example:

    com.dc3.applet.LEDSign.Script.class

becomes

    com/dc3/applet/LEDSign/Script.class

(4) Splice the path from (3) on to the root path from (2) and use this
complete URL to fetch the class file from the web server. Using the
above, the full URL would be

    /java/docs/com/dc3/applet/LEDSign/Script.class

The above example used the document's URL path as the class base. THIS
WILL ALMOST CERTAINLY BE WRONG. Moral of the story: ALWAYS USE CODEBASE
TO SPECIFY YOUR CLASS ROOT. Suppose you created a directory to hold your
classes, say /usr/local/classes, and mapped it to the URL /jcls/.
When you write your APPLET tag parameters, use 

   CODEBASE=/jcls/
   CODE=com.dc3.applet.LEDSign.Script.class

POP QUIZ
========

OK, ready? Given the above example (the one with CODEBASE):

  (1) In what physical disk directory would you expect to find 
      Script.class?

  (2) What URL path would the class loader use to get Script.class?

=================  NO PEEKING =================





















Answers:

  (1) /usr/local/classes/com/dc3/applet/LEDSign/

  (2) /jcls/com/dc3/applet/LEDSign/Script.class