org.apache.derby.iapi.store.access
Interface SortObserver

All Known Implementing Classes:
BasicSortObserver

public interface 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:

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

See Also:
SortController

Method Summary
 void addToFreeList(DataValueDescriptor[] objectArray, int maxFreeListSize)
           
 DataValueDescriptor[] getArrayClone()
           
 DataValueDescriptor[] insertDuplicateKey(DataValueDescriptor[] insertRow, DataValueDescriptor[] existingRow)
          Called prior to inserting a duplicate sort key.
 DataValueDescriptor[] insertNonDuplicateKey(DataValueDescriptor[] 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.
 

Method Detail

insertNonDuplicateKey

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 - the current row that the sorter is on the verge of retaining
Returns:
the row to be inserted by the sorter. If null, then nothing is inserted by the sorter.
Throws:
StandardException - either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

insertDuplicateKey

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 - the current row that the sorter is on the verge of retaining. It is a duplicate of existingRow.
existingRow - the row that is already in the the sorter which is a duplicate of insertRow
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.
Throws:
StandardException - either on unexpected exception, or on expected user error that is to percolate back to the driver of the sort.

addToFreeList

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

getArrayClone

public DataValueDescriptor[] getArrayClone()
                                    throws StandardException
Throws:
StandardException

Built on Tue 2006-10-10 19:23:47+0200, from revision exported

Apache Derby V10.1 Engine Documentation - Copyright © 1997,2005 The Apache Software Foundation or its licensors, as applicable.