--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.io.StorageRandomAccessFile\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.io;\r
+\r
+import java.io.DataInput;\r
+import java.io.DataOutput;\r
+import java.io.FileNotFoundException;\r
+import java.io.EOFException;\r
+import java.io.IOException;\r
+\r
+/**\r
+ * This interface abstracts an object that implements reading and writing on a random access\r
+ * file. It extends DataInput and DataOutput, so it implicitly contains all the methods of those\r
+ * interfaces. Any method in this interface that also appears in the java.io.RandomAccessFile class\r
+ * should behave as the java.io.RandomAccessFile method does.\r
+ *<p>\r
+ * Each StorageRandomAccessFile has an associated file pointer, a byte offset in the file. All reading and writing takes\r
+ * place at the file pointer offset and advances it.\r
+ *<p>\r
+ * An implementation of StorageRandomAccessFile need not be thread safe. The database engine\r
+ * single-threads access to each StorageRandomAccessFile instance. Two threads will not access the\r
+ * same StorageRandomAccessFile instance at the same time.\r
+ *<p>\r
+ * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>\r
+ */\r
+public interface StorageRandomAccessFile extends DataInput, DataOutput\r
+{\r
+\r
+ /**\r
+ * Closes this file.\r
+ *\r
+ * @exception IOException - if an I/O error occurs.\r
+ */\r
+ public void close() throws IOException;\r
+\r
+ /**\r
+ * Get the current offset in this file.\r
+ *\r
+ * @return the current file pointer. \r
+ *\r
+ * @exception IOException - if an I/O error occurs.\r
+ */\r
+ public long getFilePointer() throws IOException;\r
+\r
+ /**\r
+ * Gets the length of this file.\r
+ *\r
+ * @return the number of bytes this file. \r
+ *\r
+ * @exception IOException - if an I/O error occurs.\r
+ */\r
+ public long length() throws IOException;\r
+\r
+ /**\r
+ * Set the file pointer. It may be moved beyond the end of the file, but this does not change\r
+ * the length of the file. The length of the file is not changed until data is actually written..\r
+ *\r
+ * @param newFilePointer the new file pointer, measured in bytes from the beginning of the file.\r
+ *\r
+ * @exception IOException - if newFilePointer is less than 0 or an I/O error occurs.\r
+ */\r
+ public void seek(long newFilePointer) throws IOException;\r
+\r
+ /**\r
+ * Sets the length of this file, either extending or truncating it.\r
+ *<p>\r
+ * If the file is extended then the contents of the extension are not defined.\r
+ *<p>\r
+ * If the file is truncated and the file pointer is greater than the new length then the file pointer\r
+ * is set to the new length.\r
+ *\r
+ * @param newLength The new file length.\r
+ *\r
+ * @exception IOException If an I/O error occurs.\r
+ */\r
+ public void setLength(long newLength) throws IOException;\r
+ \r
+ /**\r
+ * Force any changes out to the persistent store. If the database is to be transient, that is, if the database\r
+ * does not survive a restart, then the sync method implementation need not do anything.\r
+ *\r
+ * @param metaData If true then this method must force both changes to the file's\r
+ * contents and metadata to be written to storage; if false, it need only force file content changes\r
+ * to be written. The implementation is allowed to ignore this parameter and always force out\r
+ * metadata changes.\r
+ *\r
+ * @exception SyncFailedException if a possibly recoverable error occurs.\r
+ * @exception IOException If an IO error occurs.\r
+ */\r
+ public void sync( boolean metaData) throws IOException;\r
+\r
+ /**\r
+ * Reads up to <code>len</code> bytes of data from this file into an\r
+ * array of bytes. This method blocks until at least one byte of input\r
+ * is available.\r
+ * <p>\r
+ *\r
+ * @param b the buffer into which the data is read.\r
+ * @param off the start offset in array <code>b</code>\r
+ * at which the data is written.\r
+ * @param len the maximum number of bytes read.\r
+ * @return the total number of bytes read into the buffer, or\r
+ * <code>-1</code> if there is no more data because the end of\r
+ * the file has been reached.\r
+ * @exception IOException If the first byte cannot be read for any reason\r
+ * other than end of file, or if the random access file has been closed, or\r
+ * if some other I/O error occurs.\r
+ * @exception NullPointerException If <code>b</code> is <code>null</code>.\r
+ * @exception IndexOutOfBoundsException If <code>off</code> is negative,\r
+ * <code>len</code> is negative, or <code>len</code> is greater than\r
+ * <code>b.length - off</code>\r
+ */\r
+ public int read(byte[] b, int off, int len) throws IOException;\r
+}\r