KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.access.RowLocationRetRowSource
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.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     /**
43         needsRowLocation returns true iff this the row source expects the
44         drainer of the row source to call rowLocation after getting a row from
45         getNextRowFromRowSource.
46
47         @return true iff this row source expects some row location to be
48         returned
49         @see #rowLocation
50      */
51     boolean needsRowLocation();
52
53     /**
54         rowLocation is a callback for the drainer of the row source to return
55         the rowLocation of the current row, i.e, the row that is being returned
56         by getNextRowFromRowSource. This interface is for the purpose of
57         loading a base table with index. In that case, the indices can be
58         built at the same time the base table is laid down once the row
59         location of the base row is known. This is an example pseudo code on
60         how this call is expected to be used:
61         
62         <BR><pre>
63         boolean needsRL = rowSource.needsRowLocation();
64         DataValueDescriptor[] row;
65         while((row = rowSource.getNextRowFromRowSource()) != null)
66         {
67             RowLocation rl = heapConglomerate.insertRow(row);
68             if (needsRL)
69                 rowSource.rowLocation(rl);
70         }
71         </pre><BR>
72
73         NeedsRowLocation and rowLocation will ONLY be called by a drainer of
74         the row source which CAN return a row location. Drainer of row source
75         which cannot return rowLocation will guarentee to not call either
76         callbacks. Conversely, if NeedsRowLocation is called and it returns
77         true, then for every row return by getNextRowFromRowSource, a
78         rowLocation callback must also be issued with the row location of the
79         row. Implementor of both the source and the drain of the row source
80         must be aware of this protocol.
81
82         <BR>
83         The RowLocation object is own by the caller of rowLocation, in other
84         words, the drainer of the RowSource. This is so that we don't need to
85         new a row location for every row. If the Row Source wants to keep the
86         row location, it needs to clone it (RowLocation is a ClonableObject).
87         @exception StandardException on error
88      */
89     void rowLocation(RowLocation rl) throws StandardException;
90 }
91
Popular Tags