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

java.lang.Object
  java.util.AbstractCollection<E>
      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(Index<? extends E> index)

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) This assumes each line is of the form (number=value) and it adds each value in order of the lines in the file
static Index<java.lang.String>	loadFromFileWithList(java.lang.String file) This assumes each line is one value and creates index by adding values in the order of the lines in the 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.
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)
boolean	removeAll(java.util.Collection<?> e)
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, 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

HashIndex

public HashIndex(Index<? extends E> index)

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 synchronized 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)

This assumes each line is of the form (number=value) and it adds each value in order of the lines in the file

Parameters:

file -

Returns:

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.

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.io.IOException

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.io.IOException

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 showing some of the index contents

toStringOneEntryPerLine

public java.lang.String toStringOneEntryPerLine(int n)

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

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

remove

public boolean remove(java.lang.Object o)

Specified by:

remove in interface java.util.Collection<E>

Overrides:

remove in class java.util.AbstractCollection<E>

removeAll

public boolean removeAll(java.util.Collection<?> e)

Specified by:

removeAll in interface java.util.Collection<E>

Overrides:

removeAll in class java.util.AbstractCollection<E>

loadFromFileWithList

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

This assumes each line is one value and creates index by adding values in the order of the lines in the file

Parameters:

file -

Returns: