Contents

Overview

Sequences

Containers

Container Interfaces

Storing Objects and Primitives

Adding, Printing, Clearing, and Sizing

Enumerating

Copying, Comparing, Assigning, and Cloning

Swapping

Storing Primitives

Storing User-Defined Objects

Error Handling

Adapters

JGL includes eleven highly optimized data structures for general purpose programming. It also includes several array adapters that allow you to apply JGL algorithms to native arrays and JDK Vectors. The following diagram shows all of the container classes in JGL and how they relate to the container classes that are already part of the JDK. Interfaces are indicated using italics and classes are indicated with a courier font. Classes that are already part of JDK are indicated by (JDK).

    ^1. There are ten array adapters, one for each primitive data type, one for an array of Objects, and one for a JDK Vector. There are also resizeable adapters for the primitive data types, allowing users to treat a primitive array as a traditional vector. All eighteen of these containers are in the com.objectspace.jgl.adapters package.

Note how tightly JDK integration has been achieved. For example, the JGL HashMap and OrderedMap extend the existing JDK Dictionary class. The only time there is overlap between JGL and JDK is when the JGL container has significantly more functionality or higher performance than its JDK equivalent.

The rest of this chapter contains information pertinent to every JGL container. The Sequences, Maps, Sets, Queues and Stacks, and Array Adapters chapters describe the methods and interfaces specific to each category of container.

Container Interfaces

Every JGL container implements the Container interface, which defines the methods that are common to all JGL containers. In addition, most JGL containers implement a more specialized interface related to their category. For example, Array, Deque, DList, and SList all implement the Sequence interface.
As of the 2.0 release of JGL, containers also implement the Serializable interface which was added to the Java language with the JDK 1.1 release. Serialization can be used for lightweight persistence, Remote Method Invocation (RMI), or communication via sockets.

The Container interface defines the following methods:

• add - adds an element to the container
• clear - removes every element from the container
• clone - returns a shallow copy of the container
• elements - returns an Enumeration positioned at the start of the container
• isEmpty - returns true if the container contains no elements
• equals - returns true if the contents match those of another container of the same type
• remove - removes element(s) represented by Enumerations
• size/maxSize - returns the current/maximum number of elements in the container
• start/finish - returns an iterator positioned at the start/finish of the container
• toString - returns a string that describes the container

The rest of this chapter describes common uses of these containers. For detailed information on the start() and finish() methods, refer to the Iterators chapter.

Storing Objects and Primitives

JGL follows the same philosophy as the JDK when it comes to the way that objects and primitives are stored:

• A container can store instances of any Java class.
  For example, you can store a String, a Date, and an Integer in the same container. When you retrieve an object, you must cast the object back to the required type before applying a type-specific method. Java's dynamic cast-checking mechanism ensures that any attempt to cast an object to the wrong type causes a runtime exception.

• A container cannot directly store a primitive.
  Primitives can only be stored in containers using a special technique described in the Storing Primitives section of this chapter.

Note that unlike C++ template containers, you cannot create a JDK or JGL container that can only hold instances of a specific class of object.

Adding, Printing, Clearing, and Sizing

Every JGL container allows you to add an object, print the container, clear the container, and size the container. These behaviors are illustrated by the following example.

Output
array = Array( triangle, square, pentagon, hexagon )
array.size() = 4
array.empty() = false
after array is cleared...
array.size() = 0
array.empty() = true


Enumerating

Every JDK container defines a method called elements() that returns a JDK Enumeration object positioned at its first element. Once this object is obtained, you may enumerate every element of the container by using the hasMoreElements() and nextElement() methods. For ease of use and backwards compatibility, every JGL container also defines an elements() method that returns an Enumeration. The following example uses an Enumeration object to enumerate every object in an Array.

Output
triangle
square
pentagon
hexagon


Copying, Comparing, Assignment, and Cloning

There are two well-known ways to copy a container:

• A shallow copy means that the original container and the copy share references to the same objects. This is the fastest kind of copy and is sufficient for most programming purposes.

