Package org.apache.lucene.store
Class Directory
- java.lang.Object
-
- org.apache.lucene.store.Directory
-
- All Implemented Interfaces:
Closeable
,AutoCloseable
- Direct Known Subclasses:
BaseDirectory
,FilterDirectory
,NRTCachingDirectory
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;
LockFactory
, and can be changed for each Directory instance usingsetLockFactory(org.apache.lucene.store.LockFactory)
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
Directory.IndexInputSlicer
Allows to create one or more slicedIndexInput
instances from a single file handle.
-
Constructor Summary
Constructors Constructor Description Directory()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
clearLock(String name)
Attempt to clear (forcefully unlock and remove) the specified lock.abstract void
close()
Closes the store.void
copy(Directory to, String src, String dest, IOContext context)
Copies the file src toDirectory
to 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.Directory.IndexInputSlicer
createSlicer(String name, IOContext context)
Creates anDirectory.IndexInputSlicer
for the given file 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 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[]
listAll()
Returns an array of strings, one for each file in the directory.abstract Lock
makeLock(String name)
Construct aLock
.abstract IndexInput
openInput(String name, IOContext context)
Returns a stream reading an existing file, with the specified read buffer size.abstract void
setLockFactory(LockFactory lockFactory)
Set the LockFactory that this Directory instance should use for its locking implementation.abstract void
sync(Collection<String> names)
Ensure that any writes to these files are moved to stable storage.String
toString()
-
-
-
Method Detail
-
listAll
public abstract String[] listAll() throws IOException
Returns an array of strings, one for each file in the directory.- Throws:
NoSuchDirectoryException
- if the directory is not prepared for any write operations (such ascreateOutput(String, IOContext)
).IOException
- in case of other IO errors
-
fileExists
public abstract boolean fileExists(String name) throws IOException
Returns true iff a file with the given name exists.- Throws:
IOException
-
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:- Must throw
FileNotFoundException
if the file does not exist (notjava.nio.file.NoSuchFileException
of Java 7). - 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.
- Must throw
-
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
-
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
-
openInput
public abstract IndexInput openInput(String name, IOContext context) 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 areFSDirectory
andCompoundFileDirectory
.- Must throw
FileNotFoundException
if the file does not exist (notjava.nio.file.NoSuchFileException
of Java 7).- Throws:
IOException
- Must throw
-
makeLock
public abstract Lock makeLock(String name)
Construct aLock
.- Parameters:
name
- the name of the lock file
-
clearLock
public abstract 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.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
-
setLockFactory
public abstract void setLockFactory(LockFactory lockFactory) throws IOException
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 ofLockFactory
.- Throws:
IOException
-
getLockFactory
public abstract 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.
-
copy
public void copy(Directory to, String src, String dest, IOContext context) throws IOException
Copies the file src toDirectory
to 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()) { dir.copy(to, 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
-
createSlicer
public Directory.IndexInputSlicer createSlicer(String name, IOContext context) throws IOException
Creates anDirectory.IndexInputSlicer
for the given file name. IndexInputSlicer allows otherDirectory
implementations to efficiently open one or more slicedIndexInput
instances from a single file handle. The underlying file handle is kept open until theDirectory.IndexInputSlicer
is closed.- Must throw
FileNotFoundException
if the file does not exist (notjava.nio.file.NoSuchFileException
of Java 7).- Throws:
IOException
- if anIOException
occurs
- Must throw
-
ensureOpen
protected void ensureOpen() throws AlreadyClosedException
- Throws:
AlreadyClosedException
- if this Directory is closed
-
-