edu.stanford.nlp.util
Class HashIndex<E>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by edu.stanford.nlp.util.HashIndex<E>
All Implemented Interfaces:
Index<E>, java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.RandomAccess

public class HashIndex<E>
extends java.util.AbstractCollection<E>
implements Index<E>, java.util.RandomAccess

An Index is a collection that maps between an Object vocabulary and a contiguous non-negative integer index series beginning (inclusively) at 0. It supports constant-time lookup in both directions (via get(int) and indexOf(E). The indexOf(E) method compares objects by equals, as other Collections.

The typical usage would be:

Index index = new Index(collection);

followed by

int i = index.indexOf(object);

or

Object o = index.get(i);

The source contains a concrete example of use as the main method.

An Index can be locked or unlocked: a locked index cannot have new items added to it.

Since:
1.0
Author:
Dan Klein, Eric Yeh (added write to/load from buffer)
See Also:
AbstractCollection, Serialized Form

Constructor Summary
HashIndex()
          Creates a new Index.
HashIndex(java.util.Collection<? extends E> c)
          Creates a new Index and adds every member of c to it.
HashIndex(int capacity)
          Creates a new Index.
 
Method Summary
 boolean add(E o)
          Adds an object to the Index.
 boolean addAll(java.util.Collection<? extends E> c)
          Adds every member of Collection to the Index.
 void clear()
          Clears this Index.
 boolean contains(java.lang.Object o)
          Checks whether an Object already has an index in the Index
 E get(int i)
          Gets the object whose index is the integer argument.
 int indexOf(E o)
          Returns the integer index of the Object in the Index or -1 if the Object is not already in the Index.
 int indexOf(E o, boolean add)
          Takes an Object and returns the integer index of the Object, perhaps adding it to the index first.
 int[] indices(java.util.Collection<E> elems)
          Returns the index of each elem in a List.
 boolean isLocked()
          Queries the Index for whether it's locked or not.
 java.util.Iterator<E> iterator()
          Returns an iterator over the elements of the collection.
static Index<java.lang.String> loadFromFilename(java.lang.String file)
           
static Index<java.lang.String> loadFromReader(java.io.BufferedReader br)
          This is the analogue of loadFromFilename, and is intended to be included in a routine that unpacks a text-serialized form of an object that incorporates an Index.
 void lock()
          Locks the Index.
static void main(java.lang.String[] args)
           
 java.util.Collection<E> objects(int[] indices)
          Looks up the objects corresponding to an array of indices, and returns them in a Collection.
 java.util.List<E> objectsList()
          Returns a complete List of indexed objects, in the order of their indices.
 boolean remove(java.lang.Object o)
          Removes an object from the index, if it exists (otherwise nothing happens).
 void saveToFilename(java.lang.String file)
          Save the contents of this index into a file.
 void saveToWriter(java.io.Writer bw)
          This saves the contents of this index into string form, as part of a larger text-serialization.
 int size()
          Returns the number of indexed objects.
 java.lang.String toString()
          Returns a readable version of the Index contents
 java.lang.String toString(int n)
          Returns a readable version of at least part of the Index contents.
 java.lang.String toStringOneEntryPerLine()
           
 java.lang.String toStringOneEntryPerLine(int n)
           
 void unlock()
          Unlocks the Index.
 HashIndex<E> unmodifiableView()
          Returns an unmodifiable view of the Index.
 
Methods inherited from class java.util.AbstractCollection
containsAll, isEmpty, removeAll, retainAll, toArray, toArray
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface edu.stanford.nlp.util.Index
toArray
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Constructor Detail

HashIndex

public HashIndex()
Creates a new Index.


HashIndex

public HashIndex(int capacity)
Creates a new Index.

Parameters:
capacity - Initial capacity of Index.

HashIndex

public HashIndex(java.util.Collection<? extends E> c)
Creates a new Index and adds every member of c to it.

Parameters:
c - A collection of objects
Method Detail

clear

public void clear()
Clears this Index.

Specified by:
clear in interface Index<E>
Specified by:
clear in interface java.util.Collection<E>
Overrides:
clear in class java.util.AbstractCollection<E>

indices

public int[] indices(java.util.Collection<E> elems)
Returns the index of each elem in a List.

Parameters:
elems - The list of items
Returns:
An array of indices

objects

public java.util.Collection<E> objects(int[] indices)
Looks up the objects corresponding to an array of indices, and returns them in a Collection. This collection is not a copy, but accesses the data structures of the Index.

Specified by:
objects in interface Index<E>
Parameters:
indices - An array of indices
Returns:
a Collection of the objects corresponding to the indices argument.

size

public int size()
Returns the number of indexed objects.

Specified by:
size in interface Index<E>
Specified by:
size in interface java.util.Collection<E>
Specified by:
size in class java.util.AbstractCollection<E>
Returns:
the number of indexed objects.

get

public E get(int i)
Gets the object whose index is the integer argument.

Specified by:
get in interface Index<E>
Parameters:
i - the integer index to be queried for the corresponding argument
Returns:
the object whose index is the integer argument.

objectsList

public java.util.List<E> objectsList()
Returns a complete List of indexed objects, in the order of their indices. DANGER! The current implementation returns the actual index list, not a defensive copy. Messing with this List can seriously screw up the state of the Index. (perhaps this method needs to be eliminated? I don't think it's ever used in ways that we couldn't use the Index itself for directly. --Roger, 12/29/04)

Specified by:
objectsList in interface Index<E>
Returns:
a complete List of indexed objects

isLocked

public boolean isLocked()
Queries the Index for whether it's locked or not.

Specified by:
isLocked in interface Index<E>
Returns:
whether or not the Index is locked

lock

public void lock()
Locks the Index. A locked index cannot have new elements added to it (calls to add(E) will leave the Index unchanged and return false).

Specified by:
lock in interface Index<E>

unlock

public void unlock()
Unlocks the Index. A locked index cannot have new elements added to it (calls to add(E) will leave the Index unchanged and return false).

Specified by:
unlock in interface Index<E>

indexOf

public int indexOf(E o)
Returns the integer index of the Object in the Index or -1 if the Object is not already in the Index.

Specified by:
indexOf in interface Index<E>
Parameters:
o - the Object whose index is desired.
Returns:
the index of the Object argument. Returns -1 if the object is not in the index.

indexOf

public int indexOf(E o,
                   boolean add)
Takes an Object and returns the integer index of the Object, perhaps adding it to the index first. Returns -1 if the Object is not in the Index.

Notes: The method indexOf(x, true) is the direct replacement for the number(x) method in the old Numberer class. This method now uses a Semaphore object to make the index safe for concurrent multithreaded usage. (CDM: Is this better than using a syncronized block?)

Specified by:
indexOf in interface Index<E>
Parameters:
o - the Object whose index is desired.
add - Whether it is okay to add new items to the index
Returns:
The index of the Object argument. Returns -1 if the object is not in the index.

addAll

public boolean addAll(java.util.Collection<? extends E> c)
Adds every member of Collection to the Index. Does nothing for members already in the Index.

Specified by:
addAll in interface Index<E>
Specified by:
addAll in interface java.util.Collection<E>
Overrides:
addAll in class java.util.AbstractCollection<E>
Returns:
true if some item was added to the index and false if no item was already in the index or if the index is locked

add

public boolean add(E o)
Adds an object to the Index. If it was already in the Index, then nothing is done. If it is not in the Index, then it is added iff the Index hasn't been locked.

Specified by:
add in interface Index<E>
Specified by:
add in interface java.util.Collection<E>
Overrides:
add in class java.util.AbstractCollection<E>
Returns:
true if the item was added to the index and false if the item was already in the index or if the index is locked

contains

public boolean contains(java.lang.Object o)
Checks whether an Object already has an index in the Index

Specified by:
contains in interface Index<E>
Specified by:
contains in interface java.util.Collection<E>
Overrides:
contains in class java.util.AbstractCollection<E>
Parameters:
o - the object to be queried.
Returns:
true iff there is an index for the queried object.

saveToFilename

public void saveToFilename(java.lang.String file)
Description copied from interface: Index
Save the contents of this index into a file.

Specified by:
saveToFilename in interface Index<E>
Parameters:
file - File name.

loadFromFilename

public static Index<java.lang.String> loadFromFilename(java.lang.String file)

saveToWriter

public void saveToWriter(java.io.Writer bw)
                  throws java.io.IOException
This saves the contents of this index into string form, as part of a larger text-serialization. This is not intended to act as a standalone routine, instead being called from the text-serialization routine for a component that makes use of an Index, so everything can be stored in one file. This is similar to saveToFileName. NOTE: adds an extra newline at the end of the sequence.

Specified by:
saveToWriter in interface Index<E>
Parameters:
bw - Writer to save to.
Throws:
java.io.IOException - Exception thrown if cannot save.

loadFromReader

public static Index<java.lang.String> loadFromReader(java.io.BufferedReader br)
                                              throws java.lang.Exception
This is the analogue of loadFromFilename, and is intended to be included in a routine that unpacks a text-serialized form of an object that incorporates an Index. NOTE: presumes that the next readLine() will read in the first line of the portion of the text file representing the saved Index. Currently reads until it encounters a blank line, consuming that line and returning the Index. TODO: figure out how best to terminate: currently a blank line is considered to be a terminator.

Parameters:
br - The Reader to read the index from
Returns:
An Index read from a file
Throws:
java.lang.Exception

toString

public java.lang.String toString()
Returns a readable version of the Index contents

Overrides:
toString in class java.util.AbstractCollection<E>
Returns:
A String showing the full index contents

toStringOneEntryPerLine

public java.lang.String toStringOneEntryPerLine()

toString

public java.lang.String toString(int n)
Returns a readable version of at least part of the Index contents.

Parameters:
n - Show the first n items in the Index
Returns:
A String rshowing some of the index contents

toStringOneEntryPerLine

public java.lang.String toStringOneEntryPerLine(int n)

main

public static void main(java.lang.String[] args)

iterator

public java.util.Iterator<E> iterator()
Returns an iterator over the elements of the collection.

Specified by:
iterator in interface java.lang.Iterable<E>
Specified by:
iterator in interface java.util.Collection<E>
Specified by:
iterator in class java.util.AbstractCollection<E>
Returns:
An iterator over the objects indexed

remove

public boolean remove(java.lang.Object o)
Removes an object from the index, if it exists (otherwise nothing happens). Note, the indices of other elements will not be changed, so indices will no longer necessarily be contiguous

Specified by:
remove in interface Index<E>
Specified by:
remove in interface java.util.Collection<E>
Overrides:
remove in class java.util.AbstractCollection<E>
Parameters:
o - the object to remove
Returns:
whether anything was removed

unmodifiableView

public HashIndex<E> unmodifiableView()
Returns an unmodifiable view of the Index. It is just a locked index that cannot be unlocked, so if you try to add something, nothing will happen (it won't throw an exception). Trying to unlock it will throw an UnsupportedOperationException. If the underlying Index is modified, the change will "write-through" to the view.

Returns:
An unmodifiable view of the Index


Stanford NLP Group