Namespace Lucene.Net.Store

Classes

AlreadyClosedException

This exception is thrown when there is an attempt to access something that has already been closed.

BufferedIndexInput

Base implementation class for buffered IndexInput.

BufferedIndexOutput

Base implementation class for buffered IndexOutput.

ChecksumIndexInput

Writes bytes through to a primary IndexOutput, computing checksum as it goes. Note that you cannot use seek().

ChecksumIndexOutput

Writes bytes through to a primary IndexOutput, computing checksum. Note that you cannot use seek().

Directory

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:

Directory locking is implemented by an instance of LockFactory , and can be changed for each Directory instance using SetLockFactory(LockFactory).

FileSwitchDirectory

Expert: A Directory instance that switches files between two other Directory instances.

Files with the specified extensions are placed in the primary directory; others are placed in the secondary directory. The provided Set must not change once passed to this class, and must allow multiple threads to call contains at once.

NOTE: this API is new and experimental and is subject to suddenly change in the next release.

FSDirectory

Base class for Directory implementations that store index files in the file system. There are currently three core subclasses:

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the Open(IO.DirectoryInfo) method, to allow Lucene to choose the best FSDirectory implementation given your environment, and the known limitations of each implementation. For users who have no reason to prefer a specific implementation, it's best to simply use Open(IO.DirectoryInfo) . For all others, you should instantiate the desired implementation directly.

The locking implementation is by default NativeFSLockFactory , but can be changed by passing in a custom LockFactory instance.

FSLockFactory

Base class for file system based locking implementation.

IndexInput

Abstract base class for input from a file in a Directory. A random-access input stream. Used for all Lucene index input operations.

IndexOutput

Abstract base class for output to a file in a Directory. A random-access output stream. Used for all Lucene index output operations.

Lock

An interprocess mutex lock.

Typical use might look like:

new Lock.With(directory.makeLock("my.lock")) {
public Object doBody() {
... code to execute while locked ...
}
}.run();

Lock.With

Utility class for executing code with exclusive access.

LockFactory

Base class for Locking implementation. Directory uses instances of this class to implement locking.

Note that there are some useful tools to verify that your LockFactory is working correctly: VerifyingLockFactory , LockStressTest, LockVerifyServer .

LockObtainFailedException

This exception is thrown when the write.lock could not be acquired. This happens when a writer tries to open an index that another writer already has open.

LockReleaseFailedException

This exception is thrown when the write.lock could not be released.

LockStressTest

Simple standalone tool that forever acquires & releases a lock using a specific LockFactory. Run without any args to see usage.

LockVerifyServer

Simple standalone server that must be running when you use VerifyingLockFactory. This server simply verifies at most one process holds the lock at a time. Run without any args to see usage.

MMapDirectory

File-based Directory implementation that uses mmap for reading, and SimpleFSDirectory.SimpleFSIndexOutput for writing.

NOTE: memory mapping uses up a portion of the virtual memory address space in your process equal to the size of the file being mapped. Before using this class, be sure your have plenty of virtual address space, e.g. by using a 64 bit JRE, or a 32 bit JRE with indexes that are guaranteed to fit within the address space. On 32 bit platforms also consult MaxChunkSize if you have problems with mmap failing because of fragmented address space. If you get an OutOfMemoryException, it is recommened to reduce the chunk size, until it works.

Due to this bug in Sun's JRE, MMapDirectory's Close() is unable to close the underlying OS file handle. Only when GC finally collects the underlying objects, which could be quite some time later, will the file handle be closed.

This will consume additional transient disk usage: on Windows, attempts to delete or overwrite the files will result in an exception; on other platforms, which typically have a "delete on last close" semantics, while such operations will succeed, the bytes are still consuming space on disk. For many applications this limitation is not a problem (e.g. if you have plenty of disk space, and you don't rely on overwriting files on Windows) but it's still an important limitation to be aware of.

This class supplies the workaround mentioned in the bug report (disabled by default, see UseUnmap), which may fail on non-Sun JVMs. It forcefully unmaps the buffer on close by using an undocumented internal cleanup functionality. UNMAP_SUPPORTED is true, if the workaround can be enabled (with no guarantees).

MMapDirectory.MultiMMapIndexInput

NativeFSLockFactory

Implements LockFactory using native OS file locks. Note that because this LockFactory relies on java.nio.* APIs for locking, any problems with those APIs will cause locking to fail. Specifically, on certain NFS environments the java.nio.* locks will fail (the lock can incorrectly be double acquired) whereas SimpleFSLockFactory worked perfectly in those same environments. For NFS based access to an index, it's recommended that you try SimpleFSLockFactory first and work around the one limitation that a lock file could be left when the JVM exits abnormally.

The primary benefit of NativeFSLockFactory is that lock files will be properly removed (by the OS) if the JVM has an abnormal exit.

Note that, unlike SimpleFSLockFactory, the existence of leftover lock files in the filesystem on exiting the JVM is fine because the OS will free the locks held against these files even though the files still remain.

If you suspect that this or any other LockFactory is not working properly in your environment, you can easily test it by using VerifyingLockFactory, LockVerifyServer and LockStressTest.

NIOFSDirectory

Not implemented. Waiting for volunteers.

NIOFSDirectory.NIOFSIndexInput

Not implemented. Waiting for volunteers.

NoLockFactory

Use this LockFactory to disable locking entirely. Only one instance of this lock is created. You should call Instance to get the instance.

NoSuchDirectoryException

This exception is thrown when you try to list a non-existent directory.

RAMDirectory

A memory-resident Directory implementation. Locking implementation is by default the SingleInstanceLockFactory but can be changed with SetLockFactory(LockFactory).

RAMFile

RAMInputStream

A memory-resident IndexInput implementation.

RAMOutputStream

A memory-resident IndexOutput implementation.

For lucene internal use.

SimpleFSDirectory

A straightforward implementation of FSDirectory using java.io.RandomAccessFile. However, this class has poor concurrent performance (multiple threads will bottleneck) as it synchronizes when multiple threads read from the same file. It's usually better to use NIOFSDirectory or MMapDirectory instead.

SimpleFSDirectory.SimpleFSIndexInput

SimpleFSDirectory.SimpleFSIndexInput.Descriptor

SimpleFSDirectory.SimpleFSIndexOutput

SimpleFSLockFactory

Implements LockFactory using .

NOTE: the javadocs for File.createNewFile contain a vague yet spooky warning about not using the API for file locking. This warning was added due to this bug, and in fact the only known problem with using this API for locking is that the Lucene write lock may not be released when the JVM exits abnormally.

When this happens, a LockObtainFailedException is hit when trying to create a writer, in which case you need to explicitly clear the lock file first. You can either manually remove the file, or use the Unlock(Directory) API. But, first be certain that no writer is in fact writing to the index otherwise you can easily corrupt your index.

If you suspect that this or any other LockFactory is not working properly in your environment, you can easily test it by using VerifyingLockFactory, LockVerifyServer and LockStressTest.

SingleInstanceLockFactory

Implements LockFactory for a single in-process instance, meaning all locking will take place through this one instance. Only use this LockFactory when you are certain all IndexReaders and IndexWriters for a given index are running against a single shared in-process Directory instance. This is currently the default locking for RAMDirectory.

VerifyingLockFactory

A LockFactory that wraps another LockFactory and verifies that each lock obtain/release is "correct" (never results in two processes holding the lock at the same time). It does this by contacting an external server (LockVerifyServer) to assert that at most one process holds the lock at a time. To use this, you should also run LockVerifyServer on the host & port matching what you pass to the constructor.