Package org.apache.lucene.store

# 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
A `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 `IndexOutput` is 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)`). Calling `createOutput(java.lang.String, org.apache.lucene.store.IOContext)` on an existing file must throw `FileAlreadyExistsException`.

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:
  - `FSDirectory`
  - `ByteBuffersDirectory`
  - `FilterDirectory`

## Constructor Summary

Constructors
Constructor
Description
`Directory()`

## Method Summary

Modifier and Type
Method
Description
`abstract void`
`close()`
Closes the directory.
`void`
`copyFrom(Directory from, String src, String dest, IOContext context)`
Copies an existing `src` file from directory `from` to a non-existent file `dest` in this directory.
`abstract IndexOutput`
`createOutput(String name, IOContext context)`
Creates a new, empty file in the directory and returns an `IndexOutput` instance for appending data to this file.
`abstract IndexOutput`
`createTempOutput(String prefix, String suffix, IOContext context)`
Creates a new, empty, temporary file in the directory and returns an `IndexOutput` instance for appending data to this file.
`abstract void`
`deleteFile(String name)`
Removes an existing file in the directory.
`protected void`
`ensureOpen()`
Ensures this directory is still open.
`abstract long`
`fileLength(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 String`
`getTempFileName(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 Lock`
`obtainLock(String name)`
Acquires and returns a `Lock` for a file with the given name.
`ChecksumIndexInput`
`openChecksumInput(String name)`
Opens a checksum-computing stream for reading an existing file.
`abstract IndexInput`
`openInput(String name, IOContext context)`
Opens a stream for reading an existing file.
`abstract void`
`rename(String source, String dest)`
Renames `source` file to `dest` file where `dest` must not already exist in the directory.
`abstract void`
`sync(Collection<String> names)`
Ensures that any writes to these files are moved to stable storage (made durable).
`abstract void`
`syncMetaData()`
Ensures that directory metadata, such as recent file renames, are moved to stable storage.
`String`
`toString()`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### Directory

public Directory()

## Method Details

### 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's `String.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 `NoSuchFileException` or `FileNotFoundException` if `name` points 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 `NoSuchFileException` or `FileNotFoundException` if `name` points 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 an `IndexOutput` instance for appending data to this file.

This method must throw `FileAlreadyExistsException` if 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 an `IndexOutput` instance for appending data to this file.

The temporary file name (accessible via `IndexOutput.getName()`) will start with `prefix`, end with `suffix` and 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 IOException
Ensures 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
Renames `source` file to `dest` file where `dest` must not already exist in the directory.

It is permitted for this operation to not be truly atomic, for example both `source` and `dest` can be visible temporarily in `listAll()`. However, the implementation of this method must ensure the content of `dest` appears as the entire `source` atomically. So once `dest` is visible for readers, the entire content of previous `source` is 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 `NoSuchFileException` or `FileNotFoundException` if `name` points 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) throws IOException
Opens a checksum-computing stream for reading an existing file.

This method must throw either `NoSuchFileException` or `FileNotFoundException` if `name` points 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 a `Lock` for 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 IOException
Closes the directory.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `IOException`

### copyFrom

public void copyFrom(Directory from, String src, String dest, IOContext context) throws IOException
Copies an existing `src` file from directory `from` to a non-existent file `dest` in this directory. The given IOContext is only used for opening the destination file.

Throws:
  `IOException`

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### ensureOpen

protected void ensureOpen() throws AlreadyClosedException
Ensures 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.

### getTempFileName

protected static String getTempFileName(String prefix, String suffix, long counter)
Creates a file name for a temporary file. The name will start with `prefix`, end with `suffix` and have a reserved file extension `.tmp`.

See Also:
  - `createTempOutput(String, String, IOContext)`