Package org.apache.lucene.store

Class Directory

java.lang.Object

org.apache.lucene.store.Directory

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

BaseDirectory, CompoundDirectory, FileSwitchDirectory, FilterDirectory

public abstract class Directory
extends Object
implements Closeable

A Directory provides an abstraction layer for storing a list of files. A directory contains only files (no sub-folder hierarchy).

Implementing classes must comply with the following:

• A file in a directory can be created (createOutput(java.lang.String, org.apache.lucene.store.IOContext)), appended to, then closed.
• A file open for writing may not be available for read access until the corresponding IndexOutput is closed.
• Once a file is created it must only be opened for input (openInput(java.lang.String, org.apache.lucene.store.IOContext)), or deleted (deleteFile(java.lang.String)). Calling createOutput(java.lang.String, org.apache.lucene.store.IOContext) on an existing file must throw FileAlreadyExistsException.

See Also:

FSDirectory, ByteBuffersDirectory, FilterDirectory

Constructor Summary

Constructors

Constructor	Description
Directory()

Method Summary

Modifier and Type	Method	Description
abstract void	close()	Closes the directory.
void	copyFrom(Directory from, String src, String dest, IOContext context)	Copies an existing src file from directory from to a non-existent file dest in this directory.
abstract IndexOutput	createOutput(String name, IOContext context)	Creates a new, empty file in the directory and returns an IndexOutput instance for appending data to this file.
abstract IndexOutput	createTempOutput(String prefix, String suffix, IOContext context)	Creates a new, empty, temporary file in the directory and returns an IndexOutput instance for appending data to this file.
abstract void	deleteFile(String name)	Removes an existing file in the directory.
protected void	ensureOpen()	Ensures this directory is still open.
abstract long	fileLength(String name)	Returns the byte length of a file in the directory.
abstract Set<String>	getPendingDeletions()	Returns a set of files currently pending deletion in this directory.
protected static String	getTempFileName(String prefix, String suffix, long counter)	Creates a file name for a temporary file.
abstract String[]	listAll()	Returns names of all files stored in this directory.
abstract Lock	obtainLock(String name)	Acquires and returns a Lock for a file with the given name.
ChecksumIndexInput	openChecksumInput(String name, IOContext context)	Opens a checksum-computing stream for reading an existing file.
abstract IndexInput	openInput(String name, IOContext context)	Opens a stream for reading an existing file.
abstract void	rename(String source, String dest)	Renames source file to dest file where dest must not already exist in the directory.
abstract void	sync(Collection<String> names)	Ensures that any writes to these files are moved to stable storage (made durable).
abstract void	syncMetaData()	Ensures that directory metadata, such as recent file renames, 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 names of all files stored in this directory. The output must be in sorted (UTF-16, java's String.compareTo(java.lang.String)) order.

Throws:

IOException - in case of I/O error

deleteFile

public abstract void deleteFile(String name)
                         throws IOException

Removes an existing file in the directory.

This method must throw either NoSuchFileException or FileNotFoundException if name points to a non-existing file.

Parameters:

name - the name of an existing file.

Throws:

IOException - in case of I/O error

fileLength

public abstract long fileLength(String name)
                         throws IOException

Returns the byte length of a file in the directory.

This method must throw either NoSuchFileException or FileNotFoundException if name points to a non-existing file.

Parameters:

name - the name of an existing file.

Throws:

IOException - in case of I/O error

createOutput

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

Creates a new, empty file in the directory and returns an IndexOutput instance for appending data to this file.

This method must throw FileAlreadyExistsException if the file already exists.

Parameters:

name - the name of the file to create.

Throws:

IOException - in case of I/O error

createTempOutput

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

Creates a new, empty, temporary file in the directory and returns an IndexOutput instance for appending data to this file.

The temporary file name (accessible via IndexOutput.getName()) will start with prefix, end with suffix and have a reserved file extension .tmp.

Throws:

IOException

sync

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

Ensures that any writes to these files are moved to stable storage (made durable).

Lucene uses this to properly commit changes to the index, to prevent a machine/OS crash from corrupting the index.

Throws:

IOException

See Also:

syncMetaData()

syncMetaData

public abstract void syncMetaData()
                           throws IOException

Ensures that directory metadata, such as recent file renames, are moved to stable storage.

Throws:

IOException

See Also:

sync(Collection)

rename

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

Renames source file to dest file where dest must not already exist in the directory.

It is permitted for this operation to not be truly atomic, for example both source and dest can be visible temporarily in listAll(). However, the implementation of this method must ensure the content of dest appears as the entire source atomically. So once dest is visible for readers, the entire content of previous source is visible.

This method is used by IndexWriter to publish commits.

Throws:

IOException

openInput

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

Opens a stream for reading an existing file.

This method must throw either NoSuchFileException or FileNotFoundException if name points to a non-existing file.

Parameters:

name - the name of an existing file.

Throws:

IOException - in case of I/O error

openChecksumInput

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

Opens a checksum-computing stream for reading an existing file.

This method must throw either NoSuchFileException or FileNotFoundException if name points to a non-existing file.

Parameters:

name - the name of an existing file.

Throws:

IOException - in case of I/O error

obtainLock

public abstract Lock obtainLock(String name)
                         throws IOException

Acquires and returns a Lock for a file with the given name.

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 directory.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

copyFrom

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

Copies an existing src file from directory from to a non-existent file dest in this directory.

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object

ensureOpen

protected void ensureOpen()
                   throws AlreadyClosedException

Ensures this directory is still open.

Throws:

AlreadyClosedException - if this directory is closed.

getPendingDeletions

public abstract Set<String> getPendingDeletions()
                                         throws IOException

Returns a set of files currently pending deletion in this directory.

Throws:

IOException

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

getTempFileName

protected static String getTempFileName(String prefix,
                                        String suffix,
                                        long counter)

Creates a file name for a temporary file. The name will start with prefix, end with suffix and have a reserved file extension .tmp.

See Also:

createTempOutput(String, String, IOContext)