001 /* FileChannel.java --
002 Copyright (C) 2002 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package java.nio.channels;
039
040 import java.io.IOException;
041 import java.nio.ByteBuffer;
042 import java.nio.MappedByteBuffer;
043 import java.nio.channels.spi.AbstractInterruptibleChannel;
044
045
046 /**
047 * @author Michael Koch
048 * @since 1.4
049 */
050 public abstract class FileChannel extends AbstractInterruptibleChannel
051 implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
052 {
053 public static class MapMode
054 {
055 int m;
056 public static final MapMode READ_ONLY = new MapMode(0);
057 public static final MapMode READ_WRITE = new MapMode(1);
058 public static final MapMode PRIVATE = new MapMode(2);
059
060 /**
061 * Initializes the MapMode.
062 */
063 MapMode(int a)
064 {
065 m = a;
066 }
067
068 /**
069 * Returns a string representation of the <code>MapMode</code> object.
070 */
071 public String toString()
072 {
073 if (this == READ_ONLY)
074 return "READ_ONLY";
075 else if (this == READ_WRITE)
076 return "READ_WRITE";
077
078 return "PRIVATE";
079 }
080 }
081
082 /**
083 * Initializes the channel.
084 */
085 protected FileChannel()
086 {
087 }
088
089 /**
090 * Maps the file into the memory.
091 *
092 * @exception IllegalArgumentException If the preconditions on the parameters
093 * do not hold.
094 * @exception IOException If an I/O error occurs.
095 * @exception NonReadableChannelException If mode is READ_ONLY but this channel was
096 * not opened for reading.
097 * @exception NonWritableChannelException If mode is READ_WRITE or PRIVATE but this
098 * channel was not opened for writing.
099 */
100 public abstract MappedByteBuffer map(MapMode mode, long position, long size)
101 throws IOException;
102
103 /**
104 * Return the size of the file thus far
105 *
106 * @exception ClosedChannelException If this channel is closed.
107 */
108 public abstract long size() throws IOException;
109
110 /**
111 * Writes data to the channel.
112 *
113 * @exception IOException If an I/O error occurs.
114 */
115 public final long write(ByteBuffer[] srcs) throws IOException
116 {
117 return write(srcs, 0, srcs.length);
118 }
119
120 /**
121 * Writes data to the channel.
122 *
123 * @exception IOException If an I/O error occurs.
124 */
125 public abstract int write(ByteBuffer src) throws IOException;
126
127 /**
128 * Writes data to the channel.
129 *
130 * @exception AsynchronousCloseException If another thread closes this channel
131 * while the transfer is in progress.
132 * @exception ClosedByInterruptException If another thread interrupts the
133 * current thread while the transfer is in progress, thereby closing both
134 * channels and setting the current thread's interrupt status.
135 * @exception ClosedChannelException If this channel is closed.
136 * @exception IllegalArgumentException If position is negative.
137 * @exception IOException If an I/O error occurs.
138 * @exception NonWritableChannelException If this channel was not opened for
139 * writing.
140 */
141 public abstract int write(ByteBuffer srcs, long position)
142 throws IOException;
143
144 /**
145 * Writes data to the channel.
146 *
147 * @exception IOException If an I/O error occurs.
148 */
149 public abstract long write(ByteBuffer[] srcs, int offset, int length)
150 throws IOException;
151
152 /**
153 * Reads data from the channel.
154 *
155 * @exception IOException If an I/O error occurs.
156 */
157 public abstract long read(ByteBuffer[] dsts, int offset, int length)
158 throws IOException;
159
160 /**
161 * Reads data from the channel.
162 *
163 * @exception IOException If an I/O error occurs.
164 */
165 public final long read(ByteBuffer[] dsts) throws IOException
166 {
167 return read(dsts, 0, dsts.length);
168 }
169
170 /**
171 * Reads data from the channel.
172 *
173 * @exception IOException If an I/O error occurs.
174 */
175 public abstract int read(ByteBuffer dst) throws IOException;
176
177 /**
178 * Reads data from the channel.
179 *
180 * @exception AsynchronousCloseException If another thread closes this channel
181 * while the transfer is in progress.
182 * @exception ClosedByInterruptException If another thread interrupts the
183 * current thread while the transfer is in progress, thereby closing both
184 * channels and setting the current thread's interrupt status.
185 * @exception ClosedChannelException If this channel is closed.
186 * @exception IllegalArgumentException If position is negative.
187 * @exception IOException If an I/O error occurs.
188 * @exception NonReadableChannelException If this channel was not opened for
189 * reading.
190 */
191 public abstract int read(ByteBuffer dst, long position)
192 throws IOException;
193
194 /**
195 * Closes the channel.
196 *
197 * This is called from @see close.
198 *
199 * @exception IOException If an I/O error occurs.
200 */
201 protected abstract void implCloseChannel() throws IOException;
202
203 /**
204 * msync with the disk
205 *
206 * @exception ClosedChannelException If this channel is closed.
207 * @exception IOException If an I/O error occurs.
208 */
209 public abstract void force(boolean metaData) throws IOException;
210
211 /**
212 * Creates a file lock for the whole associated file.
213 *
214 * @exception AsynchronousCloseException If another thread closes this channel
215 * while the transfer is in progress.
216 * @exception ClosedChannelException If this channel is closed.
217 * @exception FileLockInterruptionException If the invoking thread is
218 * interrupted while blocked in this method.
219 * @exception IOException If an I/O error occurs.
220 * @exception NonReadableChannelException If shared is true and this channel
221 * was not opened for reading.
222 * @exception NonWritableChannelException If shared is false and this channel
223 * was not opened for writing.
224 * @exception OverlappingFileLockException If a lock that overlaps the
225 * requested region is already held by this Java virtual machine, or if
226 * another thread is already blocked in this method and is attempting to lock
227 * an overlapping region.
228 */
229 public final FileLock lock() throws IOException
230 {
231 return lock(0, Long.MAX_VALUE, false);
232 }
233
234 /**
235 * Creates a file lock for a region of the associated file.
236 *
237 * @exception AsynchronousCloseException If another thread closes this channel
238 * while the transfer is in progress.
239 * @exception ClosedChannelException If this channel is closed.
240 * @exception FileLockInterruptionException If the invoking thread is
241 * interrupted while blocked in this method.
242 * @exception IllegalArgumentException If the preconditions on the parameters
243 * do not hold.
244 * @exception IOException If an I/O error occurs.
245 * @exception OverlappingFileLockException If a lock that overlaps the
246 * requested region is already held by this Java virtual machine, or if
247 * another thread is already blocked in this method and is attempting to lock
248 * an overlapping region.
249 * @exception NonReadableChannelException If shared is true and this channel
250 * was not opened for reading.
251 * @exception NonWritableChannelException If shared is false and this channel
252 * was not opened for writing.
253 */
254 public abstract FileLock lock(long position, long size, boolean shared)
255 throws IOException;
256
257 /**
258 * Tries to aqquire alock on the whole associated file.
259 *
260 * @exception ClosedChannelException If this channel is closed.
261 * @exception IOException If an I/O error occurs.
262 * @exception OverlappingFileLockException If a lock that overlaps the
263 * requested region is already held by this Java virtual machine, or if
264 * another thread is already blocked in this method and is attempting to lock
265 * an overlapping region.
266 */
267 public final FileLock tryLock() throws IOException
268 {
269 return tryLock(0, Long.MAX_VALUE, false);
270 }
271
272 /**
273 * Tries to aqquire a lock on a region of the associated file.
274 *
275 * @exception ClosedChannelException If this channel is closed.
276 * @exception IllegalArgumentException If the preconditions on the parameters
277 * do not hold.
278 * @exception IOException If an I/O error occurs.
279 * @exception OverlappingFileLockException If a lock that overlaps the
280 * requested region is already held by this Java virtual machine, or if
281 * another thread is already blocked in this method and is attempting to lock
282 * an overlapping region.
283 */
284 public abstract FileLock tryLock(long position, long size, boolean shared)
285 throws IOException;
286
287 /**
288 * Returns the current position on the file.
289 *
290 * @exception ClosedChannelException If this channel is closed.
291 * @exception IOException If an I/O error occurs.
292 */
293 public abstract long position() throws IOException;
294
295 /**
296 * Sets the position of the channel on the assoziated file.
297 *
298 * @exception ClosedChannelException If this channel is closed.
299 * @exception IllegalArgumentException If newPosition is negative.
300 * @exception IOException If an I/O error occurs.
301 */
302 public abstract FileChannel position(long newPosition)
303 throws IOException;
304
305 /**
306 * Transfers bytes from this channel's file to the given writable byte
307 * channel.
308 *
309 * @exception AsynchronousCloseException If another thread closes this channel
310 * while the transfer is in progress.
311 * @exception ClosedByInterruptException If another thread interrupts the
312 * current thread while the transfer is in progress, thereby closing both
313 * channels and setting the current thread's interrupt status.
314 * @exception ClosedChannelException If this channel is closed.
315 * @exception IllegalArgumentException If the preconditions on the parameters
316 * do not hold.
317 * @exception IOException If an I/O error occurs.
318 * @exception NonReadableChannelException If this channel was not opened for
319 * reading.
320 * @exception NonWritableChannelException If the target channel was not
321 * opened for writing.
322 */
323 public abstract long transferTo(long position, long count,
324 WritableByteChannel target)
325 throws IOException;
326
327 /**
328 * Transfers bytes from the given readable channel into this channel.
329 *
330 * @exception AsynchronousCloseException If another thread closes this channel
331 * while the transfer is in progress.
332 * @exception ClosedByInterruptException If another thread interrupts the
333 * current thread while the transfer is in progress, thereby closing both
334 * channels and setting the current thread's interrupt status.
335 * @exception ClosedChannelException If this channel is closed.
336 * @exception IllegalArgumentException If the preconditions on the parameters
337 * do not hold.
338 * @exception IOException If an I/O error occurs.
339 * @exception NonReadableChannelException If the source channel was not
340 * opened for reading.
341 * @exception NonWritableChannelException If this channel was not opened for
342 * writing.
343 */
344 public abstract long transferFrom(ReadableByteChannel src, long position,
345 long count) throws IOException;
346
347 /**
348 * Truncates the channel's file at <code>size</code>.
349 *
350 * @exception ClosedChannelException If this channel is closed.
351 * @exception IllegalArgumentException If size is negative.
352 * @exception IOException If an I/O error occurs.
353 * @exception NonWritableChannelException If this channel was not opened for
354 * writing.
355 */
356 public abstract FileChannel truncate(long size) throws IOException;
357 }