| org.apache.derby.iapi.store.access.SortObserver
All known Subclasses: org.apache.derby.impl.sql.execute.BasicSortObserver,
SortObserver | public interface SortObserver (Code) | | 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.
See Also: SortController |
insertDuplicateKey | DataValueDescriptor[] insertDuplicateKey(DataValueDescriptor[] insertRow, DataValueDescriptor[] existingRow) throws StandardException(Code) | | 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 - the current row that the sorteris on the verge of retaining. It is a duplicateof existingRow. Parameters: existingRow - the row that is already in thethe sorter which is a duplicate of insertRow the row to be inserted by the sorter. If null,then nothing is inserted by the sorter. Distinctsorts will want to return null. exception: StandardException - either on unexpected exception,or on expected user error that is to percolate backto the driver of the sort. |
insertNonDuplicateKey | DataValueDescriptor[] insertNonDuplicateKey(DataValueDescriptor[] insertRow) throws StandardException(Code) | | 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 - the current row that the sorteris on the verge of retaining the row to be inserted by the sorter. If null,then nothing is inserted by the sorter. exception: StandardException - either on unexpected exception,or on expected user error that is to percolate backto the driver of the sort. |
|
|