Class Directory
- All Implemented Interfaces:
Closeable,AutoCloseable
- Direct Known Subclasses:
BaseDirectory,CompoundDirectory,FileSwitchDirectory,FilterDirectory
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
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 Directory implementation instance as this may cause deadlock; use
your own (non-Lucene) objects instead.
- See Also:
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract voidclose()Closes the directory.voidCopies 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 voidEnsures this directory is still open.abstract longfileLength(String name) Returns the byte length of a file in the directory.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.openChecksumInput(String name) Opens a checksum-computing stream for reading an existing file.abstract IndexInputOpens a stream for reading an existing file.abstract voidRenamessourcefile 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 voidEnsures that directory metadata, such as recent file renames, are moved to stable storage.toString()
-
Constructor Details
-
Directory
public Directory()
-
-
Method Details
-
listAll
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
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
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
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
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
Ensures that directory metadata, such as recent file renames, are moved to stable storage.- Throws:
IOException- See Also:
-
rename
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
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
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
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
Closes the directory.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException
-
copyFrom
Copies an existingsrcfile from directoryfromto a non-existent filedestin this directory. The given IOContext is only used for opening the destination file.- Throws:
IOException
-
toString
-
ensureOpen
Ensures this directory is still open.- Throws:
AlreadyClosedException- if this directory is closed.
-
getPendingDeletions
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
Creates a file name for a temporary file. The name will start withprefix, end withsuffixand have a reserved file extension.tmp.- See Also:
-