Directory (Lucene 3.6.2 API)
Keywords: org.apache.lucene.store.Directory class

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.lucene.store
Class Directory

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

All Implemented Interfaces:
  Closeable

Direct Known Subclasses:
  FileSwitchDirectory, FSDirectory, MockDirectoryWrapper, NRTCachingDirectory, RAMDirectory

    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)`.

Field Summary
`protected boolean` | `isOpen`
`protected LockFactory` | `lockFactory` Holds the LockFactory instance (implements locking for this Directory instance).

Constructor Summary
`Directory()`

Method Summary
`void` | `clearLock(String name)` Attempt to clear (forcefully unlock and remove) the specified lock.
`abstract void` | `close()` Closes the store.
`static void` | `copy(Directory src, Directory dest, boolean closeDirSrc)` Deprecated. should be replaced with calls to `copy(Directory, String, String)` for every file that needs copying. You can use the following code:
     IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
     for (String file : src.listAll()) {
       if (filter.accept(null, file)) {
         src.copy(dest, file, file);
       }
     }
`void` | `copy(Directory to, String src, String dest)` Copies the file src to `Directory` to under the new file name dest.
`abstract IndexOutput` | `createOutput(String name)` Creates a new, empty file in the directory with the given 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.
`abstract long` | `fileModified(String name)` Deprecated.
`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)` Returns a stream reading an existing file.
`IndexInput` | `openInput(String name, int bufferSize)` 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.
`void` | `sync(Collection<String> names)` Ensure that any writes to these files are moved to stable storage.
`void` | `sync(String name)` Deprecated. use `sync(Collection)` instead. For easy migration you can change your code to call sync(Collections.singleton(name))
`String` | `toString()`
`abstract void` | `touchFile(String name)` Deprecated. Lucene never uses this API; it will be removed in 4.0.

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)`).
    `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`

### fileModified

    @Deprecated
    public abstract long fileModified(String name)
                               throws IOException

  Deprecated.

  Returns the time the named file was last modified.

  Throws:
    `IOException`

### touchFile

    @Deprecated
    public abstract void touchFile(String name)
                            throws IOException

  Deprecated. Lucene never uses this API; it will be removed in 4.0.

  Set the modified time of an existing file to now.

  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)
                                      throws IOException

  Creates a new, empty file in the directory with the given name. Returns a stream writing this file.

  Throws:
    `IOException`

### sync

    @Deprecated
    public void sync(String name)
              throws IOException

  Deprecated. use `sync(Collection)` instead. For easy migration you can change your code to call sync(Collections.singleton(name))

  Ensure that any writes to this file 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.

  Throws:
    `IOException`

### sync

    public 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)
                                  throws IOException

  Returns a stream reading an existing file.

  Throws:
    `IOException`

### openInput

    public IndexInput openInput(String name,
                                int bufferSize)
                         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 `CompoundFileReader`.

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

### copy

    @Deprecated
    public static void copy(Directory src,
                                       Directory dest,
                                       boolean closeDirSrc)
                     throws IOException

  Deprecated. should be replaced with calls to `copy(Directory, String, String)` for every file that needs copying. You can use the following code:

       IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
       for (String file : src.listAll()) {
         if (filter.accept(null, file)) {
           src.copy(dest, file, file);
         }
       }

  Copy contents of a directory src to a directory dest. If a file in src already exists in dest then the one in dest will be blindly overwritten.

  NOTE: the source directory cannot change while this method is running. Otherwise the results are undefined and you could easily hit a FileNotFoundException.

  NOTE: this method only copies files that look like index files (ie, have extensions matching the known extensions of index files).

  Parameters:
    `src` - source directory
    `dest` - destination directory
    `closeDirSrc` - if `true`, call `close()` method on source directory
  Throws:
    `IOException`

### ensureOpen

    protected final void ensureOpen()
                             throws AlreadyClosedException

  Throws:
    `AlreadyClosedException` - if this Directory is closed

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD