org.apache.lucene.store
Class Directory

java.lang.Object
  org.apache.lucene.store.Directory

Direct Known Subclasses:

FileSwitchDirectory, FSDirectory, RAMDirectory

public abstract class Directory
extends Object

A Directory is a flat list of files. Files may be written once, when they are created. Once a file is created it may only be opened for read, or deleted. Random access is permitted both when reading and writing.

Java's i/o APIs not used directly, but rather all i/o is through this API. This permits things such as:

• implementation of RAM-based indices;
• implementation indices stored in a database, via JDBC;
• implementation of an index as a single file;

Directory locking is implemented by an instance of LockFactory, and can be changed for each Directory instance using setLockFactory(org.apache.lucene.store.LockFactory).

Field Summary

protected boolean	isOpen
protected LockFactory	lockFactory Holds the LockFactory instance (implements locking for this Directory instance).

Constructor Summary

Directory()

Method Summary

void	clearLock(String name) Attempt to clear (forcefully unlock and remove) the specified lock.
abstract void	close() Closes the store.
static void	copy(Directory src, Directory dest, boolean closeDirSrc) Copy contents of a directory src to a directory dest.
abstract IndexOutput	createOutput(String name) Creates a new, empty file in the directory with the given name.
abstract void	deleteFile(String name) Removes an existing file in the directory.
protected void	ensureOpen()
abstract boolean	fileExists(String name) Returns true iff a file with the given name exists.
abstract long	fileLength(String name) Returns the length of a file in the directory.
abstract long	fileModified(String name) Returns the time the named file was last modified.
LockFactory	getLockFactory() Get the LockFactory that this Directory instance is using for its locking implementation.
String	getLockID() Return a string identifier that uniquely differentiates this Directory instance from other Directory instances.
abstract String[]	list() Deprecated. For some Directory implementations (FSDirectory, and its subclasses), this method silently filters its results to include only index files. Please use listAll() instead, which does no filtering.
String[]	listAll() Returns an array of strings, one for each file in the directory.
Lock	makeLock(String name) Construct a Lock.
abstract IndexInput	openInput(String name) Returns a stream reading an existing file.
IndexInput	openInput(String name, int bufferSize) Returns a stream reading an existing file, with the specified read buffer size.
abstract void	renameFile(String from, String to) Deprecated.
void	setLockFactory(LockFactory lockFactory) Set the LockFactory that this Directory instance should use for its locking implementation.
void	sync(String name) Ensure that any writes to this file are moved to stable storage.
String	toString()
abstract void	touchFile(String name) Set the modified time of an existing file to now.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

isOpen

protected volatile boolean isOpen

lockFactory

protected LockFactory lockFactory

Holds the LockFactory instance (implements locking for this Directory instance).

Constructor Detail

Directory

public Directory()

Method Detail

list

public abstract String[] list()
                       throws IOException

Deprecated. For some Directory implementations (FSDirectory, and its subclasses), this method silently filters its results to include only index files. Please use listAll() instead, which does no filtering.

List the files in the directory.

Throws:

IOException

listAll

public String[] listAll()
                 throws IOException

Returns an array of strings, one for each file in the directory. Unlike list() this method does no filtering of the contents in a directory, and it will never return null (throws IOException instead). Currently this method simply falls back to list() for Directory impls outside of Lucene's core & contrib, but in 3.0 that method will be removed and this method will become abstract.

Throws:

IOException

fileExists

public abstract boolean fileExists(String name)
                            throws IOException

Returns true iff a file with the given name exists.

Throws:

IOException

fileModified

public abstract long fileModified(String name)
                           throws IOException

Returns the time the named file was last modified.

Throws:

IOException

touchFile

public abstract void touchFile(String name)
                        throws IOException

Set the modified time of an existing file to now.

Throws:

IOException

deleteFile

public abstract void deleteFile(String name)
                         throws IOException

Removes an existing file in the directory.

Throws:

IOException

renameFile

public abstract void renameFile(String from,
                                String to)
                         throws IOException

Deprecated.

Renames an existing file in the directory. If a file already exists with the new name, then it is replaced. This replacement is not guaranteed to be atomic.

Throws:

IOException

fileLength

public abstract long fileLength(String name)
                         throws IOException

Returns the length of a file in the directory.

Throws:

IOException

createOutput

public abstract IndexOutput createOutput(String name)
                                  throws IOException

Creates a new, empty file in the directory with the given name. Returns a stream writing this file.

Throws:

IOException

sync

public void sync(String name)
          throws IOException

Ensure that any writes to this file are moved to stable storage. Lucene uses this to properly commit changes to the index, to prevent a machine/OS crash from corrupting the index.

Throws:

IOException

openInput

public abstract IndexInput openInput(String name)
                              throws IOException

Returns a stream reading an existing file.

Throws:

IOException

openInput

public IndexInput openInput(String name,
                            int bufferSize)
                     throws IOException

Returns a stream reading an existing file, with the specified read buffer size. The particular Directory implementation may ignore the buffer size. Currently the only Directory implementations that respect this parameter are FSDirectory and CompoundFileReader.

Throws:

IOException

makeLock

public Lock makeLock(String name)

Construct a Lock.

Parameters:

name - the name of the lock file

clearLock

public void clearLock(String name)
               throws IOException

Attempt to clear (forcefully unlock and remove) the specified lock. Only call this at a time when you are certain this lock is no longer in use.

Parameters:

name - name of the lock to be cleared.

Throws:

IOException

close

public abstract void close()
                    throws IOException

Closes the store.

Throws:

IOException

setLockFactory

public void setLockFactory(LockFactory lockFactory)

Set the LockFactory that this Directory instance should use for its locking implementation. Each * instance of LockFactory should only be used for one directory (ie, do not share a single instance across multiple Directories).

Parameters:

lockFactory - instance of LockFactory.

getLockFactory

public LockFactory getLockFactory()

Get the LockFactory that this Directory instance is using for its locking implementation. Note that this may be null for Directory implementations that provide their own locking implementation.

getLockID

public String getLockID()

Return a string identifier that uniquely differentiates this Directory instance from other Directory instances. This ID should be the same if two Directory instances (even in different JVMs and/or on different machines) are considered "the same index". This is how locking "scopes" to the right index.

toString

public String toString()

Overrides:

toString in class Object

copy

public static void copy(Directory src,
                        Directory dest,
                        boolean closeDirSrc)
                 throws IOException

Copy contents of a directory src to a directory dest. If a file in src already exists in dest then the one in dest will be blindly overwritten.

NOTE: the source directory cannot change while this method is running. Otherwise the results are undefined and you could easily hit a FileNotFoundException.

NOTE: this method only copies files that look like index files (ie, have extensions matching the known extensions of index files).

Parameters:

src - source directory

dest - destination directory

closeDirSrc - if true, call close() method on source directory

Throws:

IOException

ensureOpen

protected final void ensureOpen()
                         throws AlreadyClosedException

Throws:

AlreadyClosedException - if this Directory is closed