edu.mit.jwi.data
Class WordnetFile<T>

java.lang.Object
  edu.mit.jwi.data.WordnetFile<T>

Type Parameters:

T - the type of the objects represented in this file

All Implemented Interfaces:

IClosable, IDataSource<T>, IHasLifecycle, ILoadable, ILoadableDataSource<T>, IHasVersion, java.lang.Iterable<java.lang.String>

Direct Known Subclasses:

BinarySearchWordnetFile, DirectAccessWordnetFile

public abstract class WordnetFile<T>
extends java.lang.Object
implements ILoadableDataSource<T>

Abstract superclass of wordnet data file objects. Provides all the infrastructure required to access the files, except for the construction of iterators and the actual implementation of the IDataSource.getLine(String) method.

While this object is implemented to provider load/unload capabilities (i.e., it allows the whole wordnet file to be loaded into memory, rather than read from disk), this does not provide much of a performance boost. In tests, the time to parsing a line of data into a data object dominates the time required to read the data from disk (for a reasonable modern harddrive).

Since:

JWI 1.0

Version:

2.4.0

Author:

Mark A. Finlayson

Nested Class Summary

protected class

WordnetFile.LineIterator Used to iterate over lines in a file.

Nested classes/interfaces inherited from interface edu.mit.jwi.data.IHasLifecycle

IHasLifecycle.LifecycleState, IHasLifecycle.ObjectClosedException, IHasLifecycle.ObjectOpenException

Constructor Summary

WordnetFile(java.io.File file, IContentType<T> contentType)
Constructs an instance of this class backed by the specified java File object, with the specified content type.

Method Summary

void	close() This closes the object by disposing of data backing objects or connections.
boolean	equals(java.lang.Object obj)
java.nio.ByteBuffer	getBuffer() Returns the buffer which backs this object.
IContentType<T>	getContentType() Returns the assigned content type of the resource that backs this object.
java.io.File	getFile() Returns the file which backs this object.
static java.lang.String	getLine(java.nio.ByteBuffer buf) Returns the String from the current position up to, but not including, the next newline.
static java.lang.String	getLine(java.nio.ByteBuffer buf, java.nio.charset.Charset cs) A different version of the getLine method that uses a specified character set to decode the byte stream.
java.lang.String	getName() Returns a string representation of the name of this resource.
IVersion	getVersion() Returns the wordnet version associated with this object, or null if the version cannot be determined.
int	hashCode()
boolean	isLoaded() Returns whether this object is loaded or not.
boolean	isOpen() Returns true if the dictionary is open, that is, ready to accept queries; returns false otherwise
WordnetFile.LineIterator	iterator()
WordnetFile.LineIterator	iterator(java.lang.String key) Returns an iterator that will iterator over lines in the data resource, starting at the line specified by the given key.
void	load() Starts a simple, non-blocking load.
void	load(boolean block) Initiates the loading process.
abstract WordnetFile.LineIterator	makeIterator(java.nio.ByteBuffer buffer, java.lang.String key) Constructs an iterator that can be used to iterate over the specified ByteBuffer, starting from the specified key.
boolean	open() This opens the object by performing any required initialization steps.
static void	rewindToLineStart(java.nio.ByteBuffer buf) Rewinds the specified buffer to the beginning of the current line.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface edu.mit.jwi.data.IDataSource

getLine

Constructor Detail

WordnetFile

public WordnetFile(java.io.File file,
                   IContentType<T> contentType)

Constructs an instance of this class backed by the specified java File object, with the specified content type. No effort is made to ensure that the data in the specified file is actually formatted in the proper manner for the line parser associated with the content type's data type. If these are mismatched, this will result in MisformattedLineExceptions in later calls.

Parameters:

file - the file which backs this wordnet file; may not be null

contentType - the content type for this file; may not be null

Throws:

java.lang.NullPointerException - if the specified file or content type is null

Since:

JWI 1.0

Method Detail

getName

public java.lang.String getName()

Description copied from interface: IDataSource

Returns a string representation of the name of this resource. For file-based resources, this will usually be the filename.

Specified by:

getName in interface IDataSource<T>

Returns:

the name of this resource, neither null, empty, or all whitespace

getFile

public java.io.File getFile()

Returns the file which backs this object.

Returns:

the file which backs this object, should never return null

Since:

JWI 2.2.0

getBuffer

public java.nio.ByteBuffer getBuffer()

Returns the buffer which backs this object.

Returns:

the buffer which backs this object

Throws:

ObjectClosedException - if the object is closed

Since:

JWI 2.2.0

getContentType

public IContentType<T> getContentType()

Description copied from interface: IDataSource

Returns the assigned content type of the resource that backs this object.

Specified by:

getContentType in interface IDataSource<T>

Returns:

the assigned content type for this data source. Will not return null.

open

public boolean open()
             throws java.io.IOException

Description copied from interface: IHasLifecycle

