KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.GroupFetchScanController
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.services.io.Storable;
25
26 import org.apache.derby.iapi.error.StandardException;
27
28 import org.apache.derby.iapi.types.DataValueDescriptor;
29
30 import org.apache.derby.iapi.types.RowLocation;
31
32 import org.apache.derby.iapi.services.io.FormatableBitSet;
33
34 import java.util.Hashtable JavaDoc;
35
36 /**
37   This scan controller can only be used for group fetch, no update
38   operations are supported, use ScanController if you need scan interfaces
39   other than group fetch.
40   <p>
41   In general group fetch will be more efficient than using the
42   ScanController fetchNext() interface to get rows one at a time. The
43   performance comes from reducing the per call overhead of getting
44   a row. Also this interface can, depending on the requested isolation
45   level, possibly do more efficient locking.
46   <p>
47   Group fetch scans are opened from a TransactionController.
48
49   @see TransactionController#openScan
50   @see RowCountable
51   @see GenericScanController
52
53 **/
54
55 public interface GroupFetchScanController extends GenericScanController
56 {
57     /**
58      * Fetch the next N rows from the table.
59      * <p>
60      * The client allocates an array of N rows and passes it into the
61      * fetchNextSet() call. The client must at least allocate a row and
62      * set row_array[0] to this row. The client can optionally either leave
63      * the rest of array entries null, or allocate rows to the slots.
64      * If access finds an entry to be null, and wants to read a row into
65      * it, it will allocate a row to the slot. Once fetchNextGroup() returns
66      * "ownership" of the row passes back to the client, access will not
67      * keep references to the allocated row. Expected usage is that
68      * the client will specify an array of some number (say 10), and then
69      * only allocate a single row. This way if only 1 row qualifies only
70      * one row will have been allocated.
71      * <p>
72      * This routine does the equivalent of N
73      * fetchNext() calls, filling in each of the rows in the array.
74      * Locking is performed exactly as if the N fetchNext() calls had
75      * been made.
76      * <p>
77      * It is up to Access how many rows to return. fetchNextGroup() will
78      * return how many rows were filled in. If fetchNextGroup() returns 0
79      * then the scan is complete, (ie. the scan is in the same state as if
80      * fetchNext() had returned false). If the scan is not complete then
81      * fetchNext() will return (1 <= row_count <= N).
82      * <p>
83      * The current position of the scan is undefined if fetchNextSet()
84      * is used (ie. mixing fetch()/fetchNext() and fetchNextSet() calls
85      * in a single scan does not work). This is because a fetchNextSet()
86      * request for 5 rows from a heap where the first 2 rows qualify, but
87      * no other rows qualify will result in the scan being positioned at
88      * the end of the table, while if 5 rows did qualify the scan will be
89      * positioned on the 5th row.
90      * <p>
91      * If the row loc array is non-null then for each row fetched into
92      * the row array, a corresponding fetchLocation() call will be made to
93      * fill in the rowloc_array. This array, like the row array can be
94      * initialized with only one non-null RowLocation and access will
95      * allocate the rest on demand.
96      * <p>
97      * Qualifiers, start and stop positioning of the openscan are applied
98      * just as in a normal scan.
99      * <p>
100      * The columns of the row will be the standard columns returned as
101      * part of a scan, as described by the validColumns - see openScan for
102      * description.
103      * <p>
104      * Expected usage:
105      *
106      * // allocate an array of 5 empty rows
107      * DataValueDescriptor[][] row_array = allocate_row_array(5);
108      * int row_cnt = 0;
109      *
110      * scan = openScan();
111      *
112      * while ((row_cnt = scan.fetchNextSet(row_array, null) != 0)
113      * {
114      * // I got "row_cnt" rows from the scan. These rows will be
115      * // found in row_array[0] through row_array[row_cnt - 1]
116      * }
117      *
118      * <p>
119      * @return The number of qualifying rows found and copied into the
120      * provided array of rows. If 0 then the scan is complete,
121      * otherwise the return value will be:
122      * 1 <= row_count <= row_array.length
123      *
124      * @param row_array The array of rows to copy rows into.
125      * row_array[].length must >= 1. The first entry
126      * must be non-null destination rows, other entries
127      * may be null and will be allocated by access
128      * if needed.
129      *
130      * @param rowloc_array If non-null, the array of row locations to
131      * copy into. If null, no row locations are
132      * retrieved.
133      *
134      * @exception StandardException Standard exception policy.
135      **/
136     public int fetchNextGroup(
137     DataValueDescriptor[][] row_array,
138     RowLocation[] rowloc_array)
139         throws StandardException;
140
141     public int fetchNextGroup(
142     DataValueDescriptor[][] row_array,
143     RowLocation[] oldrowloc_array,
144     RowLocation[] newrowloc_array)
145         throws StandardException;
146
147     /**
148     Move to the next position in the scan. If this is the first
149     call to next(), the position is set to the first row.
150     Returns false if there is not a next row to move to.
151     It is possible, but not guaranteed, that this method could return
152     true again, after returning false, if some other operation in the same
153     transaction appended a row to the underlying conglomerate.
154
155     @return True if there is a next position in the scan,
156     false if there isn't.
157
158     @exception StandardException Standard exception policy.
159     **/
160     boolean next()
161         throws StandardException;
162 }
163
Popular Tags