001: /*
002:
003: Derby - Class org.apache.derby.impl.store.access.sort.Scan
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.impl.store.access.sort;
023:
024: import org.apache.derby.iapi.reference.SQLState;
025:
026: import org.apache.derby.iapi.store.access.BackingStoreHashtable;
027: import org.apache.derby.iapi.services.io.FormatableBitSet;
028: import org.apache.derby.iapi.services.i18n.MessageService;
029:
030: import org.apache.derby.iapi.services.io.Storable;
031:
032: import org.apache.derby.iapi.types.Orderable;
033: import org.apache.derby.iapi.types.RowLocation;
034:
035: import org.apache.derby.iapi.error.StandardException;
036:
037: import org.apache.derby.iapi.store.access.conglomerate.Conglomerate;
038: import org.apache.derby.iapi.store.access.conglomerate.ScanManager;
039:
040: import org.apache.derby.iapi.store.access.Qualifier;
041: import org.apache.derby.iapi.store.access.ScanController;
042: import org.apache.derby.iapi.store.access.ScanInfo;
043:
044: import org.apache.derby.iapi.store.raw.Page;
045:
046: import org.apache.derby.iapi.types.DataValueDescriptor;
047:
048: import java.util.Properties;
049:
050: /**
051:
052: Abstract base class for all sort classes which return rows from the
053: sort. Subclasses must implement fetch, next, and close.
054:
055: **/
056:
057: public abstract class Scan implements ScanManager, ScanInfo {
058: /*
059: * Methods of ScanController
060: */
061:
062: /**
063: * A call to allow client to indicate that current row does not qualify.
064: * <p>
065: * Indicates to the ScanController that the current row does not
066: * qualify for the scan. If the isolation level of the scan allows,
067: * this may result in the scan releasing the lock on this row.
068: * <p>
069: * Note that some scan implimentations may not support releasing locks on
070: * non-qualifying rows, or may delay releasing the lock until sometime
071: * later in the scan (ie. it may be necessary to keep the lock until
072: * either the scan is repositioned on the next row or page).
073: * <p>
074: * This call should only be made while the scan is positioned on a current
075: * valid row.
076: * <p>
077: * This call does not make sense for sort scans.
078: *
079: * @exception StandardException Standard exception policy.
080: **/
081: public void didNotQualify() throws StandardException {
082: }
083:
084: /**
085: * Fetch the next N rows from the table.
086: * <p>
087: * Currently unimplemented for sorts.
088: * <p>
089: **/
090: public int fetchNextGroup(DataValueDescriptor[][] row_array,
091: RowLocation[] rowloc_array) throws StandardException {
092: throw StandardException
093: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
094: }
095:
096: public int fetchNextGroup(DataValueDescriptor[][] row_array,
097: RowLocation[] old_rowloc_array,
098: RowLocation[] new_rowloc_array) throws StandardException {
099: throw StandardException
100: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
101: }
102:
103: /**
104: * Insert all rows that qualify for the current scan into the input
105: * Hash table.
106: * <p>
107: * Currently unimplemented for sorts.
108: * <p>
109: **/
110: public void fetchSet(long max_rowcnt, int[] key_column_numbers,
111: BackingStoreHashtable hash_table) throws StandardException {
112: throw StandardException
113: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
114: }
115:
116: /**
117: Returns true if the current position of the scan still qualifies
118: under the set of qualifiers passed to the openScan().
119: @see ScanController#doesCurrentPositionQualify
120: **/
121: public boolean doesCurrentPositionQualify()
122: throws StandardException {
123: return true;
124: }
125:
126: /**
127: Fetch the location of the current position in the scan.
128: @see ScanController#fetchLocation
129: **/
130: public void fetchLocation(RowLocation templateLocation)
131: throws StandardException {
132: throw StandardException
133: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
134: }
135:
136: /**
137: * Return ScanInfo object which describes performance of scan.
138: * <p>
139: * Return ScanInfo object which contains information about the current
140: * scan.
141: * <p>
142: * Currently the ScanInfo does not have any performance data.
143: *
144: * @see ScanInfo
145: *
146: * @return The ScanInfo object which contains info about current scan.
147: *
148: * @exception StandardException Standard exception policy.
149: **/
150: public ScanInfo getScanInfo() throws StandardException {
151: return (this );
152: }
153:
154: /**
155: * Get the total estimated number of rows in the container.
156: * <p>
157: * The number is a rough estimate and may be grossly off. In general
158: * the server will cache the row count and then occasionally write
159: * the count unlogged to a backing store. If the system happens to
160: * shutdown before the store gets a chance to update the row count it
161: * may wander from reality.
162: * <p>
163: * This call is currently only supported on Heap conglomerates, it
164: * will throw an exception if called on btree conglomerates.
165: *
166: * @return The total estimated number of rows in the conglomerate.
167: *
168: * @exception StandardException Standard exception policy.
169: **/
170: public long getEstimatedRowCount() throws StandardException {
171: throw StandardException
172: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
173: }
174:
175: /**
176: * Set the total estimated number of rows in the container.
177: * <p>
178: * Often, after a scan, the client of RawStore has a much better estimate
179: * of the number of rows in the container than what store has. For
180: * instance if we implement some sort of update statistics command, or
181: * just after a create index a complete scan will have been done of the
182: * table. In this case this interface allows the client to set the
183: * estimated row count for the container, and store will use that number
184: * for all future references.
185: * <p>
186: * This call is currently only supported on Heap conglomerates, it
187: * will throw an exception if called on btree conglomerates.
188: *
189: * @param count the estimated number of rows in the container.
190: *
191: * @exception StandardException Standard exception policy.
192: **/
193: public void setEstimatedRowCount(long count)
194: throws StandardException {
195: throw StandardException
196: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
197: }
198:
199: /**
200: Returns true if the current position of the scan is at a
201: deleted row.
202: @see ScanController#isCurrentPositionDeleted
203: **/
204: public boolean isCurrentPositionDeleted() throws StandardException {
205: throw StandardException
206: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
207: }
208:
209: /**
210: * Return whether this is a keyed conglomerate.
211: * <p>
212: *
213: * @return whether this is a keyed conglomerate.
214: **/
215: public boolean isKeyed() {
216: return (false);
217: }
218:
219: /**
220: * Return whether this scan is table locked.
221: *
222: * @return whether this is table locked.
223: **/
224: public boolean isTableLocked() {
225: return (true);
226: }
227:
228: /**
229: Delete the row at the current position of the scan.
230: @see ScanController#delete
231: **/
232: public boolean delete() throws StandardException {
233: throw StandardException
234: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
235: }
236:
237: /**
238: Reposition the current scan.
239: @see ScanController#reopenScan
240: **/
241: public void reopenScan(DataValueDescriptor[] startKeyValue,
242: int startSearchOperator, Qualifier qualifier[][],
243: DataValueDescriptor[] stopKeyValue, int stopSearchOperator)
244: throws StandardException {
245: throw StandardException
246: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
247: }
248:
249: /**
250: Reposition the current scan. This call is semantically the same as if
251: the current scan had been closed and a openScan() had been called instead.
252: The scan is reopened against the same conglomerate, and the scan
253: is reopened with the same "scan column list", "hold" and "forUpdate"
254: parameters passed in the original openScan.
255:
256: @exception StandardException Standard exception policy.
257: **/
258: public void reopenScanByRowLocation(RowLocation startRowLocation,
259: Qualifier qualifier[][]) throws StandardException {
260: throw StandardException
261: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
262: }
263:
264: /**
265: Replace the entire row at the current position of the scan.
266: @see ScanController#replace
267: **/
268: public boolean replace(DataValueDescriptor[] val,
269: FormatableBitSet validColumns) throws StandardException {
270: throw StandardException
271: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
272: }
273:
274: /**
275: Return a row location object of the correct type to be
276: used in calls to fetchLocation.
277: @see ScanController#newRowLocationTemplate
278: **/
279: public RowLocation newRowLocationTemplate()
280: throws StandardException {
281: throw StandardException
282: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
283: }
284:
285: /**
286: *@see ScanController#positionAtRowLocation
287: */
288: public boolean positionAtRowLocation(RowLocation rl)
289: throws StandardException {
290: throw StandardException
291: .newException(SQLState.SORT_IMPROPER_SCAN_METHOD);
292: }
293:
294: /*
295: ** Methods of ScanManager
296: */
297:
298: /**
299: * Do work necessary to maintain the current position in the scan.
300: * <p>
301: * The latched page in the conglomerate "congomid" is changing, do
302: * whatever is necessary to maintain the current position of the scan.
303: * For some conglomerates this may be a no-op.
304: * <p>
305: *
306: * @param conglom Conglomerate object of the conglomerate being changed.
307: * @param page Page in the conglomerate being changed.
308: *
309: * @exception StandardException Standard exception policy.
310: **/
311: public void savePosition(Conglomerate conglom, Page page)
312: throws StandardException {
313: // RESOLVE (mikem), under the current implementation all scans within
314: // a transaction are called rather than just the ones with the right
315: // conglomid. For now just have sort scans ignore the call.
316:
317: return;
318: }
319:
320: /*
321: * Methods of ScanInfo
322: */
323:
324: /**
325: * Return all information gathered about the scan.
326: * <p>
327: * This routine returns a list of properties which contains all information
328: * gathered about the scan. If a Property is passed in, then that property
329: * list is appeneded to, otherwise a new property object is created and
330: * returned.
331: * <p>
332: * Currently sort scans doesn't track any information.
333: *
334: * @param prop Property list to fill in.
335: *
336: * @exception StandardException Standard exception policy.
337: **/
338: public Properties getAllScanInfo(Properties prop)
339: throws StandardException {
340: if (prop == null)
341: prop = new Properties();
342:
343: prop.put(MessageService
344: .getTextMessage(SQLState.STORE_RTS_SCAN_TYPE),
345: MessageService.getTextMessage(SQLState.STORE_RTS_SORT));
346:
347: return (prop);
348: }
349: }
|