org.apache.lucene.store

Class Directory

java.lang.Object

org.apache.lucene.store.Directory

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

BaseDirectory, FileSwitchDirectory, FilterDirectory

public abstract class Directory
extends Object
implements Closeable

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.

Constructor Summary

Constructors

Constructor and Description
Directory()

Method Summary

Modifier and Type	Method and Description
abstract void	close() Closes the store.
void	copyFrom(Directory from, String src, String dest, IOContext context) Copies the file src in from to this directory under the new file name dest.
abstract IndexOutput	createOutput(String name, IOContext context) Creates a new, empty file in the directory with the given name.
abstract IndexOutput	createTempOutput(String prefix, String suffix, IOContext context) Creates a new, empty file for writing in the directory, with a temporary file name including prefix and suffix, ending with the reserved extension .tmp.
abstract void	deleteFile(String name) Removes an existing file in the directory.
protected void	ensureOpen()
abstract long	fileLength(String name) Returns the length of a file in the directory.
abstract String[]	listAll() Returns an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.
abstract Lock	obtainLock(String name) Returns an obtained Lock.
ChecksumIndexInput	openChecksumInput(String name, IOContext context) Returns a stream reading an existing file, computing checksum as it reads
abstract IndexInput	openInput(String name, IOContext context) Returns a stream reading an existing file.
abstract void	renameFile(String source, String dest) Renames source to dest as an atomic operation, where dest does not yet exist in the directory.
abstract void	sync(Collection<String> names) Ensure that any writes to these files are moved to stable storage.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

Directory

public Directory()

Method Detail

listAll

public abstract String[] listAll()
                          throws IOException

Returns an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.

Throws:

IOException - in case of IO error

deleteFile

public abstract void deleteFile(String name)
                         throws IOException

Removes an existing file in the directory.

Throws:

IOException

fileLength

public abstract long fileLength(String name)
                         throws IOException

Returns the length of a file in the directory. This method follows the following contract:

• Throws FileNotFoundException or NoSuchFileException if the file does not exist.
• Returns a value ≥0 if the file exists, which specifies its length.

Parameters:

name - the name of the file for which to return the length.

Throws:

IOException - if there was an IO error while retrieving the file's length.

createOutput

public abstract IndexOutput createOutput(String name,
                                         IOContext context)
                                  throws IOException

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

Throws:

IOException

createTempOutput

public abstract IndexOutput createTempOutput(String prefix,
                                             String suffix,
                                             IOContext context)
                                      throws IOException

Creates a new, empty file for writing in the directory, with a temporary file name including prefix and suffix, ending with the reserved extension .tmp. Use IndexOutput.getName() to see what name was used.

Throws:

IOException

sync

public abstract void sync(Collection<String> names)
                   throws IOException

Ensure that any writes to these files 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.
NOTE: Clients may call this method for same files over and over again, so some impls might optimize for that. For other impls the operation can be a noop, for various reasons.

Throws:

IOException

renameFile

public abstract void renameFile(String source,
                                String dest)
                         throws IOException

Renames source to dest as an atomic operation, where dest does not yet exist in the directory.

Notes: This method is used by IndexWriter to publish commits. It is ok if this operation is not truly atomic, for example both source and dest can be visible temporarily. It is just important that the contents of dest appear atomically, or an exception is thrown.

Throws:

IOException

openInput

public abstract IndexInput openInput(String name,
                                     IOContext context)
                              throws IOException

Returns a stream reading an existing file.

Throws FileNotFoundException or NoSuchFileException if the file does not exist.

Throws:

IOException

openChecksumInput

public ChecksumIndexInput openChecksumInput(String name,
                                            IOContext context)
                                     throws IOException

Returns a stream reading an existing file, computing checksum as it reads

Throws:

IOException

obtainLock

public abstract Lock obtainLock(String name)
                         throws IOException

Returns an obtained Lock.

Parameters:

name - the name of the lock file

Throws:

LockObtainFailedException - (optional specific exception) if the lock could not be obtained because it is currently held elsewhere.

IOException - if any i/o error occurs attempting to gain the lock

close

public abstract void close()
                    throws IOException

Closes the store.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object

copyFrom

public void copyFrom(Directory from,
                     String src,
                     String dest,
                     IOContext context)
              throws IOException

Copies the file src in from to this directory under the new file name dest.

If you want to copy the entire source directory to the destination one, you can do so like this:

 Directory to; // the directory to copy to
 for (String file : dir.listAll()) {
   to.copyFrom(dir, file, newFile, IOContext.DEFAULT); // newFile can be either file, or a new name
 }
 

NOTE: this method does not check whether dest exist and will overwrite it if it does.

Throws:

IOException

ensureOpen

protected void ensureOpen()
                   throws AlreadyClosedException

Throws:

AlreadyClosedException - if this Directory is closed