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 To my parents, without whom I wouldn't have been possible. - Michael Klobe
For JGL 2.0, the list grows: Sanjiv Bhatia, Doug Bateman, Dan Brown, Oliver Burn, Steve Burns, Martin Fong, Robert Girin-Lajoie, Michael Greenspon, Robert Jochemsen, Nathan Litke, John Miller, Jonathan Moody, Jef Newsom, Sakuro Ozawa, Roly Perera, Clinton Popetz, Mike Radford, Mike Schuster, Nicholas Scott, Geir Ove Skjaervik, D.J. Walker-Morgan, Laurence Vanhelsuwe, John Wilson, and Matt Young.
The Generic Collection Library for Java™ (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.
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.
Once the JGL files have been installed, you must change/set the CLASSPATH
environment variable to include the JGL home directory. Most PC users have
their CLASSPATH
set in autoexec.bat
. For example, if
you installed JGL into the directory C:\jgl_2_0
then you must
set your CLASSPATH
to include C:\jgl_2_0
.
The rest of this document assumes that you have obtained a copy of
the Generic Collection Library, performed the installation process,
and installed it into the high level directory \jgl_2_0
.
Here is a map of the JGL directory structure:
\jgl_2_0
\benchmarks
*.java
The Java source code for the JGL benchmarks.*.txt
Files that contains some sample benchmarks.\COM\objectspace\jgl
*.class
The JGL object files.\doc
JGL.html
The JGL HTML home page.changes.txt
Bug fixes and alterations listing.\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 examples.*.txt
Sample output for all examples.\src\COM\objectspace\jgl
*.java
The Java source code for JGL.
\jgl_2_0\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.
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_2_0\src\COM\objectspace\jgl
directory and then enter:
javac -O -d \jgl_2_0 *.java
This command recompiles JGL as optimized code and
places the resulting object files into a directory called COM\objectspace\jgl
in the \jgl_2_0
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.
To compile the example called xxx.java
,
change into the \jgl_2_0\examples
directory and enter:
javac
xxx.java
Once the example has compiled, you may run it by entering:
java
xxx
All of the examples in this user guide are located
in the \jgl_2_0\examples
directory.
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
.
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