This opens the object by performing any required initialization steps. If this method returns false, then subsequent calls to IHasLifecycle.isOpen() will return false.

Specified by:

open in interface IHasLifecycle

Returns:

true if there were no errors in initialization; false otherwise.

Throws:

java.io.IOException - if there was IO error while performing initializataion

isOpen

public boolean isOpen()

Description copied from interface: IHasLifecycle

Returns true if the dictionary is open, that is, ready to accept queries; returns false otherwise

Specified by:

isOpen in interface IHasLifecycle

Returns:

true if the object is open; false otherwise

close

public void close()

Description copied from interface: IClosable

This closes the object by disposing of data backing objects or connections. If the object is already closed, or in the process of closing, this method does nothing (although, if the object is in the process of closing, it may block until closing is complete).

Specified by:

close in interface IClosable

isLoaded

public boolean isLoaded()

Description copied from interface: ILoadable

Returns whether this object is loaded or not. This method should return true only if the loading process has completed and the object is actually loaded; if the object is still in the process of loading, or failed to load, the method should return false.

Specified by:

isLoaded in interface ILoadable

Returns:

true if the method has completed loading; false otherwise

load

public void load()

Description copied from interface: ILoadable

Starts a simple, non-blocking load. If the object is already loaded, the method returns immediately and has no effect. If the object is in the process of loading, the method also returns immediately.

Specified by:

load in interface ILoadable

load

public void load(boolean block)

Description copied from interface: ILoadable

Initiates the loading process. Depending on the flag, the method may return immediately (block is false), or return only when the loading process is complete. If the object is already loaded, the method returns immediately and has no effect. If the object is in the process of loading, and the method is called in blocking mode, the method blocks until loading is complete, even if that call of the method did not initiate the loading process. Some implementors of this interface may not support the immediate-return functionality.

Specified by:

load in interface ILoadable

Parameters:

block - if true, the method returns only when the loading process is complete; if false, the method returns immediately.

getVersion

public IVersion getVersion()

Returns the wordnet version associated with this object, or null if the version cannot be determined.

Specified by:

getVersion in interface IHasVersion

Returns:

the wordnet version associated with this object, or null if the version cannot be determined

Throws:

ObjectClosedException - if the object is closed when this method is called

See Also:

IHasVersion.getVersion()

iterator

public WordnetFile.LineIterator iterator()

Specified by:

iterator in interface java.lang.Iterable<java.lang.String>

iterator

public WordnetFile.LineIterator iterator(java.lang.String key)

Description copied from interface: IDataSource

Returns an iterator that will iterator over lines in the data resource, starting at the line specified by the given key. If the key is null, this is the same as calling the plain Iterable.iterator() method. If no line starts with the pattern, the iterator's Iterator.hasNext() will return false. The iterator does not support the Iterator.remove() operation; if that method is called, the iterator will throw an UnsupportedOperationException.

Specified by:

iterator in interface IDataSource<T>

Parameters:

key - the key at which the iterator should begin

Returns:

an iterator that will iterate over the file starting at the line indexed by the specified key

makeIterator

public abstract WordnetFile.LineIterator makeIterator(java.nio.ByteBuffer buffer,
                                                      java.lang.String key)

Constructs an iterator that can be used to iterate over the specified ByteBuffer, starting from the specified key.

Parameters:

buffer - the buffer over which the iterator will iterate, should not be null

key - the key at which the iterator should begin, should not be null

Returns:

an iterator that can be used to iterate over the lines of the ByteBuffer

Since:

JWI 2.2.0

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

getLine

public static java.lang.String getLine(java.nio.ByteBuffer buf)

Returns the String from the current position up to, but not including, the next newline. The buffer's position is set to either directly after the next newline, or the end of the buffer. If the buffer is at its limit, the method returns null. If the buffer's position is directly before a valid newline marker (either \n, \r, or \r\n), then the method returns an empty string.

Parameters:

buf - the buffer from which the line should be extracted

Returns:

the remainder of line in the specified buffer, starting from the buffer's current position

Throws:

java.lang.NullPointerException - if the specified buffer is null

Since:

JWI 2.1.0

getLine

public static java.lang.String getLine(java.nio.ByteBuffer buf,
                                       java.nio.charset.Charset cs)

A different version of the getLine method that uses a specified character set to decode the byte stream. If the provided character set is null, the method defaults to the previous method getLine(ByteBuffer).

Parameters:

buf - the buffer from which the line should be extracted

cs - the character set to use for decoding; may be null

Returns:

the remainder of line in the specified buffer, starting from the buffer's current position

Throws:

java.lang.NullPointerException - if the specified buffer is null

Since:

JWI 2.3.4

rewindToLineStart

public static void rewindToLineStart(java.nio.ByteBuffer buf)

Rewinds the specified buffer to the beginning of the current line.

Parameters:

buf - the buffer to be rewound; may not be null

Throws:

java.lang.NullPointerException - if the specified buffer is null

Since:

JWI 2.2.0