001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.SortObserver
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.access;
023:
024: import org.apache.derby.iapi.types.DataValueDescriptor;
025:
026: import org.apache.derby.iapi.error.StandardException;
027:
028: /**
029: * A SortObserver is an object that is used as a callback by the
030: * sorter. It allows the sort client to do whatever they want
031: * from the context of a sort. It contains 2 callback methods:
032: * <I>insertDuplicateKey()</I> and <I>insertNonDuplicateKey()</I>.
033: * On each <I>SortController.insert()</I>, one or the other of these
034: * methods will be called, depending on whether the given row has a
035: * key that has been seen before or not.
036: * <p>
037: * Some sample uses include:
038: * <UL><LI>
039: *
040: * <I>Sorts from Language</I>: Language typically recycles
041: * data type wrappers. So the language layer uses SortObservers
042: * to clone rows that are kept by the sorter.
043: * </LI>
044: *
045: * <LI>
046: * <I>Distinct sorts</I>: The sorter will call the sort observer
047: * each time it identifies a duplicate row. Based on what the
048: * sort observer returns to the sorter, the sorter will either
049: * retain (insert) the duplicate row, or discard the duplicate
050: * row. All you have to do to implement a distinct sort is to
051: * tell the sorter to discard the row (return null from <I>
052: * insertDuplicateKey()</I>). Also, if you want to throw an
053: * exception on a duplicate (e.g. create a unique index), you
054: * can just throw an exception from your SortObserver.
055: * </LI>
056: *
057: * <LI>
058: * <I>Aggregates</I>: Vector (grouped) aggregates typically require
059: * a sort. Language can use a SortObserver to perform aggregations
060: * as duplicate elements are encountered. Scalar aggregates
061: * can also be computed using a SortObserver.
062: * </LI>
063: * </UL>
064: *
065: * These are possible uses only. You, kind reader, may do whatever
066: * you wish with this forgiving interface.
067: *
068: * @see SortController
069: *
070: **/
071: public interface SortObserver {
072: /**
073: * Called prior to inserting a distinct sort
074: * key; in other words, the first time that a
075: * key is inserted into the sorter, this method
076: * is called. Subsequent inserts with the same
077: * key generate a call to insertDuplicateKey()
078: * instead.
079: * <p>
080: * This method will most commonly be used to clone
081: * the row that is retained by the sorter, or possibly
082: * to do some initialization of that row.
083: *
084: * @param insertRow the current row that the sorter
085: * is on the verge of retaining
086: *
087: * @return the row to be inserted by the sorter. If null,
088: * then nothing is inserted by the sorter.
089: *
090: * @exception StandardException either on unexpected exception,
091: * or on expected user error that is to percolate back
092: * to the driver of the sort.
093: */
094: DataValueDescriptor[] insertNonDuplicateKey(
095: DataValueDescriptor[] insertRow) throws StandardException;
096:
097: /**
098: * Called prior to inserting a duplicate sort
099: * key. This method will typically be used
100: * to perform some aggregation on a row that is
101: * going to be discarded by the sorter.
102: *
103: * @param insertRow the current row that the sorter
104: * is on the verge of retaining. It is a duplicate
105: * of existingRow.
106: *
107: * @param existingRow the row that is already in the
108: * the sorter which is a duplicate of insertRow
109: *
110: * @return the row to be inserted by the sorter. If null,
111: * then nothing is inserted by the sorter. Distinct
112: * sorts will want to return null.
113: *
114: * @exception StandardException either on unexpected exception,
115: * or on expected user error that is to percolate back
116: * to the driver of the sort.
117: */
118: DataValueDescriptor[] insertDuplicateKey(
119: DataValueDescriptor[] insertRow,
120: DataValueDescriptor[] existingRow) throws StandardException;
121:
122: public void addToFreeList(DataValueDescriptor[] objectArray,
123: int maxFreeListSize);
124:
125: public DataValueDescriptor[] getArrayClone()
126: throws StandardException;
127: }
|