org.apache.uima.cas.impl

## Class FSIndexFlat<T extends FeatureStructure>

- java.lang.Object
- - org.apache.uima.cas.impl.FSIndexFlat<T>

-     public class FSIndexFlat<T extends FeatureStructure>
      extends Object

  Flattened indexes built as a speed-up alternative for Sorted indexes. (might someday be extended to bag/ set, but those index iterators don't need to "sort" among subtypes) The flattened version has several performance benefits over the normal sorted iterators - there's no maintenance of the ordering of subtypes (via heapifyUp and heapifyDown methods) - the conversion from the CAS int heap format to the Java cover class instance is done once when the iterator is constructed. Only built for Sorted indexes which have subtypes (needing merging for the total sort ordering) Each FsLeafIndexImpl (one per cas-view, per different index, per type and subtypes of that index definition) has a lazily-created associated instance of this class. It is lazily created because there may in general be 1000's of types/subtypes which are never iterated over. It's created when the iicp cache is created, which is when the first iterator over this cas-view/index/(type or subtype) is created It's only created for sorted indexes The flattened version is "thrown away" if an index update occurs to the type or any of the subtypes included in the iteration, because it's no longer valid. This condition is checked for when the iterator is created, but not checked for afterwards. This means that these iterators are not "fail fast". The build of the flattened version is done only after some amount of normal iterating is done with no intervening index update. This is done by keeping a counter of the number of times the "heapify up" or "heapify down" is called, and comparing it against the total number of things in the index. The counter is reset when an iterator is called for and the code detects that an update has happened to the the type or subtypes, since the last time monitoring was started for updates. The effect of this is to delay creating flattened versions until it's pretty certain that they'll be stable for a while. Threading The flattened version creation is done on the same thread as the iterator causing it. An experimental version was tried which ran these on separate threads, but that created a lot of complex synchronization code, including handling cases where a CAS Reset occurs, but the index flattening thread is still running. Also, much more synchronization / volatile / atomic kinds of operations were required, which can slow down the iterating. Because the CAS is single threaded for updates, but can have multiple threads "reading" it, with this feature, "reading" the CAS using an iterator potentially results in the creation of new flattened indexes. So, the creation activity is locked so only one thread does this, using an AtomicBoolean. Many of normally volatile variables are not marked this way, because their values only need to be approximate. An example is the counters used to determine if it's time to build the flat iterator. These are potentially updated on multiple threads, so should be atomic, etc., but this is not really needed, because the effect of using a locally cached value instead of the real on from another thread is only to somewhat delay the creation point. ConcurrentModificationException is checked for using the isUpdateFreeSinceLastCounterReset method. MoveToFirst/Last/FS doesn't "reset" the CME as is done in other iterators, because this is looking at a flattened snapshot.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FSIndexFlat.FSIteratorFlat<TI extends FeatureStructure>`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `enabled`
    `static int` | `THRESHOLD_FOR_FLATTENING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FSIndexFlat(org.apache.uima.cas.impl.FSIndexRepositoryImpl.IndexIteratorCachePair<T> iicp)` Constructor

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `FSIterator<T>` | `iterator()` This iterator either returns an iterator over the flattened index, or null.
    `FSIndexFlat.FSIteratorFlat<T>` | `iterator(FeatureStructure fs)` As of July 2015, flattened indexes are disabled - too little benefit, too many edge cases: edge cases to handle: going from non-JCas -> JCas requires existing flat indexes to be invalidated edge case: entering a PEAR, may require different impl of flattened indexes while in the PEAR, plus restoration of previous versions upon PEAR exit This iterator either returns an iterator over the flattened index, or null.

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

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

- - ### Field Detail

    - #### enabled

          public static final boolean enabled

      See Also:
        Constant Field Values

    - #### THRESHOLD_FOR_FLATTENING

          public static final int THRESHOLD_FOR_FLATTENING

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### FSIndexFlat

          public FSIndexFlat(org.apache.uima.cas.impl.FSIndexRepositoryImpl.IndexIteratorCachePair<T> iicp)

      Constructor
      Parameters:
        `iicp` - the sorted index for a type being cached

  - ### Method Detail

    - #### iterator

          public FSIterator<T> iterator()

      This iterator either returns an iterator over the flattened index, or null. positioned at the first element (if non empty).
      Returns:
        the iterator

    - #### iterator

          public FSIndexFlat.FSIteratorFlat<T> iterator(FeatureStructure fs)

      As of July 2015, flattened indexes are disabled - too little benefit, too many edge cases: edge cases to handle: going from non-JCas -> JCas requires existing flat indexes to be invalidated edge case: entering a PEAR, may require different impl of flattened indexes while in the PEAR, plus restoration of previous versions upon PEAR exit This iterator either returns an iterator over the flattened index, or null. As a side effect, if there is no flattened index, check the counts and if there's enough, kick off a subtask to create the flattened one.
      Parameters:
        `fs` - the feature structure to use as a template for setting the initial position of this iterator
      Returns:
        the iterator, or null if there's no flattened iterator (the caller will construct the appropriate iterator)

Copyright © 2006–2021 The Apache Software Foundation. All rights reserved.