com.solarmetric.kodo.runtime.objectprovider
Class OnDemandForwardResultList

java.lang.Object
  |
  +--java.util.AbstractCollection
        |
        +--java.util.AbstractList
              |
              +--com.solarmetric.kodo.runtime.objectprovider.OnDemandForwardResultList

All Implemented Interfaces:

Collection, CustomResultList, List, ResultList, Serializable

public class OnDemandForwardResultList

extends AbstractList

implements CustomResultList, Serializable

ResultList implementation that uses lazy instantiation for forward-only underlying ResultObjectProvider instances.

The result of size() will return Integer.MAX_VALUE if the results have not yet been completely instantiated, in accordance with section 14.6.1 of the JDO specification.

By default, hard references will be used to hold elements of the list. The configuration parameters setUseHardReferences(boolean), setUseSoftReferences(boolean), and setUseWeakReferences(boolean) can be used to configure this behavior. Note that if a weak or soft reference holder is garbage collected, then null may be returned from invocations of get(int), since the underlying input cannot be scrolled back to retrieve the lost object.

Since:

2.5.0

See Also:

ResultList, Configuration.setResultListClass(java.lang.String), Configuration.setResultListProperties(java.lang.String), Serialized Form

Fields inherited from class java.util.AbstractList

modCount

Constructor Summary

OnDemandForwardResultList()

Method Summary

void	checkClosed() Ensure that the ResultList is not closed.
void	close() To be in accordance with the spec, we need to throw an Exception on list access after our owning Extent or Query is closed.
boolean	equals(Object other) Unless the list is completely instantiated, returns the identity equals for objects, since returning the default Collection.equals(java.lang.Object) behanvior would mean that we have to traverse the entire list.
(package private) void	free() Close and free the result object provider.
Object	get(int index) Get the element at the indexth position.
int	getInstantiatedCount() Returns the number of results that have been instantiated.
int	getKnownSize() Return the correct size of the results if known, otherwise return Integer.MAX_VALUE.
(package private) Object	getReferenceAtIndex(int index) Returns the element of the list at index, or null if we are past the end of the list.
int	getTrueSize() Return the correct size of the results if known.
boolean	getUseCorrectSize() If true, the size() method will ensure that the results are completely instantiated before returning the size of the results.
boolean	getUseWindow() If this returns true, this list will use a sliding window of the same size as the PM's batch size (actually, the batch size plus one, to make room for the lookahead object) at the time that this list was created.
int	hashCode() Unless the list is completely instantiated, returns the identity hash code of this object, since returning the default Collection.hashCode() behanvior would mean that we have to traverse the entire list.
void	initResultList(Object input, ResultObjectProvider rop, Configuration config) Initialize the ResultList implementation, which will allow custom ResultList objects to be used for Query results.
boolean	isClosed() Returns true if the ResultList has been explicitely closed.
void	setUseCorrectSize(boolean useCorrectSize) Sets whether the results if size() should be correct.
void	setUseHardReferences(boolean use) If true, weak references will be held in the list.
void	setUseSoftReferences(boolean use) If true, soft references will be held in the list.
void	setUseWeakReferences(boolean use) If true, hard references will ensure that results will not be garbage collected.
void	setUseWindow(boolean val) If set to true, this list will use a sliding window of the same size as the PM's batch size (actually, the batch size plus one, to make room for the lookahead object) at the time that this list was created.
int	size() If getUseCorrectSize() is true, return the true size of the ResultList (instantiating all the elements if necessary), otherwise return the size of the results if they have been completely instantiated, or else Integer.MAX_VALUE (as per the JDO specification 1.0 section 14.6.1).
String	toString()
boolean	windowHasMoved() Returns true if the window has moved -- if the low end of the list have been dropped as we've moved through the list.
Object	writeReplace() Serialize as a simple ArrayList.

Methods inherited from class java.util.AbstractList

add, add, addAll, clear, indexOf, iterator, lastIndexOf, listIterator, listIterator, remove, removeRange, set, subList

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray

Methods inherited from class java.lang.Object

, clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.List

add, add, addAll, addAll, clear, contains, containsAll, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, retainAll, set, subList, toArray, toArray

Constructor Detail

OnDemandForwardResultList

public OnDemandForwardResultList()

Method Detail

initResultList

public void initResultList(Object input,
                           ResultObjectProvider rop,
                           Configuration config)

Description copied from interface: CustomResultList

Initialize the ResultList implementation, which will allow custom ResultList objects to be used for Query results.

Specified by:

initResultList in interface CustomResultList

