001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.access.RowSource
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.iapi.store.access;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: import org.apache.derby.iapi.types.DataValueDescriptor;
027:
028: import org.apache.derby.iapi.services.io.FormatableBitSet;
029:
030: /**
031:
032: A RowSource is the mechanism for iterating over a set of rows. The RowSource
033: is the interface through which access recieved a set of rows from the client
034: for the purpose of inserting into a single conglomerate.
035:
036: <p>
037: A RowSource can come from many sources - from rows that are from fast path
038: import, to rows coming out of a sort for index creation.
039:
040: */
041: public interface RowSource {
042:
043: /**
044: Get the next row as an array of column objects. The column objects can
045: be a JBMS Storable or any
046: Serializable/Externalizable/Formattable/Streaming type.
047: <BR>
048: A return of null indicates that the complete set of rows has been read.
049:
050: <p>
051: A null column can be specified by leaving the object null, or indicated
052: by returning a non-null getValidColumns. On streaming columns, it can
053: be indicated by returning a non-null get FieldStates.
054:
055: <p>
056: If RowSource.needToClone() is true then the returned row
057: (the DataValueDescriptor[]) is guaranteed not to be modified by drainer
058: of the RowSource (except that the input stream will be read, of course)
059: and drainer will keep no reference to it before making the subsequent
060: nextRow call. So it is safe to return the same DataValueDescriptor[]
061: in subsequent nextRow calls if that is desirable for performance
062: reasons.
063:
064: <p>
065: If RowSource.needToClone() is false then the returned row (the
066: DataValueDescriptor[]) may be be modified by drainer of the RowSource,
067: and the drainer may keep a reference to it after making the subsequent
068: nextRow call. In this case the client should severe all references to
069: the row after returning it from getNextRowFromRowSource().
070:
071: @exception StandardException Cloudscape Standard Error Policy
072: */
073: public DataValueDescriptor[] getNextRowFromRowSource()
074: throws StandardException;
075:
076: /**
077: Does the caller of getNextRowFromRowSource() need to clone the row
078: in order to keep a reference to the row past the
079: getNextRowFromRowSource() call which returned the row. This call
080: must always return the same for all rows in a RowSource (ie. the
081: caller will call this once per scan from a RowSource and assume the
082: behavior is true for all rows in the RowSource).
083:
084: */
085: public boolean needsToClone();
086:
087: /**
088: getValidColumns describes the DataValueDescriptor[] returned by all calls
089: to the getNextRowFromRowSource() call.
090:
091: If getValidColumns returns null, the number of columns is given by the
092: DataValueDescriptor.length where DataValueDescriptor[] is returned by the
093: preceeding getNextRowFromRowSource() call. Column N maps to
094: DataValueDescriptor[N], where column numbers start at zero.
095:
096: If getValidColumns return a non null validColumns FormatableBitSet the number of
097: columns is given by the number of bits set in validColumns. Column N is
098: not in the partial row if validColumns.get(N) returns false. Column N is
099: in the partial row if validColumns.get(N) returns true. If column N is
100: in the partial row then it maps to DataValueDescriptor[M] where M is the
101: count of calls to validColumns.get(i) that return true where i < N. If
102: DataValueDescriptor.length is greater than the number of columns
103: indicated by validColumns the extra entries are ignored.
104: */
105: FormatableBitSet getValidColumns();
106:
107: /**
108: closeRowSource tells the RowSource that it will no longer need to
109: return any rows and it can release any resource it may have.
110: Subsequent call to any method on the RowSource will result in undefined
111: behavior. A closed rowSource can be closed again.
112: */
113: void closeRowSource();
114: }
|