Apache Derby Database Engine and Embedded JDBC Driver 10.17.1.0 · org.apache.derby.iapi.store.access.SortObserver

A SortObserver is an object that is used as a callback by the sorter. It allows the sort client to do whatever they want from the context of a sort. It contains 2 callback methods: insertDuplicateKey() and insertNonDuplicateKey(). On each SortController.insert(), one or the other of these methods will be called, depending on whether the given row has a key that has been seen before or not.

Some sample uses include:

Sorts from Language: Language typically recycles data type wrappers. So the language layer uses SortObservers to clone rows that are kept by the sorter.
Distinct sorts: The sorter will call the sort observer each time it identifies a duplicate row. Based on what the sort observer returns to the sorter, the sorter will either retain (insert) the duplicate row, or discard the duplicate row. All you have to do to implement a distinct sort is to tell the sorter to discard the row (return null from insertDuplicateKey()). Also, if you want to throw an exception on a duplicate (e.g. create a unique index), you can just throw an exception from your SortObserver.
Aggregates: Vector (grouped) aggregates typically require a sort. Language can use a SortObserver to perform aggregations as duplicate elements are encountered. Scalar aggregates can also be computed using a SortObserver.

These are possible uses only. You, kind reader, may do whatever you wish with this forgiving interface.

Method Summary

Modifier and Type	Method and Description
public void	addToFreeList(DataValueDescriptor[] objectArray, int maxFreeListSize)
public boolean	Returns: true if the index's constraint is deferrable. Any SortObserver implementations that implement uniqueness checking need to keep track of this information. deferrable() Overridden by subclasses that observe sorters with uniqueness checking.
public boolean	Returns: true if constraint mode of the index's constraint is effectively deferred. Any SortObserver implementations that implement uniqueness checking need to keep track of this information. deferred() Overridden by subclasses that observe sorters with uniqueness checking.
public DataValueDescriptor[]	getArrayClone()
public DataValueDescriptor[]	Returns: the row to be inserted by the sorter. If null, then nothing is inserted by the sorter. Distinct sorts will want to return null. insertDuplicateKey(DataValueDescriptor[] the current row that the sorter is on the verge of retaining. It is a duplicate of existingRow. insertRow, DataValueDescriptor[] the row that is already in the the sorter which is a duplicate of insertRow existingRow) Called prior to inserting a duplicate sort key.
public DataValueDescriptor[]	Returns: the row to be inserted by the sorter. If null, then nothing is inserted by the sorter. insertNonDuplicateKey(DataValueDescriptor[] the current row that the sorter is on the verge of retaining insertRow) Called prior to inserting a distinct sort key; in other words, the first time that a key is inserted into the sorter, this method is called.
public void	rememberDuplicate(DataValueDescriptor[] data of offending key row) Overridden by subclasses that observe sorters with uniqueness checking.

Method Detail

addToFreeList	back to summary
public void addToFreeList(DataValueDescriptor[] objectArray, int maxFreeListSize)

deferrable	back to summary
public boolean deferrable() Overridden by subclasses that observe sorters with uniqueness checking. Returns:boolean true if the index's constraint is deferrable. Any SortObserver implementations that implement uniqueness checking need to keep track of this information.

deferrable

back to summary

public boolean deferrable()

Overridden by subclasses that observe sorters with uniqueness checking.

Returns:boolean: true if the index's constraint is deferrable. Any SortObserver implementations that implement uniqueness checking need to keep track of this information.

deferred	back to summary
public boolean deferred() Overridden by subclasses that observe sorters with uniqueness checking. Returns:boolean true if constraint mode of the index's constraint is effectively deferred. Any SortObserver implementations that implement uniqueness checking need to keep track of this information.

deferred

back to summary

public boolean deferred()

Overridden by subclasses that observe sorters with uniqueness checking.

Returns:boolean: true if constraint mode of the index's constraint is effectively deferred. Any SortObserver implementations that implement uniqueness checking need to keep track of this information.

