001: /*
002:
003: Derby - Class org.apache.derby.io.StorageRandomAccessFile
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.io;
023:
024: import java.io.DataInput;
025: import java.io.DataOutput;
026: import java.io.FileNotFoundException;
027: import java.io.EOFException;
028: import java.io.IOException;
029:
030: /**
031: * This interface abstracts an object that implements reading and writing on a random access
032: * file. It extends DataInput and DataOutput, so it implicitly contains all the methods of those
033: * interfaces. Any method in this interface that also appears in the java.io.RandomAccessFile class
034: * should behave as the java.io.RandomAccessFile method does.
035: *<p>
036: * Each StorageRandomAccessFile has an associated file pointer, a byte offset in the file. All reading and writing takes
037: * place at the file pointer offset and advances it.
038: *<p>
039: * An implementation of StorageRandomAccessFile need not be thread safe. The database engine
040: * single-threads access to each StorageRandomAccessFile instance. Two threads will not access the
041: * same StorageRandomAccessFile instance at the same time.
042: *<p>
043: * @see <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/io/RandomAccessFile.html">java.io.RandomAccessFile</a>
044: */
045: public interface StorageRandomAccessFile extends DataInput, DataOutput {
046:
047: /**
048: * Closes this file.
049: *
050: * @exception IOException - if an I/O error occurs.
051: */
052: public void close() throws IOException;
053:
054: /**
055: * Get the current offset in this file.
056: *
057: * @return the current file pointer.
058: *
059: * @exception IOException - if an I/O error occurs.
060: */
061: public long getFilePointer() throws IOException;
062:
063: /**
064: * Gets the length of this file.
065: *
066: * @return the number of bytes this file.
067: *
068: * @exception IOException - if an I/O error occurs.
069: */
070: public long length() throws IOException;
071:
072: /**
073: * Set the file pointer. It may be moved beyond the end of the file, but this does not change
074: * the length of the file. The length of the file is not changed until data is actually written..
075: *
076: * @param newFilePointer the new file pointer, measured in bytes from the beginning of the file.
077: *
078: * @exception IOException - if newFilePointer is less than 0 or an I/O error occurs.
079: */
080: public void seek(long newFilePointer) throws IOException;
081:
082: /**
083: * Sets the length of this file, either extending or truncating it.
084: *<p>
085: * If the file is extended then the contents of the extension are not defined.
086: *<p>
087: * If the file is truncated and the file pointer is greater than the new length then the file pointer
088: * is set to the new length.
089: *
090: * @param newLength The new file length.
091: *
092: * @exception IOException If an I/O error occurs.
093: */
094: public void setLength(long newLength) throws IOException;
095:
096: /**
097: * Force any changes out to the persistent store. If the database is to be transient, that is, if the database
098: * does not survive a restart, then the sync method implementation need not do anything.
099: *
100: * @param metaData If true then this method must force both changes to the file's
101: * contents and metadata to be written to storage; if false, it need only force file content changes
102: * to be written. The implementation is allowed to ignore this parameter and always force out
103: * metadata changes.
104: *
105: * @exception SyncFailedException if a possibly recoverable error occurs.
106: * @exception IOException If an IO error occurs.
107: */
108: public void sync(boolean metaData) throws IOException;
109: }
|