org.apache.lucene.store

## Class Directory

- java.lang.Object
- - org.apache.lucene.store.Directory

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    BaseDirectory, FileSwitchDirectory, FilterDirectory

      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;
  Directory locking is implemented by an instance of `LockFactory`.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Directory()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract void` | `close()` Closes the store.
    `void` | `copyFrom(Directory from, String src, String dest, IOContext context)` Copies the file src in from to this directory 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.
    `abstract IndexOutput` | `createTempOutput(String prefix, String suffix, IOContext context)` Creates a new, empty file for writing in the directory, with a temporary file name including prefix and suffix, ending with the reserved extension `.tmp`.
    `abstract void` | `deleteFile(String name)` Removes an existing file in the directory.
    `protected void` | `ensureOpen()`
    `abstract long` | `fileLength(String name)` Returns the length of a file in the directory.
    `abstract String[]` | `listAll()` Returns an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.
    `abstract Lock` | `obtainLock(String name)` Returns an obtained `Lock`.
    `ChecksumIndexInput` | `openChecksumInput(String name, IOContext context)` Returns a stream reading an existing file, computing checksum as it reads
    `abstract IndexInput` | `openInput(String name, IOContext context)` Returns a stream reading an existing file.
    `abstract void` | `rename(String source, String dest)` Renames `source` to `dest` as an atomic operation, where `dest` does not yet exist in the directory.
    `void` | `renameFile(String source, String dest)` Deprecated. Use `rename(java.lang.String, java.lang.String)` and `syncMetaData()` instead.
    `abstract void` | `sync(Collection<String> names)` Ensure that any writes to these files are moved to stable storage.
    `abstract void` | `syncMetaData()` Ensure that directory metadata, such as recent file renames, are made durable.
    `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 an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.
      Throws:
        `IOException` - in case of IO error

    - #### 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:
      - Throws `FileNotFoundException` or `NoSuchFileException` if the file does not exist.
      - 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.

    - #### 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`

    - #### createTempOutput

          public abstract IndexOutput createTempOutput(String prefix,
                                                       String suffix,
                                                       IOContext context)
                                                throws IOException

      Creates a new, empty file for writing in the directory, with a temporary file name including prefix and suffix, ending with the reserved extension `.tmp`. Use `IndexOutput.getName()` to see what name was used.
      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`

    - #### renameFile

          @Deprecated
          public final void renameFile(String source,
                                                   String dest)
                                            throws IOException

      Deprecated. Use `rename(java.lang.String, java.lang.String)` and `syncMetaData()` instead.
      Renames `source` to `dest` as an atomic operation, where `dest` does not yet exist in the directory.

      Notes: This method is used by IndexWriter to publish commits. It is ok if this operation is not truly atomic, for example both `source` and `dest` can be visible temporarily. It is just important that the contents of `dest` appear atomically, or an exception is thrown.

      Throws:
        `IOException`

    - #### rename

          public abstract void rename(String source,
                                      String dest)
                               throws IOException

      Renames `source` to `dest` as an atomic operation, where `dest` does not yet exist in the directory.

      Notes: This method is used by IndexWriter to publish commits. It is ok if this operation is not truly atomic, for example both `source` and `dest` can be visible temporarily. It is just important that the contents of `dest` appear atomically, or an exception is thrown.

      Throws:
        `IOException`

    - #### syncMetaData

          public abstract void syncMetaData()
                                     throws IOException

      Ensure that directory metadata, such as recent file renames, are made durable.
      Throws:
        `IOException`

    - #### openInput

          public abstract IndexInput openInput(String name,
                                               IOContext context)
                                        throws IOException

      Returns a stream reading an existing file.

      Throws `FileNotFoundException` or `NoSuchFileException` if the file does not exist.

      Throws:
        `IOException`

    - #### openChecksumInput

          public ChecksumIndexInput openChecksumInput(String name,
                                                      IOContext context)
                                               throws IOException

      Returns a stream reading an existing file, computing checksum as it reads
      Throws:
        `IOException`

    - #### obtainLock

          public abstract Lock obtainLock(String name)
                                   throws IOException

      Returns an obtained `Lock`.
      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 store.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `IOException`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### copyFrom

          public void copyFrom(Directory from,
                               String src,
                               String dest,
                               IOContext context)
                        throws IOException

      Copies the file src in from to this directory 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()) {
             to.copyFrom(dir, 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`

    - #### ensureOpen

          protected void ensureOpen()
                             throws AlreadyClosedException

      Throws:
        `AlreadyClosedException` - if this Directory is closed

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