Package org.apache.cayenne.access

## Class IncrementalFaultList<E>

- java.lang.Object
- - org.apache.cayenne.access.IncrementalFaultList<E>

- All Implemented Interfaces:
    `Serializable`, `Iterable<E>`, `Collection<E>`, `List<E>`

      public class IncrementalFaultList<E>
      extends Object
      implements List<E>, Serializable

  A synchronized list that serves as a container of DataObjects. It is returned when a paged query is performed by DataContext. On creation, only the first "page" is fully resolved, for the rest of the objects only their ObjectIds are read. Pages following the first page are resolved on demand only. On access to an element, the list would ensure that this element as well as all its siblings on the same page are fully resolved.

  The list can hold DataRows or DataObjects. Attempts to add any other object types will result in an exception.

  Performance note: certain operations like `toArray` would trigger full list fetch.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected DataContext` | `dataContext` |
    `protected List` | `elements` |
    `protected int` | `idWidth` | Stores a hint allowing to distinguish data rows from unfetched ids when the query fetches data rows.
    `protected int` | `maxFetchSize` | Defines the upper limit on the size of fetches.
    `protected QueryMetadata` | `metadata` |
    `protected int` | `pageSize` |
    `protected ObjEntity` | `rootEntity` |
    `protected int` | `unfetchedObjects` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `IncrementalFaultList​(DataContext dataContext, Query query, int maxFetchSize)` | Creates a new IncrementalFaultList using a given DataContext and query.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(int index, Object element)` |
    `boolean` | `add​(Object o)` |
    `boolean` | `addAll​(int index, Collection<? extends E> c)` |
    `boolean` | `addAll​(Collection<? extends E> c)` |
    `void` | `clear()` |
    `boolean` | `contains​(Object o)` |
    `boolean` | `containsAll​(Collection<?> c)` |
    `protected void` | `fillIn​(Query query, List<Object> elementsList)` | Performs initialization of the list of objects.
    `E` | `get​(int index)` |
    `DataContext` | `getDataContext()` | Returns the dataContext.
    `int` | `getMaxFetchSize()` | Get the upper bound on the number of records to resolve in one round trip to the database.
    `int` | `getPageSize()` | Returns the pageSize.
    `int` | `getUnfetchedObjects()` | Returns a total number of objects that are not resolved yet.
    `int` | `indexOf​(Object o)` |
    `boolean` | `isEmpty()` |
    `Iterator<E>` | `iterator()` | Return an iterator for this list.
    `int` | `lastIndexOf​(Object o)` |
    `ListIterator<E>` | `listIterator()` | Returns a list iterator for this list.
    `ListIterator<E>` | `listIterator​(int index)` | Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list.
    `int` | `pageIndex​(int elementIndex)` | Returns zero-based index of the virtual "page" for a given array element index.
    `E` | `remove​(int index)` |
    `boolean` | `remove​(Object o)` |
    `boolean` | `removeAll​(Collection<?> c)` |
    `void` | `resolveAll()` | Will resolve all unread objects.
    `protected void` | `resolveInterval​(int fromIndex, int toIndex)` | Resolves a sublist of objects starting at `fromIndex` up to but not including `toIndex`.
    `boolean` | `retainAll​(Collection<?> c)` |
    `E` | `set​(int index, Object element)` |
    `void` | `setMaxFetchSize​(int fetchSize)` |
    `int` | `size()` |
    `List<E>` | `subList​(int fromIndex, int toIndex)` |
    `Object[]` | `toArray()` |
    `<T> T[]` | `toArray​(T[] a)` |

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

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

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, removeIf, stream, toArray`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

    - ### Methods inherited from interface java.util.List

      `equals, hashCode, replaceAll, sort, spliterator`

- - ### Field Detail

    - #### pageSize

          protected int pageSize

    - #### elements

          protected final List elements

    - #### dataContext

          protected DataContext dataContext

    - #### rootEntity

          protected ObjEntity rootEntity

    - #### unfetchedObjects

          protected int unfetchedObjects

    - #### idWidth

          protected int idWidth

      Stores a hint allowing to distinguish data rows from unfetched ids when the query fetches data rows.

    - #### metadata

          protected QueryMetadata metadata

    - #### maxFetchSize

          protected int maxFetchSize

      Defines the upper limit on the size of fetches. This is needed to avoid where clause size limitations.

  - ### Constructor Detail

    - #### IncrementalFaultList

          public IncrementalFaultList​(DataContext dataContext,
                                      Query query,
                                      int maxFetchSize)

      Creates a new IncrementalFaultList using a given DataContext and query.
      Parameters:
        `dataContext` - DataContext used by IncrementalFaultList to fill itself with objects.
        `query` - Main query used to retrieve data. Must have "pageSize" property set to a value greater than zero.
        `maxFetchSize` - maximum number of fetches in one query

  - ### Method Detail

    - #### fillIn

          protected void fillIn​(Query query,
                                List<Object> elementsList)

      Performs initialization of the list of objects. Only the first page is fully resolved. For the rest of the list, only ObjectIds are read.
      Since:
        3.0

    - #### resolveAll

          public void resolveAll()

      Will resolve all unread objects.

    - #### resolveInterval

          protected void resolveInterval​(int fromIndex,
                                         int toIndex)

      Resolves a sublist of objects starting at `fromIndex` up to but not including `toIndex`. Internally performs bound checking and trims indexes accordingly.

    - #### pageIndex

          public int pageIndex​(int elementIndex)

      Returns zero-based index of the virtual "page" for a given array element index.

    - #### getMaxFetchSize

          public int getMaxFetchSize()

      Get the upper bound on the number of records to resolve in one round trip to the database. This setting governs the size/complexity of the where clause generated to retrieve the next page of records. If the fetch size is less than the page size, then multiple fetches will be made to resolve a page.

    - #### setMaxFetchSize

          public void setMaxFetchSize​(int fetchSize)

    - #### getDataContext

          public DataContext getDataContext()

      Returns the dataContext.
      Returns:
        DataContext

    - #### getPageSize

          public int getPageSize()

      Returns the pageSize.
      Returns:
        int

    - #### listIterator

          public ListIterator<E> listIterator()

      Returns a list iterator for this list. DataObjects are resolved a page (according to getPageSize()) at a time as necessary - when retrieved with next() or previous().
      Specified by:
        `listIterator` in interface `List<E>`

    - #### listIterator

          public ListIterator<E> listIterator​(int index)

      Returns a list iterator of the elements in this list (in proper sequence), starting at the specified position in this list. The specified index indicates the first element that would be returned by an initial call to the next method. An initial call to the previous method would return the element with the specified index minus one. DataObjects are resolved a page at a time (according to getPageSize()) as necessary - when retrieved with next() or previous().
      Specified by:
        `listIterator` in interface `List<E>`

    - #### iterator

          public Iterator<E> iterator()

      Return an iterator for this list. DataObjects are resolved a page (according to getPageSize()) at a time as necessary - when retrieved with next().
      Specified by:
        `iterator` in interface `Collection<E>`
      Specified by:
        `iterator` in interface `Iterable<E>`
      Specified by:
        `iterator` in interface `List<E>`

    - #### add

          public void add​(int index,
                          Object element)

      Specified by:
        `add` in interface `List<E>`
      See Also:
        `List.add(int, Object)`

    - #### add

          public boolean add​(Object o)

      Specified by:
        `add` in interface `Collection<E>`
      Specified by:
        `add` in interface `List<E>`
      See Also:
        `Collection.add(Object)`

    - #### addAll

          public boolean addAll​(Collection<? extends E> c)

      Specified by:
        `addAll` in interface `Collection<E>`
      Specified by:
        `addAll` in interface `List<E>`
      See Also:
        `Collection.addAll(Collection)`

    - #### addAll

          public boolean addAll​(int index,
                                Collection<? extends E> c)

      Specified by:
        `addAll` in interface `List<E>`
      See Also:
        `List.addAll(int, Collection)`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `Collection<E>`
      Specified by:
        `clear` in interface `List<E>`
      See Also:
        `Collection.clear()`

    - #### contains

          public boolean contains​(Object o)

      Specified by:
        `contains` in interface `Collection<E>`
      Specified by:
        `contains` in interface `List<E>`
      See Also:
        `Collection.contains(Object)`

    - #### containsAll

          public boolean containsAll​(Collection<?> c)

      Specified by:
        `containsAll` in interface `Collection<E>`
      Specified by:
        `containsAll` in interface `List<E>`
      See Also:
        `Collection.containsAll(Collection)`

    - #### get

          public E get​(int index)

      Specified by:
        `get` in interface `List<E>`

    - #### indexOf

          public int indexOf​(Object o)

      Specified by:
        `indexOf` in interface `List<E>`
      See Also:
        `List.indexOf(Object)`

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `Collection<E>`
      Specified by:
        `isEmpty` in interface `List<E>`
      See Also:
        `Collection.isEmpty()`

    - #### lastIndexOf

          public int lastIndexOf​(Object o)

      Specified by:
        `lastIndexOf` in interface `List<E>`

    - #### remove

          public E remove​(int index)

      Specified by:
        `remove` in interface `List<E>`

    - #### remove

          public boolean remove​(Object o)

      Specified by:
        `remove` in interface `Collection<E>`
      Specified by:
        `remove` in interface `List<E>`

    - #### removeAll

          public boolean removeAll​(Collection<?> c)

      Specified by:
        `removeAll` in interface `Collection<E>`
      Specified by:
        `removeAll` in interface `List<E>`

    - #### retainAll

          public boolean retainAll​(Collection<?> c)

      Specified by:
        `retainAll` in interface `Collection<E>`
      Specified by:
        `retainAll` in interface `List<E>`

    - #### set

          public E set​(int index,
                       Object element)

      Specified by:
        `set` in interface `List<E>`
      See Also:
        `List.set(int, Object)`

    - #### size

          public int size()

      Specified by:
        `size` in interface `Collection<E>`
      Specified by:
        `size` in interface `List<E>`
      See Also:
        `Collection.size()`

    - #### subList

          public List<E> subList​(int fromIndex,
                                 int toIndex)

      Specified by:
        `subList` in interface `List<E>`

    - #### toArray

          public Object[] toArray()

      Specified by:
        `toArray` in interface `Collection<E>`
      Specified by:
        `toArray` in interface `List<E>`

    - #### toArray

          public <T> T[] toArray​(T[] a)

      Specified by:
        `toArray` in interface `Collection<E>`
      Specified by:
        `toArray` in interface `List<E>`

    - #### getUnfetchedObjects

          public int getUnfetchedObjects()

      Returns a total number of objects that are not resolved yet.