01: /*
02:
03: Derby - Class org.apache.derby.iapi.store.access.RowLocationRetRowSource
04:
05: Licensed to the Apache Software Foundation (ASF) under one or more
06: contributor license agreements. See the NOTICE file distributed with
07: this work for additional information regarding copyright ownership.
08: The ASF licenses this file to you under the Apache License, Version 2.0
09: (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.error.StandardException;
25:
26: import org.apache.derby.iapi.types.DataValueDescriptor;
27:
28: import org.apache.derby.iapi.types.RowLocation;
29:
30: /**
31:
32: A RowLocationRetRowSource is the mechanism for iterating over a set of rows,
33: loading those rows into a conglomerate, and returning the RowLocation of the
34: inserted rows.
35:
36: @see RowSource
37:
38: */
39: public interface RowLocationRetRowSource extends RowSource {
40:
41: /**
42: needsRowLocation returns true iff this the row source expects the
43: drainer of the row source to call rowLocation after getting a row from
44: getNextRowFromRowSource.
45:
46: @return true iff this row source expects some row location to be
47: returned
48: @see #rowLocation
49: */
50: boolean needsRowLocation();
51:
52: /**
53: rowLocation is a callback for the drainer of the row source to return
54: the rowLocation of the current row, i.e, the row that is being returned
55: by getNextRowFromRowSource. This interface is for the purpose of
56: loading a base table with index. In that case, the indices can be
57: built at the same time the base table is laid down once the row
58: location of the base row is known. This is an example pseudo code on
59: how this call is expected to be used:
60:
61: <BR><pre>
62: boolean needsRL = rowSource.needsRowLocation();
63: DataValueDescriptor[] row;
64: while((row = rowSource.getNextRowFromRowSource()) != null)
65: {
66: RowLocation rl = heapConglomerate.insertRow(row);
67: if (needsRL)
68: rowSource.rowLocation(rl);
69: }
70: </pre><BR>
71:
72: NeedsRowLocation and rowLocation will ONLY be called by a drainer of
73: the row source which CAN return a row location. Drainer of row source
74: which cannot return rowLocation will guarentee to not call either
75: callbacks. Conversely, if NeedsRowLocation is called and it returns
76: true, then for every row return by getNextRowFromRowSource, a
77: rowLocation callback must also be issued with the row location of the
78: row. Implementor of both the source and the drain of the row source
79: must be aware of this protocol.
80:
81: <BR>
82: The RowLocation object is own by the caller of rowLocation, in other
83: words, the drainer of the RowSource. This is so that we don't need to
84: new a row location for every row. If the Row Source wants to keep the
85: row location, it needs to clone it (RowLocation is a ClonableObject).
86: @exception StandardException on error
87: */
88: void rowLocation(RowLocation rl) throws StandardException;
89: }
|