getArrayClone	back to summary
public DataValueDescriptor[] getArrayClone() throws StandardException

insertDuplicateKey	back to summary
public DataValueDescriptor[] insertDuplicateKey(DataValueDescriptor[] insertRow, DataValueDescriptor[] existingRow) throws StandardException Called prior to inserting a duplicate sort key. This method will typically be used to perform some aggregation on a row that is going to be discarded by the sorter. Parameters insertRow:DataValueDescriptor[] the current row that the sorter is on the verge of retaining. It is a duplicate of existingRow. existingRow:DataValueDescriptor[] the row that is already in the the sorter which is a duplicate of insertRow Returns:DataValueDescriptor[] the row to be inserted by the sorter. If null, then nothing is inserted by the sorter. Distinct sorts will want to return null. Exceptions StandardException: either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

insertDuplicateKey

back to summary

public DataValueDescriptor[] insertDuplicateKey(DataValueDescriptor[] insertRow, DataValueDescriptor[] existingRow) throws StandardException

Called prior to inserting a duplicate sort key. This method will typically be used to perform some aggregation on a row that is going to be discarded by the sorter.

Parameters

insertRow:DataValueDescriptor[]: the current row that the sorter is on the verge of retaining. It is a duplicate of existingRow.
existingRow:DataValueDescriptor[]: the row that is already in the the sorter which is a duplicate of insertRow

Returns:DataValueDescriptor[]

the row to be inserted by the sorter. If null, then nothing is inserted by the sorter. Distinct sorts will want to return null.

Exceptions

StandardException:: either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

insertNonDuplicateKey	back to summary
public DataValueDescriptor[] insertNonDuplicateKey(DataValueDescriptor[] insertRow) throws StandardException Called prior to inserting a distinct sort key; in other words, the first time that a key is inserted into the sorter, this method is called. Subsequent inserts with the same key generate a call to insertDuplicateKey() instead. This method will most commonly be used to clone the row that is retained by the sorter, or possibly to do some initialization of that row. Parameters insertRow:DataValueDescriptor[] the current row that the sorter is on the verge of retaining Returns:DataValueDescriptor[] the row to be inserted by the sorter. If null, then nothing is inserted by the sorter. Exceptions StandardException: either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

insertNonDuplicateKey

back to summary

public DataValueDescriptor[] insertNonDuplicateKey(DataValueDescriptor[] insertRow) throws StandardException

Called prior to inserting a distinct sort key; in other words, the first time that a key is inserted into the sorter, this method is called. Subsequent inserts with the same key generate a call to insertDuplicateKey() instead.

This method will most commonly be used to clone the row that is retained by the sorter, or possibly to do some initialization of that row.

Parameters

insertRow:DataValueDescriptor[]: the current row that the sorter is on the verge of retaining

Returns:DataValueDescriptor[]

the row to be inserted by the sorter. If null, then nothing is inserted by the sorter.

Exceptions

StandardException:: either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

rememberDuplicate	back to summary
public void rememberDuplicate(DataValueDescriptor[] row) throws StandardException Overridden by subclasses that observe sorters with uniqueness checking. Will be called by sorters iff deferrable() and deferred() and uniqueness violation, so implementations that sometimes return true to these must implement this method to save duplicate information till commit time. Parameters row:DataValueDescriptor[] data of offending key Exceptions StandardException: standard error policy

rememberDuplicate

back to summary

public void rememberDuplicate(DataValueDescriptor[] row) throws StandardException

Overridden by subclasses that observe sorters with uniqueness checking. Will be called by sorters iff deferrable() and deferred() and uniqueness violation, so implementations that sometimes return true to these must implement this method to save duplicate information till commit time.

Parameters

row:DataValueDescriptor[]: data of offending key

Exceptions

StandardException:: standard error policy

public Interface SortObserver

Method Summary

Method Detail