org.apache.lucene.store

## Class Directory

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

- All Implemented Interfaces:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    CompoundFileDirectory, FileSwitchDirectory, FSDirectory, NRTCachingDirectory, RAMDirectory, RateLimitedDirectoryWrapper, TrackingDirectoryWrapper

      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`, and can be changed for each Directory instance using `setLockFactory(org.apache.lucene.store.LockFactory)`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `class` | `Directory.IndexInputSlicer` Allows to create one or more sliced `IndexInput` instances from a single file handle.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `isOpen`
    `protected LockFactory` | `lockFactory` Holds the LockFactory instance (implements locking for this Directory instance).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Directory()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearLock(String name)` Attempt to clear (forcefully unlock and remove) the specified lock.
    `abstract void` | `close()` Closes the store.
    `void` | `copy(Directory to, String src, String dest, IOContext context)` Copies the file src to `Directory` to 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.
    `Directory.IndexInputSlicer` | `createSlicer(String name, IOContext context)` Creates an `Directory.IndexInputSlicer` for the given file name.
    `abstract void` | `deleteFile(String name)` Removes an existing file in the directory.
    `protected void` | `ensureOpen()`
    `abstract boolean` | `fileExists(String name)` Returns true iff a file with the given name exists.
    `abstract long` | `fileLength(String name)` Returns the length of a file in the directory.
    `LockFactory` | `getLockFactory()` Get the LockFactory that this Directory instance is using for its locking implementation.
    `String` | `getLockID()` Return a string identifier that uniquely differentiates this Directory instance from other Directory instances.
    `abstract String[]` | `listAll()` Returns an array of strings, one for each file in the directory.
    `Lock` | `makeLock(String name)` Construct a `Lock`.
    `abstract IndexInput` | `openInput(String name, IOContext context)` Returns a stream reading an existing file, with the specified read buffer size.
    `void` | `setLockFactory(LockFactory lockFactory)` Set the LockFactory that this Directory instance should use for its locking implementation.
    `abstract void` | `sync(Collection<String> names)` Ensure that any writes to these files are moved to stable storage.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### isOpen

          protected volatile boolean isOpen

    - #### lockFactory

          protected LockFactory lockFactory

      Holds the LockFactory instance (implements locking for this Directory instance).

  - ### Constructor Detail

    - #### Directory

          public Directory()

  - ### Method Detail

    - #### listAll

          public abstract String[] listAll()
                                    throws IOException

      Returns an array of strings, one for each file in the directory.
      Throws:
        `NoSuchDirectoryException` - if the directory is not prepared for any write operations (such as `createOutput(String, IOContext)`).
        `IOException` - in case of other IO errors

    - #### fileExists

          public abstract boolean fileExists(String name)
                                      throws IOException

      Returns true iff a file with the given name exists.
      Throws:
        `IOException`

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

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

    - #### openInput

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

      Returns a stream reading an existing file, with the specified read buffer size. The particular Directory implementation may ignore the buffer size. Currently the only Directory implementations that respect this parameter are `FSDirectory` and `CompoundFileDirectory`.
      Throws:
        `IOException`

    - #### makeLock

          public Lock makeLock(String name)

      Construct a `Lock`.
      Parameters:
        `name` - the name of the lock file

    - #### clearLock

          public void clearLock(String name)
                         throws IOException

      Attempt to clear (forcefully unlock and remove) the specified lock. Only call this at a time when you are certain this lock is no longer in use.
      Parameters:
        `name` - name of the lock to be cleared.
      Throws:
        `IOException`

    - #### close

          public abstract void close()
                              throws IOException

      Closes the store.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `IOException`

    - #### setLockFactory

          public void setLockFactory(LockFactory lockFactory)
                              throws IOException

      Set the LockFactory that this Directory instance should use for its locking implementation. Each * instance of LockFactory should only be used for one directory (ie, do not share a single instance across multiple Directories).
      Parameters:
        `lockFactory` - instance of `LockFactory`.
      Throws:
        `IOException`

    - #### getLockFactory

          public LockFactory getLockFactory()

      Get the LockFactory that this Directory instance is using for its locking implementation. Note that this may be null for Directory implementations that provide their own locking implementation.

    - #### getLockID

          public String getLockID()

      Return a string identifier that uniquely differentiates this Directory instance from other Directory instances. This ID should be the same if two Directory instances (even in different JVMs and/or on different machines) are considered "the same index". This is how locking "scopes" to the right index.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### copy

          public void copy(Directory to,
                  String src,
                  String dest,
                  IOContext context)
                    throws IOException

      Copies the file src to `Directory` to 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()) {
             dir.copy(to, file, newFile); // 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`

    - #### createSlicer

          public Directory.IndexInputSlicer createSlicer(String name,
                                                IOContext context)
                                                  throws IOException

      Creates an `Directory.IndexInputSlicer` for the given file name. IndexInputSlicer allows other `Directory` implementations to efficiently open one or more sliced `IndexInput` instances from a single file handle. The underlying file handle is kept open until the `Directory.IndexInputSlicer` is closed.
      Throws:
        `IOException` - if an `IOException` occurs
      WARNING: This API is experimental and might change in incompatible ways in the next release.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### ensureOpen

          protected final void ensureOpen()
                                   throws AlreadyClosedException

      Throws:
        `AlreadyClosedException` - if this Directory is closed

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