## org.apache.lucene.index
Class SegmentInfos

    java.lang.Object
      org.apache.lucene.index.SegmentInfos

All Implemented Interfaces:
  Cloneable, Iterable<SegmentInfoPerCommit>

    public final class SegmentInfos

extends Object
implements Cloneable, Iterable<SegmentInfoPerCommit>

A collection of segmentInfo objects with methods for operating on those segments in relation to the file system.

The active segments in the index are stored in the segment info file, `segments_N`. There may be one or more `segments_N` files in the index; however, the one with the largest generation is the active one (when older segments_N files are present it's because they temporarily cannot be deleted, or, a writer is in the process of committing, or a custom `IndexDeletionPolicy` is in use). This file lists each segment by name and has details about the codec and generation of deletes.

There is also a file `segments.gen`. This file contains the current generation (the `_N` in `segments_N`) of the index. This is used only as a fallback in case the current generation cannot be accurately determined by directory listing alone (as is the case for some NFS clients with time-based directory cache expiration). This file simply contains an `Int32` version header (`FORMAT_SEGMENTS_GEN_CURRENT`), followed by the generation recorded as `Int64`, written twice.

Files:

- `segments.gen`: GenHeader, Generation, Generation
- `segments_N`: Header, Version, NameCounter, SegCount, <SegName, SegCodec, DelGen, DeletionCount>SegCount, CommitUserData, Checksum

Data types:

- Header --> `CodecHeader`
- GenHeader, NameCounter, SegCount, DeletionCount --> `Int32`
- Generation, Version, DelGen, Checksum --> `Int64`
- SegName, SegCodec --> `String`
- CommitUserData --> `Map<String,String>`

Field Descriptions:

- Version counts how often the index has been changed by adding or deleting documents.
- NameCounter is used to generate names for new segment files.
- SegName is the name of the segment, and is used as the file name prefix for all of the files that compose the segment's index.
- DelGen is the generation count of the deletes file. If this is -1, there are no deletes. Anything above zero means there are deletes stored by `LiveDocsFormat`.
- DeletionCount records the number of deleted documents in this segment.
- Checksum contains the CRC32 checksum of all bytes in the segments_N file up until the checksum. This is used to verify integrity of the file on opening the index.
- SegCodec is the `name` of the Codec that encoded this segment.
- CommitUserData stores an optional user-supplied opaque Map<String,String> that was passed to `IndexWriter.setCommitData(java.util.Map)`.

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

Nested Class Summary
`static class` `SegmentInfos.FindSegmentsFile` Utility class for executing code that needs to do something with the current segments file.

Field Summary
`int` `counter` Used to name new segments.
`static int` `FORMAT_SEGMENTS_GEN_CURRENT` Used for the segments.gen file only! Whenever you add a new format, make it 1 smaller (negative version logic)!
`Map<String,String>` `userData` Opaque Map<String, String> that user can specify during IndexWriter.commit
`long` `version` Counts how often the index has been changed.
`static int` `VERSION_40` The file format version for the segments_N codec header

Constructor Summary
`SegmentInfos()` Sole constructor.

Method Summary
`void` `add(SegmentInfoPerCommit si)` Appends the provided `SegmentInfoPerCommit`.
`void` `addAll(Iterable<SegmentInfoPerCommit> sis)` Appends the provided `SegmentInfoPerCommit`s.
`List<SegmentInfoPerCommit>` `asList()` Returns all contained segments as an unmodifiable `List` view.
`void` `changed()` Call this before committing if changes have been made to the segments.
`void` `clear()` Clear all `SegmentInfoPerCommit`s.
`SegmentInfos` `clone()` Returns a copy of this instance, also copying each SegmentInfo.
`Collection<String>` `files(Directory dir, boolean includeSegmentsFile)` Returns all file names referenced by SegmentInfo instances matching the provided Directory (ie files associated with any "external" segments are skipped).
`static long` `generationFromSegmentsFileName(String fileName)` Parse the generation off the segments file name and return it.
`static int` `getDefaultGenLookahedCount()` Returns the `defaultGenLookaheadCount`.
`long` `getGeneration()` Returns current generation.
`static PrintStream` `getInfoStream()` Returns `infoStream`.
`static long` `getLastCommitGeneration(Directory directory)` Get the generation of the most recent commit to the index in this directory (N in the segments_N file).
`static long` `getLastCommitGeneration(String[] files)` Get the generation of the most recent commit to the list of index files (N in the segments_N file).
`static String` `getLastCommitSegmentsFileName(Directory directory)` Get the filename of the segments_N file for the most recent commit to the index in this Directory.
`static String` `getLastCommitSegmentsFileName(String[] files)` Get the filename of the segments_N file for the most recent commit in the list of index files.
`long` `getLastGeneration()` Returns last succesfully read or written generation.
`String` `getNextSegmentFileName()` Get the next segments_N filename that will be written.
`String` `getSegmentsFileName()` Get the segments_N filename in use by this segment infos.
`Map<String,String>` `getUserData()` Return `userData` saved with this commit.
`long` `getVersion()` version number when this SegmentInfos was generated.
`SegmentInfoPerCommit` `info(int i)` Returns `SegmentInfoPerCommit` at the provided index.
`Iterator<SegmentInfoPerCommit>` `iterator()` Returns an unmodifiable `Iterator` of contained segments in order.
`void` `read(Directory directory)` Find the latest commit (`segments_N file`) and load all `SegmentInfoPerCommit`s.
`void` `read(Directory directory, String segmentFileName)` Read a particular segmentFileName.
`void` `remove(SegmentInfoPerCommit si)` Remove the provided `SegmentInfoPerCommit`.
`static void` `setDefaultGenLookaheadCount(int count)` Advanced: set how many times to try incrementing the gen when loading the segments file.
`static void` `setInfoStream(PrintStream infoStream)` If non-null, information about retries when loading the segments file will be printed to this.
`int` `size()` Returns number of `SegmentInfoPerCommit`s.
`String` `toString(Directory directory)` Returns readable description of this segment.
`int` `totalDocCount()` Returns sum of all segment's docCounts.
`static String` `write3xInfo(Directory dir, SegmentInfo si, IOContext context)` Deprecated.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### VERSION_40

    public static final int VERSION_40

  The file format version for the segments_N codec header

  See Also:
    Constant Field Values

### FORMAT_SEGMENTS_GEN_CURRENT

    public static final int FORMAT_SEGMENTS_GEN_CURRENT

  Used for the segments.gen file only! Whenever you add a new format, make it 1 smaller (negative version logic)!

  See Also:
    Constant Field Values

### counter

    public int counter

  Used to name new segments.

### version

    public long version

  Counts how often the index has been changed.

### userData

    public Map<String,String> userData

  Opaque Map<String, String> that user can specify during IndexWriter.commit

Constructor Detail

### SegmentInfos

    public SegmentInfos()

  Sole constructor. Typically you call this and then use `or #read(Directory,String)` to populate each `SegmentInfoPerCommit`. Alternatively, you can add/remove your own `SegmentInfoPerCommit`s.

Method Detail

### info

    public SegmentInfoPerCommit info(int i)

  Returns `SegmentInfoPerCommit` at the provided index.

### getLastCommitGeneration

    public static long getLastCommitGeneration(String[] files)

  Get the generation of the most recent commit to the list of index files (N in the segments_N file).

  Parameters:
    `files` - -- array of file names to check

### getLastCommitGeneration

    public static long getLastCommitGeneration(Directory directory)
                                        throws IOException

  Get the generation of the most recent commit to the index in this directory (N in the segments_N file).

  Parameters:
    `directory` - -- directory to search for the latest segments_N file
  Throws:
    `IOException`

### getLastCommitSegmentsFileName

    public static String getLastCommitSegmentsFileName(String[] files)

  Get the filename of the segments_N file for the most recent commit in the list of index files.

  Parameters:
    `files` - -- array of file names to check

### getLastCommitSegmentsFileName

    public static String getLastCommitSegmentsFileName(Directory directory)
                                                throws IOException

  Get the filename of the segments_N file for the most recent commit to the index in this Directory.

  Parameters:
    `directory` - -- directory to search for the latest segments_N file
  Throws:
    `IOException`

### getSegmentsFileName

    public String getSegmentsFileName()

  Get the segments_N filename in use by this segment infos.

### generationFromSegmentsFileName

    public static long generationFromSegmentsFileName(String fileName)

  Parse the generation off the segments file name and return it.

### getNextSegmentFileName

    public String getNextSegmentFileName()

  Get the next segments_N filename that will be written.

### read

    public final void read(Directory directory,
                           String segmentFileName)
                    throws IOException

  Read a particular segmentFileName. Note that this may throw an IOException if a commit is in process.

  Parameters:
    `directory` - -- directory containing the segments file
    `segmentFileName` - -- segment file to load
  Throws:
    `CorruptIndexException` - if the index is corrupt
    `IOException` - if there is a low-level IO error

### read

    public final void read(Directory directory)
                    throws IOException

  Find the latest commit (`segments_N file`) and load all `SegmentInfoPerCommit`s.

  Throws:
    `IOException`

### write3xInfo

    @Deprecated
    public static String write3xInfo(Directory dir,
                                                SegmentInfo si,
                                                IOContext context)
                              throws IOException

  Deprecated.

  Throws:
    `IOException`

### clone

    public SegmentInfos clone()

  Returns a copy of this instance, also copying each SegmentInfo.

  Overrides:
    `clone` in class `Object`

### getVersion

    public long getVersion()

  version number when this SegmentInfos was generated.

### getGeneration

    public long getGeneration()

  Returns current generation.

### getLastGeneration

    public long getLastGeneration()

  Returns last succesfully read or written generation.

### setInfoStream

    public static void setInfoStream(PrintStream infoStream)

  If non-null, information about retries when loading the segments file will be printed to this.

### setDefaultGenLookaheadCount

    public static void setDefaultGenLookaheadCount(int count)

  Advanced: set how many times to try incrementing the gen when loading the segments file. This only runs if the primary (listing directory) and secondary (opening segments.gen file) methods fail to find the segments file.

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

### getDefaultGenLookahedCount

    public static int getDefaultGenLookahedCount()

  Returns the `defaultGenLookaheadCount`.

  See Also:
    `setDefaultGenLookaheadCount(int)`
  WARNING: This API is experimental and might change in incompatible ways in the next release.

### getInfoStream

    public static PrintStream getInfoStream()

  Returns `infoStream`.

  See Also:
    `setInfoStream(java.io.PrintStream)`

### files

    public Collection<String> files(Directory dir,
                                    boolean includeSegmentsFile)
                             throws IOException

  Returns all file names referenced by SegmentInfo instances matching the provided Directory (ie files associated with any "external" segments are skipped). The returned collection is recomputed on each invocation.

  Throws:
    `IOException`

### toString

    public String toString(Directory directory)

  Returns readable description of this segment.

### getUserData

    public Map<String,String> getUserData()

  Return `userData` saved with this commit.

  See Also:
    `IndexWriter.commit()`

### totalDocCount

    public int totalDocCount()

  Returns sum of all segment's docCounts. Note that this does not include deletions

### changed

    public void changed()

  Call this before committing if changes have been made to the segments.

### iterator

    public Iterator<SegmentInfoPerCommit> iterator()

  Returns an unmodifiable `Iterator` of contained segments in order.

  Specified by:
    `iterator` in interface `Iterable<SegmentInfoPerCommit>`

### asList

    public List<SegmentInfoPerCommit> asList()

  Returns all contained segments as an unmodifiable `List` view.

### size

    public int size()

  Returns number of `SegmentInfoPerCommit`s.

### add

    public void add(SegmentInfoPerCommit si)

  Appends the provided `SegmentInfoPerCommit`.

### addAll

    public void addAll(Iterable<SegmentInfoPerCommit> sis)

  Appends the provided `SegmentInfoPerCommit`s.

### clear

    public void clear()

  Clear all `SegmentInfoPerCommit`s.

### remove

    public void remove(SegmentInfoPerCommit si)

  Remove the provided `SegmentInfoPerCommit`.

  WARNING: O(N) cost

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