org.apache.lucene.store

## Class NRTCachingDirectory

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

- All Implemented Interfaces:
    Closeable, AutoCloseable, Accountable

      public class NRTCachingDirectory
      extends FilterDirectory
      implements Accountable

  Wraps a `RAMDirectory` around any provided delegate directory, to be used during NRT search.

  This class is likely only useful in a near-real-time context, where indexing rate is lowish but reopen rate is highish, resulting in many tiny files being written. This directory keeps such segments (as well as the segments produced by merging them, as long as they are small enough), in RAM.

  This is safe to use: when your app calls {IndexWriter#commit}, all cached files will be flushed from the cached and sync'd.

  Here's a simple example usage:

         Directory fsDir = FSDirectory.open(new File("/path/to/index").toPath());
         NRTCachingDirectory cachedFSDir = new NRTCachingDirectory(fsDir, 5.0, 60.0);
         IndexWriterConfig conf = new IndexWriterConfig(analyzer);
         IndexWriter writer = new IndexWriter(cachedFSDir, conf);

  This will cache all newly flushed segments, all merges whose expected segment size is `<= 5 MB`, unless the net cached bytes exceeds 60 MB at which point all writes will not be cached (until the net bytes falls below 60 MB).

  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.store.FilterDirectory

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NRTCachingDirectory(Directory delegate, double maxMergeSizeMB, double maxCachedMB)` We will cache a newly created output if 1) it's a flush or a merge and the estimated size of the merged segment is `<= maxMergeSizeMB`, and 2) the total cached bytes is `<= maxCachedMB`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close this directory, which flushes any cached files to the delegate and then closes the delegate.
    `IndexOutput` | `createOutput(String name, IOContext context)` Creates a new, empty file in the directory with the given name.
    `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`.
    `void` | `deleteFile(String name)` Removes an existing file in the directory.
    `protected boolean` | `doCacheWrite(String name, IOContext context)` Subclass can override this to customize logic; return true if this file should be written to the RAMDirectory.
    `long` | `fileLength(String name)` Returns the length of a file in the directory.
    `Collection<Accountable>` | `getChildResources()` Returns nested resources of this class.
    `String[]` | `listAll()` Returns an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.
    `String[]` | `listCachedFiles()`
    `IndexInput` | `openInput(String name, IOContext context)` Returns a stream reading an existing file.
    `long` | `ramBytesUsed()` Return the memory usage of this object in bytes.
    `void` | `rename(String source, String dest)` Renames `source` to `dest` as an atomic operation, where `dest` does not yet exist in the directory.
    `void` | `sync(Collection<String> fileNames)` Ensure that any writes to these files are moved to stable storage.
    `String` | `toString()`

    - ### Methods inherited from class org.apache.lucene.store.FilterDirectory

      `getDelegate, obtainLock, syncMetaData, unwrap`

    - ### Methods inherited from class org.apache.lucene.store.Directory

      `copyFrom, ensureOpen, openChecksumInput, renameFile`

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

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

- - ### Constructor Detail

    - #### NRTCachingDirectory

          public NRTCachingDirectory(Directory delegate,
                                     double maxMergeSizeMB,
                                     double maxCachedMB)

      We will cache a newly created output if 1) it's a flush or a merge and the estimated size of the merged segment is `<= maxMergeSizeMB`, and 2) the total cached bytes is `<= maxCachedMB`

  - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `FilterDirectory`

    - #### listAll

          public String[] listAll()
                           throws IOException

      Description copied from class: `Directory`
      Returns an array of strings, one for each entry in the directory, in sorted (UTF16, java's String.compare) order.
      Overrides:
        `listAll` in class `FilterDirectory`
      Throws:
        `IOException` - in case of IO error

    - #### deleteFile

          public void deleteFile(String name)
                          throws IOException

      Description copied from class: `Directory`
      Removes an existing file in the directory.
      Overrides:
        `deleteFile` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### fileLength

          public long fileLength(String name)
                          throws IOException

      Description copied from class: `Directory`
      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.
      Overrides:
        `fileLength` in class `FilterDirectory`
      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.

    - #### listCachedFiles

          public String[] listCachedFiles()

    - #### createOutput

          public IndexOutput createOutput(String name,
                                          IOContext context)
                                   throws IOException

      Description copied from class: `Directory`
      Creates a new, empty file in the directory with the given name. Returns a stream writing this file.
      Overrides:
        `createOutput` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### sync

          public void sync(Collection<String> fileNames)
                    throws IOException

      Description copied from class: `Directory`
      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.
      Overrides:
        `sync` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### rename

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

      Description copied from class: `Directory`
      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.

      Overrides:
        `rename` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### openInput

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

      Description copied from class: `Directory`
      Returns a stream reading an existing file.

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

      Overrides:
        `openInput` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Close this directory, which flushes any cached files to the delegate and then closes the delegate.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Overrides:
        `close` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### doCacheWrite

          protected boolean doCacheWrite(String name,
                                         IOContext context)

      Subclass can override this to customize logic; return true if this file should be written to the RAMDirectory.

    - #### createTempOutput

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

      Description copied from class: `Directory`
      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.
      Overrides:
        `createTempOutput` in class `FilterDirectory`
      Throws:
        `IOException`

    - #### ramBytesUsed

          public long ramBytesUsed()

      Description copied from interface: `Accountable`
      Return the memory usage of this object in bytes. Negative values are illegal.
      Specified by:
        `ramBytesUsed` in interface `Accountable`

    - #### getChildResources

          public Collection<Accountable> getChildResources()

      Description copied from interface: `Accountable`
      Returns nested resources of this class. The result should be a point-in-time snapshot (to avoid race conditions).
      Specified by:
        `getChildResources` in interface `Accountable`
      See Also:
        `Accountables`

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