Contents Overview

Preface

Dedications
Acknowledgements
Purpose and Audience
Using this Documentation
Installation
Reading the Online Documentation
Package Layout
Compiling the Library
Running Examples
Submitting Bugs
Getting Updates

Dedications

To my family: Diane, Emily, and Laura.
  - Paul Jenkins

To Pooh Bear and Michael Ryan
  - David Whitmore

To Lotus Engineering, whose cars are almost as fast as our software.
  - Graham Glass

Acknowledgements

We proudly acknowledge the following people who contributed to JGL 1.1: Mike Colon, Rob Davis, David, Bill Joy, Carlo Prelz, Rene Schmit, Guy Steele, Lewis Stiller, and Walter Szewelanczyk.

Purpose and Audience

The Java Generic Library (JGL) is a comprehensive set of reusable data structures and algorithms. It embraces and extends the library that comes with every Java Development Kit (JDK). This users guide describes the JGL facilities in detail using a mix of text, diagrams, and sample code. Any programmer who wishes to use JGL will benefit from first reading this guide.

If you wish to see the interface to a particular JGL class, consult the API Guide.

How To Use This Document

First, read the rest of this preface, which contains information about how to install JGL, access the online HTML documentation, run the example code, and get additional information about JGL.

Then, read the first chapter Overview which contains an overview of JGL and its main facilities.

Next, read the Containers chapter which describes the common characteristics of all the JGL containers. The 5 chapters that follow it: Sequences, Maps, Sets, Queues and Stacks, and Array Adapters, describe each different kind of container in detail.

The remaining chapters are optional but very useful. For example, to learn about JGL generic algorithms, which allow you to perform sorting, filtering, and other useful operations, read the Algorithms and Function Objects chapters. For information about advanced iterators, which allow you to perform tasks like enumerating a container in a reverse direction or applying an algorithm to a portion of a container, read the Iterators chapter.

For a summary of every JGL class, consult the Class Summary.

The Appendix contains some benchmarks and a comparison of JGL against other data structure libraries.

Installation

Once the JGL files have been installed, you must change/set the CLASSPATH environment variable to include the JGL home directory. Most users have their CLASSPATH set in autoexec.bat. For example, if you installed JGL into the directory C:\jgl_1_1 then you must set your CLASSPATH to include C:\jgl_1_1. The rest of this document assumes that you have obtained a copy of the Java Generic Library, performed the installation process, and installed it into the high level directory \jgl_1_1.

Package Layout and Contents

Here is a map of the JGL directory structure:

\jgl_1_1
  \benchmarks
    *.java      The Java source code for the JGL benchmarks
    *.txt       Files that contains some sample benchmarks
  \doc
    JGL.html    The JGL HTML home page.
    \api
      *.html      HTML API docs and examples.
      \images     .gif files that are referenced by the HTML documentation.
    \user
      *.html      HTML user guide.
      \images     .gif files that are referenced by the HTML documentation.
  \examples
    *.java      The Java source code for all JGL example code.
  \jgl
    *.class     The JGL object files.
  \src
    *.java      The Java source code for JGL.

Reading the Online Documentation

JGL comes complete with full online HTML documentation. The entry point into this documentation is \jgl_1_1\doc\JGL.html, from which you can jump to the user guide, the API guide, and frequently asked questions (FAQs). To view this from the Internet Explorer, use the "File>Open" menu option. To view this file from the Netscape Navigator, use the "File>Open File in Browser" menu option.

To view a particular class, select the class from the tree structure in the API guide. Most classes have a hot link to some examples from the "See Also" section.

Compiling The Library

The JGL installation process automatically installs the JGL object files, so you do not need to compile the library in order to use it. However, if you ever wish to recompile the library, change to the \jgl_1_1\src directory and then enter: 

  jvc -O *.java -d \jgl_1_1

This command recompiles JGL as optimized code and places the resulting object files into a directory called jgl in the \jgl_1_1 directory. Note that due to circularities in class imports, many Java environments will not allow you to recompile JGL on a file-by-file basis. This is a weakness with the environment, not with the design or implementation of JGL.

Running Examples

To compile the example called xxx.java, change into the \jgl_1_1\examples directory and enter: 

  jvc xxx.java

Once the example has compiled, you may run it by entering: 

  jview xxx

All of the examples in this user guide are located in the \jgl_1_1\examples directory.

Submitting Bug Reports and New Containers/Algorithms

We welcome bug reports, suggestions for improvement, and new containers/algorithms. All significant contributions to JGL will be acknowledged in future releases. Please send your valuable feedback to jgl@objectspace.com.

Getting Updates

If you chose to receive automatic email notification when you downloaded JGL, you will automatically be notified of new JGL releases and other JGL-related news items. If you didn't choose to receive email notification but wish you had, send email to jgl@objectspace.com and request future notification.

Contents Overview