org.apache.cayenne.access
Class IncrementalFaultList<E>

java.lang.Object
  extended by org.apache.cayenne.access.IncrementalFaultList<E>
All Implemented Interfaces:
Iterable<E>, Collection<E>, List<E>

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

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.


Field Summary
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  SelectQuery internalQuery
           
protected  int maxFetchSize
          Defines the upper limit on the size of fetches.
protected  int pageSize
           
protected  ObjEntity rootEntity
           
protected  int unfetchedObjects
           
 
Constructor Summary
IncrementalFaultList(DataContext dataContext, Query query)
          Creates a new IncrementalFaultList using a given DataContext and query.
IncrementalFaultList(IncrementalFaultList<E> list)
          Deprecated. since 3.0 - unused
 
Method Summary
 void add(int index, Object element)
           
 boolean add(Object o)
           
 boolean addAll(Collection<? extends E> c)
           
 boolean addAll(int index, Collection<? extends E> c)
           
 void clear()
           
 boolean contains(Object o)
           
 boolean containsAll(Collection<?> c)
           
protected  void fillIn(Query query)
          Deprecated. since 3.0 this method is not called and is deprecated in favor of fillIn(Query, List), as this method performed unneeded synchronization.
protected  void fillIn(Query query, List 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.List
equals, hashCode
 

Field Detail

pageSize

protected int pageSize

elements

protected List elements

dataContext

protected DataContext dataContext

rootEntity

protected ObjEntity rootEntity

internalQuery

protected SelectQuery internalQuery

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.


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(IncrementalFaultList<E> list)
Deprecated. since 3.0 - unused

Creates a new list copying settings from another list. Elements WILL NOT be copied or fetched.


IncrementalFaultList

public IncrementalFaultList(DataContext dataContext,
                            Query query)
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.
Method Detail

fillIn

protected void fillIn(Query query)
Deprecated. since 3.0 this method is not called and is deprecated in favor of fillIn(Query, List), as this method performed unneeded synchronization.

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

Since:
1.0.6

fillIn

protected void fillIn(Query query,
                      List 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.

Returns:
int

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 Iterable<E>
Specified by:
iterator in interface Collection<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.



Copyright © 2001-2011 Apache Cayenne. All Rights Reserved.