• A deep copy means that the original container and the copy do not share references to the same objects. Instead, every element of the original container is copied as it is added to the new container.

The JGL copy constructors always perform a shallow copy. In addition, you may replace the contents of a container with a shallow copy of another container by using the copy() method, or obtain a shallow clone of a container using the standard clone() method.

To compare two containers of the same type for equality, use the standard equals() method. JGL follows the standard Java convention and extends Container from Cloneable. The following example illustrates all of these methods.

Output
array1 = Array( triangle, square, pentagon )
array2 = Array( triangle, square, pentagon )
array1.equals( array2 ) = true
before copy, array3 = Array( heptagon, octagon )
after copy, array3 = Array( triangle, square, pentagon )
array4 = Array( triangle, square, pentagon )


Swapping

Every JGL container allows you to efficiently exchange its contents with those of another container of the same type by using the swap() method. This is illustrated by the following example.

Output
array1 = Array( ape, bat, cat ), array2 = Array( red, blue )
array1 = Array( red, blue ), array2 = Array( ape, bat, cat )


Storing Primitives

The JGL containers can only contain objects. To store primitives, "wrap" them in their object equivalents defined in java.lang. Here is a table of primitives and their object equivalents:

The following example shows how an Array can be used to store a variety of primitives.

Output
Array = Array( 2, false, x, 3.14 )


Note that the JGL algorithms are smart enough to convert these "wrapper" objects to and from their primitive equivalents when necessary. See the "Algorithms" and "Iterators" chapters for examples.

Storing User-Defined Objects

There are three special methods that are invoked by JGL containers on the objects they contain:

• boolean equals( Object object ) - return true if I am equal to the specified object. By default, JGL algorithms and containers use this function when comparing elements.

• int hashCode() - return my hash code. HashMap and HashSet use this value to store and locate objects. In addition, OrderedMap and OrderedSet use this value by default to order their elements. Note that if two objects match using equals(), their hash codes must be identical.

• String toString() - return a string that describes me. JGL uses this function when printing containers.

For example, here is a Company class that overrides each of these methods appropriately. Note that two companies are considered to match when their names are the same.

Company.java
// Copyright(c) 1996,1997 ObjectSpace, Inc.

public class Company
  {
  String myName;

  public Company( String name )
    {
    myName = name;
    }

  public String toString()
    {
    return "Company( " + myName + " )";
    }

  public int hashCode()
    {
    return myName.hashCode();
    }

  public boolean equals( Object object )
    {
    return
      object instanceof Company
      && myName.equals( ( (Company)object ).myName );
    }
  }


Output
The headquarters of Company( ObjectSpace ) are in Texas


Error Handling

A JGL error causes a Java exception to be thrown. Methods that can cause an exception are commented in the source code using the @exception tag and are documented in the online help. Whenever possible, JGL throws the standard JDK exceptions that are defined in java.lang. The only exception unique to JGL is InvalidOperationException.

Here is a hierarchy of the exceptions that JGL can throw, together with a brief description of when the exception is thrown. All of these exception classes are part of the JDK except for the bolded class.

Because all JGL exceptions inherit from RuntimeException, methods that can generate them do not have to explicitly declare them using throws.

The following example catches an IndexOutOfBoundsException.

Output
Caught java.lang.IndexOutOfBoundsException: Attempt to access index 5; valid range is 0..1


The next example catches an InvalidOperationException.

Output
Caught com.objectspace.jgl.InvalidOperationException: Array is empty


The last example in this series catches an IllegalArgumentException.

Output
Caught java.lang.IllegalArgumentException: Attempt to create an Array with a negative size


Array Adapters

Most of the JGL algorithms such as sort() and countIf() can operate directly on a JGL container. In order for the algorithms to also work with JDK Vectors and native Java arrays, JGL includes special array adapter classes that wrap them in a Container-compliant interface. The following example uses an IntArray adapter to allow sort() to operate on a native array of ints.

Output
unsorted native int array = int[]( 3, -1, 2, 0, -6 )
sorted = -6 -1 0 2 3


For more information about array adapters, read the chapter called Array Adapters.

Contents Overview Sequences