FSDirectory

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

• MMapDirectory uses memory-mapped IO when reading. This is a good choice if you have plenty of virtual memory relative to your index size, eg if you are running on a 64 bit JRE, or you are running on a 32 bit JRE but your index sizes are small enough to fit into the virtual memory space. This class will use the modern [ ] API available since Java 21 which allows to safely unmap previously mmapped files after closing the IndexInputs. There is no need to enable the "preview feature" of your Java version; it works out of box with some compilation tricks. For more information about the foreign memory API read documentation of the [ ] package and Uwe's blog post.

• NIOFSDirectory uses java.nio's FileChannel's positional io when reading to avoid synchronization when reading from the same file. Unfortunately, due to a Windows-only Sun JRE bug this is a poor choice for Windows, but on all other platforms this is the preferred choice. Applications using Thread.interrupt or Future.cancel should use RAFDirectory instead, which is provided in the misc module. See [ ] javadoc for details.

Unfortunately, because of system peculiarities, there is no single overall best implementation. Therefore, we've added the .open 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. For all others, you should instantiate the desired implementation directly.

NOTE: Accessing one of the above subclasses either directly or indirectly from a thread while it's interrupted can close the underlying channel immediately if at the same time the thread is blocked on IO. The channel will remain closed and subsequent access to the index will throw a ClosedChannelException. Applications using Thread.interrupt or Future.cancel should use the slower legacy RAFDirectory from the misc Lucene module instead.

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

See also

Inheritors