JGL - The Generic Collection Library for Java

Overview

Preface

Dedications

Acknowledgements

Purpose and Audience

Using this Documentation

Installation

Reading the Online Documentation

Package Layout

Compiling the Library

Running Examples

Submitting Feedback

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

To my parents, without whom I wouldn't have been possible.
- Michael Klobe

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.

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.

With version 3, still more people contributed: Paul Fisher, Brian R. Gilstrap, Sean Kelly, Suresh P., Nicky Sandhu, Sander Tichelaar, Sven Van Den Berghe, John Wilson, Dave Yost. The 3.1 update adds to this page the names of Ajit Bhagvat, Brett Crossley, Bob Gleason, Dave Han, Saulo Medeiros de Araujo, Wayne Stidolph, Brian Thorstad, and Derek Young.

Purpose and Audience

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.

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.

There is also a chapter that describes how to use Voyager with JGL. ObjectSpace Voyager is the world's first 100% Java agent-enhanced Object Request Broker (ORB). Voyager allows Java programmers to quickly and easily create sophisticated network applications using both traditional and agent-enhanced distributed programming techniques. For more information visit our website at http://www.objectspace.com/voyager.

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 PC users have their CLASSPATH set in autoexec.bat. For example, if you installed JGL into the directory C:\jgl3.1.0 then you must set your CLASSPATH to include C:\jgl3.1.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 \jgl3.1.0.

Package Layout and Contents

Here is a map of the JGL directory structure:

`\jgl3.1.0`			Root directory.
	`\benchmarks`		Simple JGL comparison programs.
	`\doc`		JGL documentation files.
		`changes.txt`	Bug fixes and alterations listing.
		`license3_0.txt`	JGL license agreement.
		`\user`	HTML User Guide files.
		`\api`	HTML API Guide files.
	`\examples`		Source code for example programs.
	`\lib`		Library jar file, which contains all the `.class` files.
	`\src\com\objectspace\jgl\*`		Source code for the library.

Reading the Online Documentation

JGL comes complete with full online HTML documentation. The entry point into this documentation is \jgl3.1.0\doc\index.html, from which you can jump to the user guide, the API guide, and frequently asked questions (FAQs). These file may be viewed with any browser, such as Internet Explorer or Netscape Navigator.

To view a particular class, select the class from the tree structure in the API guide. Several 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 \jgl3.1.0\src\com\objectspace\jgl directory and then enter:

javac -O -d \jgl3.1.0 *.java

This command recompiles JGL as optimized code and places the resulting object files into a directory called com\objectspace\jgl in the \jgl3.1.0 directory. You can then repeat this step for the other directories at this level: adapters, algorithms, etc. Be aware that the classes in the voyager directories won't compile properly without the ObjectSpace Voyager product installed; if you aren't using Voyager, then you need not worry about these classes. 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 an example called xxx.java, change into the \jgl3.1.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 (and more!) are located in the \jgl3.1.0\examples directory.

Submitting Feedback

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.

There is also an email discussion list dedicated to JGL. To join the JGL discussion list, send mail to objectlist@objectspace.com with the following information within the body of the message:

join jgl-interest someone@somewhere.com

where someone@somewhere.com is your actual email address. By joining the JGL discussion list this way, you will receive email whenever someone posts to the discussion group.
To receive the list in a digest format, send mail to objectlist@objectspace.com with the following information within the body of the message:

digest jgl-interest someone@somewhere.com

By "digesting" the JGL discussion list you will receive one email that will be a compilation of all post to the discussion list within the past 24 hours.

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