001: /*
002: Copyright (C) 2007 Mobixess Inc. http://www.java-objects-database.com
003:
004: This file is part of the JODB (Java Objects Database) open source project.
005:
006: JODB is free software; you can redistribute it and/or modify it under
007: the terms of version 2 of the GNU General Public License as published
008: by the Free Software Foundation.
009:
010: JODB is distributed in the hope that it will be useful, but WITHOUT ANY
011: WARRANTY; without even the implied warranty of MERCHANTABILITY or
012: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013: for more details.
014:
015: You should have received a copy of the GNU General Public License along
016: with this program; if not, write to the Free Software Foundation, Inc.,
017: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
018: */
019: package com.mobixess.jodb.core.io;
020:
021: import java.io.DataInput;
022: import java.io.DataOutput;
023: import java.io.IOException;
024: import java.nio.channels.AsynchronousCloseException;
025: import java.nio.channels.ByteChannel;
026: import java.nio.channels.ClosedByInterruptException;
027: import java.nio.channels.ClosedChannelException;
028: import java.nio.channels.NonReadableChannelException;
029: import java.nio.channels.NonWritableChannelException;
030: import java.nio.channels.ReadableByteChannel;
031: import java.nio.channels.WritableByteChannel;
032:
033: public interface IRandomAccessDataBuffer extends DataInput, DataOutput {
034: void prefetch(long offset) throws IOException;
035:
036: void seek(long pos) throws IOException;
037:
038: long length() throws IOException;
039:
040: void setLength(long newLength) throws IOException;
041:
042: long getCursorOffset() throws IOException;
043:
044: ByteChannel getChannel();
045:
046: void close() throws IOException;
047:
048: void delete() throws IOException;
049:
050: /**
051: * Transfers bytes from this channel's file to the given writable byte
052: * channel.
053: *
054: * <p> An attempt is made to read up to <tt>count</tt> bytes starting at
055: * the given <tt>position</tt> in this channel's file and write them to the
056: * target channel. An invocation of this method may or may not transfer
057: * all of the requested bytes; whether or not it does so depends upon the
058: * natures and states of the channels. Fewer than the requested number of
059: * bytes are transferred if this channel's file contains fewer than
060: * <tt>count</tt> bytes starting at the given <tt>position</tt>, or if the
061: * target channel is non-blocking and it has fewer than <tt>count</tt>
062: * bytes free in its output buffer.
063: *
064: * <p> This method does not modify this channel's position. If the given
065: * position is greater than the file's current size then no bytes are
066: * transferred. If the target channel has a position then bytes are
067: * written starting at that position and then the position is incremented
068: * by the number of bytes written.
069: *
070: * <p> This method is potentially much more efficient than a simple loop
071: * that reads from this channel and writes to the target channel. Many
072: * operating systems can transfer bytes directly from the filesystem cache
073: * to the target channel without actually copying them. </p>
074: *
075: * @param position
076: * The position within the file at which the transfer is to begin;
077: * must be non-negative
078: *
079: * @param count
080: * The maximum number of bytes to be transferred; must be
081: * non-negative
082: *
083: * @param target
084: * The target channel
085: *
086: * @return The number of bytes, possibly zero,
087: * that were actually transferred
088: *
089: * @throws IllegalArgumentException
090: * If the preconditions on the parameters do not hold
091: *
092: * @throws NonReadableChannelException
093: * If this channel was not opened for reading
094: *
095: * @throws NonWritableChannelException
096: * If the target channel was not opened for writing
097: *
098: * @throws ClosedChannelException
099: * If either this channel or the target channel is closed
100: *
101: * @throws AsynchronousCloseException
102: * If another thread closes either channel
103: * while the transfer is in progress
104: *
105: * @throws ClosedByInterruptException
106: * If another thread interrupts the current thread while the
107: * transfer is in progress, thereby closing both channels and
108: * setting the current thread's interrupt status
109: *
110: * @throws IOException
111: * If some other I/O error occurs
112: */
113: long transferTo(long position, long count,
114: WritableByteChannel target) throws IOException;
115:
116: /**
117: * Transfers bytes into this channel's file from the given readable byte
118: * channel.
119: *
120: * <p> An attempt is made to read up to <tt>count</tt> bytes from the
121: * source channel and write them to this channel's file starting at the
122: * given <tt>position</tt>. An invocation of this method may or may not
123: * transfer all of the requested bytes; whether or not it does so depends
124: * upon the natures and states of the channels. Fewer than the requested
125: * number of bytes will be transferred if the source channel has fewer than
126: * <tt>count</tt> bytes remaining, or if the source channel is non-blocking
127: * and has fewer than <tt>count</tt> bytes immediately available in its
128: * input buffer.
129: *
130: * <p> This method does not modify this channel's position. If the given
131: * position is greater than the file's current size then no bytes are
132: * transferred. If the source channel has a position then bytes are read
133: * starting at that position and then the position is incremented by the
134: * number of bytes read.
135: *
136: * <p> This method is potentially much more efficient than a simple loop
137: * that reads from the source channel and writes to this channel. Many
138: * operating systems can transfer bytes directly from the source channel
139: * into the filesystem cache without actually copying them. </p>
140: *
141: * @param src
142: * The source channel
143: *
144: * @param position
145: * The position within the file at which the transfer is to begin;
146: * must be non-negative
147: *
148: * @param count
149: * The maximum number of bytes to be transferred; must be
150: * non-negative
151: *
152: * @return The number of bytes, possibly zero,
153: * that were actually transferred
154: *
155: * @throws IllegalArgumentException
156: * If the preconditions on the parameters do not hold
157: *
158: * @throws NonReadableChannelException
159: * If the source channel was not opened for reading
160: *
161: * @throws NonWritableChannelException
162: * If this channel was not opened for writing
163: *
164: * @throws ClosedChannelException
165: * If either this channel or the source channel is closed
166: *
167: * @throws AsynchronousCloseException
168: * If another thread closes either channel
169: * while the transfer is in progress
170: *
171: * @throws ClosedByInterruptException
172: * If another thread interrupts the current thread while the
173: * transfer is in progress, thereby closing both channels and
174: * setting the current thread's interrupt status
175: *
176: * @throws IOException
177: * If some other I/O error occurs
178: */
179: long transferFrom(ReadableByteChannel src, long position, long count)
180: throws IOException;
181:
182: void resetToStart() throws IOException;
183:
184: void resetToEnd() throws IOException;
185:
186: void read(byte[] b, int off, int len) throws IOException;
187:
188: long skip(long n) throws IOException;
189: }
|