Save This Page
1 /*
2
3 Derby - Class org.apache.derby.iapi.store.access.conglomerate.ScanManager
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.conglomerate;
23
24 import org.apache.derby.iapi.store.access.GroupFetchScanController;
25 import org.apache.derby.iapi.store.access.ScanController;
26 import org.apache.derby.iapi.store.raw.Page;
27 import org.apache.derby.iapi.error.StandardException;
28
29 import org.apache.derby.iapi.store.access.BackingStoreHashtable;
30
31 /**
32
33 The ScanManager interface contains those methods private to access method
34 implementors necessary to implement Scans on Conglomerates. Client of scans
35 use the ScanController to interact with the scan.
36 <P>
37 @see ScanController
38
39 **/
40
41 public interface ScanManager extends ScanController, GroupFetchScanController
42 {
43
44 /**
45 * Close scan as part of terminating a transaction.
46 * <p>
47 * Use this call to close the scan resources as part of committing or
48 * aborting a transaction. The normal close() routine may do some cleanup
49 * that is either unnecessary, or not correct due to the unknown condition
50 * of the scan following a transaction ending error. Use this call when
51 * closing all scans as part of an abort of a transaction.
52 *
53 * @param closeHeldScan If true, means to close scan even if it has been
54 * opened to be kept opened across commit. This is
55 * used to close these scans on abort.
56 *
57 * @return boolean indicating that the close has resulted in a real close
58 * of the scan. A held scan will return false if called
59 * by closeForEndTransaction(false), otherwise it will
60 * return true. A non-held scan will always return true.
61 *
62 * @exception StandardException Standard exception policy.
63 **/
64 boolean closeForEndTransaction(boolean closeHeldScan)
65 throws StandardException;
66
67 /**
68 * Insert all rows that qualify for the current scan into the input
69 * Hash table.
70 * <p>
71 * This routine scans executes the entire scan as described in the
72 * openScan call. For every qualifying unique row value an entry is
73 * placed into the HashTable. For unique row values the entry in the
74 * Hashtable has a key value of the object stored in
75 * row[key_column_number], and the value of the data is row. For row
76 * values with duplicates, the key value is also row[key_column_number],
77 * but the value of the data is a Vector of
78 * rows. The caller will have to call "instanceof" on the data value
79 * object if duplicates are expected, to determine if the data value
80 * of the Hashtable entry is a row or is a Vector of rows.
81 * <p>
82 * Note, that for this routine to work efficiently the caller must
83 * ensure that the object in row[key_column_number] implements
84 * the hashCode and equals method as appropriate for it's datatype.
85 * <p>
86 * It is expected that this call will be the first and only call made in
87 * an openscan. Qualifiers and stop position of the openscan are applied
88 * just as in a normal scan. This call is logically equivalent to the
89 * caller performing the following:
90 *
91 * import java.util.Hashtable;
92 *
93 * hash_table = new Hashtable();
94 *
95 * while (next())
96 * {
97 * row = create_new_row();
98 * fetch(row);
99 * if ((duplicate_value =
100 * hash_table.put(row[key_column_number], row)) != null)
101 * {
102 * Vector row_vec;
103 *
104 * // inserted a duplicate
105 * if ((duplicate_value instanceof vector))
106 * {
107 * row_vec = (Vector) duplicate_value;
108 * }
109 * else
110 * {
111 * // allocate vector to hold duplicates
112 * row_vec = new Vector(2);
113 *
114 * // insert original row into vector
115 * row_vec.addElement(duplicate_value);
116 *
117 * // put the vector as the data rather than the row
118 * hash_table.put(row[key_column_number], row_vec);
119 * }
120 *
121 * // insert new row into vector
122 * row_vec.addElement(row);
123 * }
124 * }
125 * <p>
126 * The columns of the row will be the standard columns returned as
127 * part of a scan, as described by the validColumns - see openScan for
128 * description.
129 * RESOLVE - is this ok? or should I hard code somehow the row to
130 * be the first column and the row location?
131 * <p>
132 * No overflow to external storage is provided, so calling this routine
133 * on a 1 gigabyte conglomerate will incur at least 1 gigabyte of memory
134 * (probably failing with a java out of memory condition). If this
135 * routine gets an out of memory condition, or if "max_rowcnt" is
136 * exceeded then then the routine will give up, empty the Hashtable,
137 * and return "false."
138 * <p>
139 * On exit from this routine, whether the fetchSet() succeeded or not
140 * the scan is complete, it is positioned just the same as if the scan
141 * had been drained by calling "next()" until it returns false (ie.
142 * fetchNext() and next() calls will return false).
143 * reopenScan() can be called to restart the scan.
144 * <p>
145 *
146 * RESOLVE - until we get row counts what should we do for sizing the
147 * the size, capasity, and load factor of the hash table.
148 * For now it is up to the caller to create the Hashtable,
149 * Access does not reset any parameters.
150 * <p>
151 * RESOLVE - I am not sure if access should be in charge of allocating
152 * the new row objects. I know that I can do this in the
153 * case of btree's, but I don't think I can do this in heaps.
154 * Maybe this is solved by work to be done on the sort
155 * interface.
156 *
157 *
158 * @param max_rowcnt The maximum number of rows to insert into the
159 * Hash table. Pass in -1 if there is no maximum.
160 * @param key_column_numbers The column numbers of the columns in the
161 * scan result row to be the key to the Hashtable.
162 * "0" is the first column in the scan result
163 * row (which may be different than the first
164 * row in the table of the scan).
165 *
166 * @exception StandardException Standard exception policy.
167 **/
168 void fetchSet(
169 long max_rowcnt,
170 int[] key_column_numbers,
171 BackingStoreHashtable hash_table)
172 throws StandardException;
173 }