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
ADirectoryprovides 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
IndexOutputis 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)). CallingcreateOutput(java.lang.String, org.apache.lucene.store.IOContext)on an existing file must throwFileAlreadyExistsException.
NOTE: If your application requires external synchronization, you should not synchronize on the
Directoryimplementation instance as this may cause deadlock; use your own (non-Lucene) objects instead.- See Also:
FSDirectory,ByteBuffersDirectory,FilterDirectory
-
-
Constructor Summary
Constructors Constructor Description Directory()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract voidclose()Closes the directory.voidcopyFrom(Directory from, String src, String dest, IOContext context)Copies an existingsrcfile from directoryfromto a non-existent filedestin this directory.abstract IndexOutputcreateOutput(String name, IOContext context)Creates a new, empty file in the directory and returns anIndexOutputinstance for appending data to this file.abstract IndexOutputcreateTempOutput(String prefix, String suffix, IOContext context)Creates a new, empty, temporary file in the directory and returns anIndexOutputinstance for appending data to this file.abstract voiddeleteFile(String name)Removes an existing file in the directory.protected voidensureOpen()Ensures this directory is still open.abstract longfileLength(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 StringgetTempFileName(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 LockobtainLock(String name)Acquires and returns aLockfor a file with the given name.ChecksumIndexInputopenChecksumInput(String name, IOContext context)Opens a checksum-computing stream for reading an existing file.abstract IndexInputopenInput(String name, IOContext context)Opens a stream for reading an existing file.abstract voidrename(String source, String dest)Renamessourcefile todestfile wheredestmust not already exist in the directory.abstract voidsync(Collection<String> names)Ensures that any writes to these files are moved to stable storage (made durable).abstract voidsyncMetaData()Ensures that directory metadata, such as recent file renames, are moved to stable storage.StringtoString()
-
-
-
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'sString.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
NoSuchFileExceptionorFileNotFoundExceptionifnamepoints 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
NoSuchFileExceptionorFileNotFoundExceptionifnamepoints 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 anIndexOutputinstance for appending data to this file.This method must throw
FileAlreadyExistsExceptionif 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 anIndexOutputinstance for appending data to this file.The temporary file name (accessible via
IndexOutput.getName()) will start withprefix, end withsuffixand 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 IOExceptionEnsures 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
Renamessourcefile todestfile wheredestmust not already exist in the directory.It is permitted for this operation to not be truly atomic, for example both
sourceanddestcan be visible temporarily inlistAll(). However, the implementation of this method must ensure the content ofdestappears as the entiresourceatomically. So oncedestis visible for readers, the entire content of previoussourceis 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
NoSuchFileExceptionorFileNotFoundExceptionifnamepoints 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
NoSuchFileExceptionorFileNotFoundExceptionifnamepoints 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 aLockfor 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 IOExceptionCloses the directory.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException
-
copyFrom
public void copyFrom(Directory from, String src, String dest, IOContext context) throws IOException
Copies an existingsrcfile from directoryfromto a non-existent filedestin this directory. The given IOContext is only used for opening the destination file.- Throws:
IOException
-
ensureOpen
protected void ensureOpen() throws AlreadyClosedExceptionEnsures 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.
-
-