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`.
  See Also:
    `FSDirectory`, `RAMDirectory`, `FilterDirectory`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Directory()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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, IOContext context)` 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 Detail

    - #### Directory

          public Directory()

  - ### Method Detail

    - #### 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,
                                                      IOContext context)
                                               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 `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      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.
      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)`

Copyright © 2000-2020 Apache Software Foundation. All Rights Reserved.