Adding JMCR-Stable version

[Benchmarks_CSolver.git] / JMCR-Stable / real-world application / MyDerby-10.3 / java / engine / org / apache / derby / iapi / store / access / RowLocationRetRowSource.java

diff --git a/JMCR-Stable/real-world application/MyDerby-10.3/java/engine/org/apache/derby/iapi/store/access/RowLocationRetRowSource.java b/JMCR-Stable/real-world application/MyDerby-10.3/java/engine/org/apache/derby/iapi/store/access/RowLocationRetRowSource.java
new file mode 100644 (file)
index 0000000..60cc095
--- /dev/null
+++ b/JMCR-Stable/real-world application/MyDerby-10.3/java/engine/org/apache/derby/iapi/store/access/RowLocationRetRowSource.java
@@ -0,0 +1,90 @@
+/*\r
+\r
+   Derby - Class org.apache.derby.iapi.store.access.RowLocationRetRowSource\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.types.RowLocation;\r
+\r
+/**\r
+\r
+  A RowLocationRetRowSource is the mechanism for iterating over a set of rows,\r
+  loading those rows into a conglomerate, and returning the RowLocation of the\r
+  inserted rows. \r
+\r
+  @see RowSource\r
+\r
+*/ \r
+public interface RowLocationRetRowSource extends RowSource \r
+{\r
+\r
+       /**\r
+               needsRowLocation returns true iff this the row source expects the\r
+               drainer of the row source to call rowLocation after getting a row from\r
+               getNextRowFromRowSource.\r
+\r
+               @return true iff this row source expects some row location to be\r
+               returned \r
+               @see #rowLocation\r
+        */\r
+       boolean needsRowLocation();\r
+\r
+       /**\r
+               rowLocation is a callback for the drainer of the row source to return\r
+               the rowLocation of the current row, i.e, the row that is being returned\r
+               by getNextRowFromRowSource.  This interface is for the purpose of\r
+               loading a base table with index.  In that case, the indices can be\r
+               built at the same time the base table is laid down once the row\r
+               location of the base row is known.  This is an example pseudo code on\r
+               how this call is expected to be used:\r
+               \r
+               <BR><pre>\r
+               boolean needsRL = rowSource.needsRowLocation();\r
+               DataValueDescriptor[] row;\r
+               while((row = rowSource.getNextRowFromRowSource()) != null)\r
+               {\r
+                       RowLocation rl = heapConglomerate.insertRow(row);\r
+                       if (needsRL)\r
+                               rowSource.rowLocation(rl);\r
+               }\r
+               </pre><BR>\r
+\r
+               NeedsRowLocation and rowLocation will ONLY be called by a drainer of\r
+               the row source which CAN return a row location.  Drainer of row source\r
+               which cannot return rowLocation will guarentee to not call either\r
+               callbacks. Conversely, if NeedsRowLocation is called and it returns\r
+               true, then for every row return by getNextRowFromRowSource, a\r
+               rowLocation callback must also be issued with the row location of the\r
+               row.  Implementor of both the source and the drain of the row source\r
+               must be aware of this protocol.\r
+\r
+               <BR>\r
+               The RowLocation object is own by the caller of rowLocation, in other\r
+               words, the drainer of the RowSource.  This is so that we don't need to\r
+               new a row location for every row.  If the Row Source wants to keep the\r
+               row location, it needs to clone it (RowLocation is a ClonableObject).\r
+               @exception StandardException on error\r
+        */\r
+       void rowLocation(RowLocation rl) throws StandardException;\r
+}\r