--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.access.RowSource\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.access;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.iapi.types.DataValueDescriptor;\r
+\r
+import org.apache.derby.iapi.services.io.FormatableBitSet;\r
+\r
+/**\r
+\r
+ A RowSource is the mechanism for iterating over a set of rows. The RowSource\r
+ is the interface through which access recieved a set of rows from the client\r
+ for the purpose of inserting into a single conglomerate.\r
+\r
+ <p>\r
+ A RowSource can come from many sources - from rows that are from fast path\r
+ import, to rows coming out of a sort for index creation.\r
+\r
+*/ \r
+public interface RowSource {\r
+\r
+ /**\r
+ Get the next row as an array of column objects. The column objects can\r
+ be a JBMS Storable or any\r
+ Serializable/Externalizable/Formattable/Streaming type.\r
+ <BR>\r
+ A return of null indicates that the complete set of rows has been read.\r
+\r
+ <p>\r
+ A null column can be specified by leaving the object null, or indicated\r
+ by returning a non-null getValidColumns. On streaming columns, it can\r
+ be indicated by returning a non-null get FieldStates.\r
+\r
+ <p>\r
+ If RowSource.needToClone() is true then the returned row \r
+ (the DataValueDescriptor[]) is guaranteed not to be modified by drainer\r
+ of the RowSource (except that the input stream will be read, of course) \r
+ and drainer will keep no reference to it before making the subsequent \r
+ nextRow call. So it is safe to return the same DataValueDescriptor[] \r
+ in subsequent nextRow calls if that is desirable for performance \r
+ reasons. \r
+\r
+ <p>\r
+ If RowSource.needToClone() is false then the returned row (the \r
+ DataValueDescriptor[]) may be be modified by drainer of the RowSource, \r
+ and the drainer may keep a reference to it after making the subsequent \r
+ nextRow call. In this case the client should severe all references to \r
+ the row after returning it from getNextRowFromRowSource().\r
+\r
+ @exception StandardException Standard Derby Error Policy\r
+ */\r
+ public DataValueDescriptor[] getNextRowFromRowSource() \r
+ throws StandardException;\r
+\r
+ /**\r
+ Does the caller of getNextRowFromRowSource() need to clone the row\r
+ in order to keep a reference to the row past the \r
+ getNextRowFromRowSource() call which returned the row. This call\r
+ must always return the same for all rows in a RowSource (ie. the\r
+ caller will call this once per scan from a RowSource and assume the\r
+ behavior is true for all rows in the RowSource).\r
+\r
+ */\r
+ public boolean needsToClone();\r
+\r
+ /**\r
+ getValidColumns describes the DataValueDescriptor[] returned by all calls\r
+ to the getNextRowFromRowSource() call. \r
+\r
+ If getValidColumns returns null, the number of columns is given by the\r
+ DataValueDescriptor.length where DataValueDescriptor[] is returned by the\r
+ preceeding getNextRowFromRowSource() call. Column N maps to \r
+ DataValueDescriptor[N], where column numbers start at zero.\r
+\r
+ If getValidColumns return a non null validColumns FormatableBitSet the number of\r
+ columns is given by the number of bits set in validColumns. Column N is\r
+ not in the partial row if validColumns.get(N) returns false. Column N is\r
+ in the partial row if validColumns.get(N) returns true. If column N is\r
+ in the partial row then it maps to DataValueDescriptor[M] where M is the \r
+ count of calls to validColumns.get(i) that return true where i < N. If\r
+ DataValueDescriptor.length is greater than the number of columns \r
+ indicated by validColumns the extra entries are ignored. \r
+ */\r
+ FormatableBitSet getValidColumns(); \r
+\r
+ /**\r
+ closeRowSource tells the RowSource that it will no longer need to\r
+ return any rows and it can release any resource it may have.\r
+ Subsequent call to any method on the RowSource will result in undefined\r
+ behavior. A closed rowSource can be closed again.\r
+ */\r
+ void closeRowSource();\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff