Source code: org/apache/derby/iapi/store/access/SortObserver.java
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.SortObserver
4
5 Copyright 1999, 2004 The Apache Software Foundation or its licensors, as applicable.
6
7 Licensed under the Apache License, Version 2.0 (the "License");
8 you may not use this file except in compliance with the License.
9 You may obtain a copy of the License at
10
11 http://www.apache.org/licenses/LICENSE-2.0
12
13 Unless required by applicable law or agreed to in writing, software
14 distributed under the License is distributed on an "AS IS" BASIS,
15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 See the License for the specific language governing permissions and
17 limitations under the License.
18
19 */
20
21 package org.apache.derby.iapi.store.access;
22
23 import org.apache.derby.iapi.types.DataValueDescriptor;
24
25 import org.apache.derby.iapi.error.StandardException;
26
27 /**
28 * A SortObserver is an object that is used as a callback by the
29 * sorter. It allows the sort client to do whatever they want
30 * from the context of a sort. It contains 2 callback methods:
31 * <I>insertDuplicateKey()</I> and <I>insertNonDuplicateKey()</I>.
32 * On each <I>SortController.insert()</I>, one or the other of these
33 * methods will be called, depending on whether the given row has a
34 * key that has been seen before or not.
35 * <p>
36 * Some sample uses include:
37 * <UL><LI>
38 *
39 * <I>Sorts from Language</I>: Language typically recycles
40 * data type wrappers. So the language layer uses SortObservers
41 * to clone rows that are kept by the sorter.
42 * </LI>
43 *
44 * <LI>
45 * <I>Distinct sorts</I>: The sorter will call the sort observer
46 * each time it identifies a duplicate row. Based on what the
47 * sort observer returns to the sorter, the sorter will either
48 * retain (insert) the duplicate row, or discard the duplicate
49 * row. All you have to do to implement a distinct sort is to
50 * tell the sorter to discard the row (return null from <I>
51 * insertDuplicateKey()</I>). Also, if you want to throw an
52 * exception on a duplicate (e.g. create a unique index), you
53 * can just throw an exception from your SortObserver.
54 * </LI>
55 *
56 * <LI>
57 * <I>Aggregates</I>: Vector (grouped) aggregates typically require
58 * a sort. Language can use a SortObserver to perform aggregations
59 * as duplicate elements are encountered. Scalar aggregates
60 * can also be computed using a SortObserver.
61 * </LI>
62 * </UL>
63 *
64 * These are possible uses only. You, kind reader, may do whatever
65 * you wish with this forgiving interface.
66 *
67 * @see SortController
68 *
69 **/
70 public interface SortObserver
71 {
72 /**
73 * Called prior to inserting a distinct sort
74 * key; in other words, the first time that a
75 * key is inserted into the sorter, this method
76 * is called. Subsequent inserts with the same
77 * key generate a call to insertDuplicateKey()
78 * instead.
79 * <p>
80 * This method will most commonly be used to clone
81 * the row that is retained by the sorter, or possibly
82 * to do some initialization of that row.
83 *
84 * @param insertRow the current row that the sorter
85 * is on the verge of retaining
86 *
87 * @return the row to be inserted by the sorter. If null,
88 * then nothing is inserted by the sorter.
89 *
90 * @exception StandardException either on unexpected exception,
91 * or on expected user error that is to percolate back
92 * to the driver of the sort.
93 */
94 DataValueDescriptor[] insertNonDuplicateKey(
95 DataValueDescriptor[] insertRow)
96 throws StandardException;
97
98 /**
99 * Called prior to inserting a duplicate sort
100 * key. This method will typically be used
101 * to perform some aggregation on a row that is
102 * going to be discarded by the sorter.
103 *
104 * @param insertRow the current row that the sorter
105 * is on the verge of retaining. It is a duplicate
106 * of existingRow.
107 *
108 * @param existingRow the row that is already in the
109 * the sorter which is a duplicate of insertRow
110 *
111 * @return the row to be inserted by the sorter. If null,
112 * then nothing is inserted by the sorter. Distinct
113 * sorts will want to return null.
114 *
115 * @exception StandardException either on unexpected exception,
116 * or on expected user error that is to percolate back
117 * to the driver of the sort.
118 */
119 DataValueDescriptor[] insertDuplicateKey(
120 DataValueDescriptor[] insertRow,
121 DataValueDescriptor[] existingRow)
122 throws StandardException;
123
124 public void addToFreeList(
125 DataValueDescriptor[] objectArray,
126 int maxFreeListSize);
127
128 public DataValueDescriptor[] getArrayClone()
129 throws StandardException;
130 }