KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > access > SortObserver


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