001/* FileChannel.java --
002   Copyright (C) 2002 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package java.nio.channels;
039
040import java.io.IOException;
041import java.nio.ByteBuffer;
042import java.nio.MappedByteBuffer;
043import java.nio.channels.spi.AbstractInterruptibleChannel;
044
045
046/**
047 * @author Michael Koch
048 * @since 1.4
049 */
050public 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}