Following copied from interface: com.solarmetric.kodo.runtime.objectprovider.CustomResultList

Parameters:

input - the source of the results (e.g., a JDBC ResultSet)

rop - the provider used to obtain the next element from the list

config - the Configuration object to use

getInstantiatedCount

public int getInstantiatedCount()

Returns the number of results that have been instantiated. If this list is configured with a window size, this number may be greater than the number of entries actually in the list.

Specified by:

getInstantiatedCount in interface ResultList

size

public int size()

If getUseCorrectSize() is true, return the true size of the ResultList (instantiating all the elements if necessary), otherwise return the size of the results if they have been completely instantiated, or else Integer.MAX_VALUE (as per the JDO specification 1.0 section 14.6.1).

Specified by:

size in interface List

Overrides:

size in class AbstractCollection

See Also:

getTrueSize(), getKnownSize()

getKnownSize

public int getKnownSize()

Return the correct size of the results if known, otherwise return Integer.MAX_VALUE.

getTrueSize

public int getTrueSize()

Return the correct size of the results if known. If the results have not been completely instantied yet, then they will be travered in order to obtain the correct count.

writeReplace

public Object writeReplace()
                    throws ObjectStreamException

Serialize as a simple ArrayList.

checkClosed

public void checkClosed()
                 throws FatalUserException

Ensure that the ResultList is not closed.

Specified by:

checkClosed in interface ResultList

Throws:

FatalUserException - if the list is closed

close

public void close()

To be in accordance with the spec, we need to throw an Exception on list access after our owning Extent or Query is closed.

Specified by:

close in interface ResultList

free

void free()

Close and free the result object provider.

get

public Object get(int index)

Get the element at the indexth position.

Specified by:

get in interface List

Overrides:

get in class AbstractList

getReferenceAtIndex

Object getReferenceAtIndex(int index)

Returns the element of the list at index, or null if we are past the end of the list.

isClosed

public boolean isClosed()

Returns true if the ResultList has been explicitely closed.

Specified by:

isClosed in interface ResultList

hashCode

public int hashCode()

Unless the list is completely instantiated, returns the identity hash code of this object, since returning the default Collection.hashCode() behanvior would mean that we have to traverse the entire list.

If the list is completely instantiated, the standard Collection.hashCode() contract is respected.

Specified by:

hashCode in interface List

Overrides:

hashCode in class AbstractList

equals

public boolean equals(Object other)

Unless the list is completely instantiated, returns the identity equals for objects, since returning the default Collection.equals(java.lang.Object) behanvior would mean that we have to traverse the entire list.

If the list is completely instantiated, the standard Collection.equals(java.lang.Object) contract is respected.

Specified by:

equals in interface List

Overrides:

equals in class AbstractList

setUseCorrectSize

public void setUseCorrectSize(boolean useCorrectSize)

Sets whether the results if size() should be correct.

See Also:

getUseCorrectSize()

getUseCorrectSize

public boolean getUseCorrectSize()

If true, the size() method will ensure that the results are completely instantiated before returning the size of the results. If false, size() will return Integer.MAX_VALUE if the results have not been completely instantiated.

setUseWindow

public void setUseWindow(boolean val)

If set to true, this list will use a sliding window of the same size as the PM's batch size (actually, the batch size plus one, to make room for the lookahead object) at the time that this list was created. If this list uses a sliding window, then low results will be dropped as we walk through this list. This means that the list can only be iterated once, and that the list will maintain a fixed amount of memory, among other things. By default, this is false.

Since:

2.5.3

getUseWindow

public boolean getUseWindow()

If this returns true, this list will use a sliding window of the same size as the PM's batch size (actually, the batch size plus one, to make room for the lookahead object) at the time that this list was created. If this list uses a sliding window, then low results will be dropped as we walk through this list. This means that the list can only be iterated once, and that the list will maintain a fixed amount of memory, among other things. By default, this returns false.

Since:

2.5.3

setUseWeakReferences

public void setUseWeakReferences(boolean use)

If true, hard references will ensure that results will not be garbage collected.

setUseHardReferences

public void setUseHardReferences(boolean use)

If true, weak references will be held in the list. If garbage collection occurs, then elements of the list might be null.

setUseSoftReferences

public void setUseSoftReferences(boolean use)

If true, soft references will be held in the list. If garbage collection occurs, then elements of the list might be null.

windowHasMoved

public boolean windowHasMoved()

Returns true if the window has moved -- if the low end of the list have been dropped as we've moved through the list. Otherwise, returns false.

Since:

2.5.3

toString

public String toString()

Overrides:

toString in class AbstractCollection