org.apache.lucene.codecs

## Class DocValuesFormat

- java.lang.Object
- - org.apache.lucene.codecs.DocValuesFormat

- All Implemented Interfaces:
    NamedSPILoader.NamedSPI
  Direct Known Subclasses:
    Lucene40DocValuesFormat, Lucene42DocValuesFormat, PerFieldDocValuesFormat

      public abstract class DocValuesFormat
      extends Object
      implements NamedSPILoader.NamedSPI

  Encodes/decodes per-document values.

  Note, when extending this class, the name (`getName()`) may written into the index in certain configurations. In order for the segment to be read, the name must resolve to your implementation via `forName(String)`. This method uses Java's `Service Provider Interface` (SPI) to resolve format names.

  If you implement your own format, make sure that it has a no-arg constructor so SPI can load it.

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

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DocValuesFormat(String name)` Creates a new docvalues format.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Set<String>` | `availableDocValuesFormats()` returns a list of all available format names
    `abstract DocValuesConsumer` | `fieldsConsumer(SegmentWriteState state)` Returns a `DocValuesConsumer` to write docvalues to the index.
    `abstract DocValuesProducer` | `fieldsProducer(SegmentReadState state)` Returns a `DocValuesProducer` to read docvalues from the index.
    `static DocValuesFormat` | `forName(String name)` looks up a format by name
    `String` | `getName()`
    `static void` | `reloadDocValuesFormats(ClassLoader classloader)` Reloads the DocValues format list from the given `ClassLoader`.
    `String` | `toString()`

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

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

- - ### Constructor Detail

    - #### DocValuesFormat

          protected DocValuesFormat(String name)

      Creates a new docvalues format.

      The provided name will be written into the index segment in some configurations (such as when using `PerFieldDocValuesFormat`): in such configurations, for the segment to be read this class should be registered with Java's SPI mechanism (registered in META-INF/ of your jar file, etc).

      Parameters:
        `name` - must be all ascii alphanumeric, and less than 128 characters in length.

  - ### Method Detail

    - #### fieldsConsumer

          public abstract DocValuesConsumer fieldsConsumer(SegmentWriteState state)
                                                    throws IOException

      Returns a `DocValuesConsumer` to write docvalues to the index.
      Throws:
        `IOException`

    - #### fieldsProducer

          public abstract DocValuesProducer fieldsProducer(SegmentReadState state)
                                                    throws IOException

      Returns a `DocValuesProducer` to read docvalues from the index.

      NOTE: by the time this call returns, it must hold open any files it will need to use; else, those files may be deleted. Additionally, required files may be deleted during the execution of this call before there is a chance to open them. Under these circumstances an IOException should be thrown by the implementation. IOExceptions are expected and will automatically cause a retry of the segment opening logic with the newly revised segments.

      Throws:
        `IOException`

    - #### getName

          public final String getName()

      Specified by:
        `getName` in interface `NamedSPILoader.NamedSPI`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### forName

          public static DocValuesFormat forName(String name)

      looks up a format by name

    - #### availableDocValuesFormats

          public static Set<String> availableDocValuesFormats()

      returns a list of all available format names

    - #### reloadDocValuesFormats

          public static void reloadDocValuesFormats(ClassLoader classloader)

      Reloads the DocValues format list from the given `ClassLoader`. Changes to the docvalues formats are visible after the method ends, all iterators (`availableDocValuesFormats()`,...) stay consistent.

      NOTE: Only new docvalues formats are added, existing ones are never removed or replaced.

      This method is expensive and should only be called for discovery of new docvalues formats on the given classpath/classloader!

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