gomp-20050608-branch/libjava/classpath/java/nio/channels/FileChannel.java

   1 /* FileChannel.java --
   2    Copyright (C) 2002 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.nio.channels;
  39
  40 import java.io.IOException;
  41 import java.nio.ByteBuffer;
  42 import java.nio.MappedByteBuffer;
  43 import java.nio.channels.spi.AbstractInterruptibleChannel;
  44
  45
  46 /**
  47  * @author Michael Koch
  48  * @since 1.4
  49  */
  50 public abstract class FileChannel extends AbstractInterruptibleChannel
  51   implements ByteChannel, GatheringByteChannel, ScatteringByteChannel
  52 {
  53   public static class MapMode
  54   {
  55     int m;
  56     public static final MapMode READ_ONLY = new MapMode(0);
  57     public static final MapMode READ_WRITE = new MapMode(1);
  58     public static final MapMode PRIVATE = new MapMode(2);
  59
  60     /**
  61      * Initializes the MapMode.
  62      */
  63     MapMode(int a)
  64     {
  65       m = a;
  66     }
  67
  68     /**
  69      * Returns a string representation of the <code>MapMode</code> object.
  70      */
  71     public String toString()
  72     {
  73       if (this == READ_ONLY)
  74         return "READ_ONLY";
  75       else if (this == READ_WRITE)
  76         return "READ_WRITE";
  77
  78       return "PRIVATE";
  79     }
  80   }
  81
  82   /**
  83    * Initializes the channel.
  84    */
  85   protected FileChannel()
  86   {
  87   }
  88
  89   /**
  90    * Maps the file into the memory.
  91    *
  92    * @exception IllegalArgumentException If the preconditions on the parameters
  93    * do not hold.
  94    * @exception IOException If an I/O error occurs.
  95    * @exception NonReadableChannelException If mode is READ_ONLY but this channel was
  96    * not opened for reading.
  97    * @exception NonWritableChannelException If mode is READ_WRITE or PRIVATE but this
  98    * channel was not opened for writing.
  99    */
 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     long result = 0;
 118
 119     for (int i = 0; i < srcs.length; i++)
 120       result += write(srcs[i]);
 121
 122     return result;
 123   }
 124
 125   /**
 126    * Writes data to the channel.
 127    *
 128    * @exception IOException If an I/O error occurs.
 129    */
 130   public abstract int write(ByteBuffer src) throws IOException;
 131
 132   /**
 133    * Writes data to the channel.
 134    *
 135    * @exception AsynchronousCloseException If another thread closes this channel
 136    * while the transfer is in progress.
 137    * @exception ClosedByInterruptException If another thread interrupts the
 138    * current thread while the transfer is in progress, thereby closing both
 139    * channels and setting the current thread's interrupt status.
 140    * @exception ClosedChannelException If this channel is closed.
 141    * @exception IllegalArgumentException If position is negative.
 142    * @exception IOException If an I/O error occurs.
 143    * @exception NonWritableChannelException If this channel was not opened for
 144    * writing.
 145    */
 146   public abstract int write(ByteBuffer srcs, long position)
 147     throws IOException;
 148
 149   /**
 150    * Writes data to the channel.
 151    *
 152    * @exception IOException If an I/O error occurs.
 153    */
 154   public abstract long write(ByteBuffer[] srcs, int offset, int length)
 155     throws IOException;
 156
 157   /**
 158    * Reads data from the channel.
 159    *
 160    * @exception IOException If an I/O error occurs.
 161    */
 162   public abstract long read(ByteBuffer[] dsts, int offset, int length)
 163     throws IOException;
 164
 165   /**
 166    * Reads data from the channel.
 167    *
 168    * @exception IOException If an I/O error occurs.
 169    */
 170   public final long read(ByteBuffer[] dsts) throws IOException
 171   {
 172     long result = 0;
 173
 174     for (int i = 0; i < dsts.length; i++)
 175       read(dsts[i]);
 176
 177     return result;
 178   }
 179
 180   /**
 181    * Reads data from the channel.
 182    *
 183    * @exception IOException If an I/O error occurs.
 184    */
 185   public abstract int read(ByteBuffer dst) throws IOException;
 186
 187   /**
 188    * Reads data from the channel.
 189    *
 190    * @exception AsynchronousCloseException If another thread closes this channel
 191    * while the transfer is in progress.
 192    * @exception ClosedByInterruptException If another thread interrupts the
 193    * current thread while the transfer is in progress, thereby closing both
 194    * channels and setting the current thread's interrupt status.
 195    * @exception ClosedChannelException If this channel is closed.
 196    * @exception IllegalArgumentException If position is negative.
 197    * @exception IOException If an I/O error occurs.
 198    * @exception NonReadableChannelException If this channel was not opened for
 199    * reading.
 200    */
 201   public abstract int read(ByteBuffer dst, long position)
 202     throws IOException;
 203
 204   /**
 205    * Closes the channel.
 206    *
 207    * This is called from @see close.
 208    *
 209    * @exception IOException If an I/O error occurs.
 210    */
 211   protected abstract void implCloseChannel() throws IOException;
 212
 213   /**
 214    * msync with the disk
 215    *
 216    * @exception ClosedChannelException If this channel is closed.
 217    * @exception IOException If an I/O error occurs.
 218    */
 219   public abstract void force(boolean metaData) throws IOException;
 220
 221   /**
 222    * Creates a file lock for the whole assoziated file.
 223    *
 224    * @exception AsynchronousCloseException If another thread closes this channel
 225    * while the transfer is in progress.
 226    * @exception ClosedChannelException If this channel is closed.
 227    * @exception FileLockInterruptionException If the invoking thread is
 228    * interrupted while blocked in this method.
 229    * @exception IOException If an I/O error occurs.
 230    * @exception NonReadableChannelException If shared is true and this channel
 231    * was not opened for reading.
 232    * @exception NonWritableChannelException If shared is false and this channel
 233    * was not opened for writing.
 234    * @exception OverlappingFileLockException If a lock that overlaps the
 235    * requested region is already held by this Java virtual machine, or if
 236    * another thread is already blocked in this method and is attempting to lock
 237    * an overlapping region.
 238    */
 239   public final FileLock lock() throws IOException
 240   {
 241     return lock(0, Long.MAX_VALUE, false);
 242   }
 243
 244   /**
 245    * Creates a file lock for a region of the assoziated file.
 246    *
 247    * @exception AsynchronousCloseException If another thread closes this channel
 248    * while the transfer is in progress.
 249    * @exception ClosedChannelException If this channel is closed.
 250    * @exception FileLockInterruptionException If the invoking thread is
 251    * interrupted while blocked in this method.
 252    * @exception IllegalArgumentException If the preconditions on the parameters
 253    * do not hold.
 254    * @exception IOException If an I/O error occurs.
 255    * @exception OverlappingFileLockException If a lock that overlaps the
 256    * requested region is already held by this Java virtual machine, or if
 257    * another thread is already blocked in this method and is attempting to lock
 258    * an overlapping region.
 259    * @exception NonReadableChannelException If shared is true and this channel
 260    * was not opened for reading.
 261    * @exception NonWritableChannelException If shared is false and this channel
 262    * was not opened for writing.
 263    */
 264   public abstract FileLock lock(long position, long size, boolean shared)
 265     throws IOException;
 266
 267   /**
 268    * Tries to aqquire alock on the whole assoziated file.
 269    *
 270    * @exception ClosedChannelException If this channel is closed.
 271    * @exception IOException If an I/O error occurs.
 272    * @exception OverlappingFileLockException If a lock that overlaps the
 273    * requested region is already held by this Java virtual machine, or if
 274    * another thread is already blocked in this method and is attempting to lock
 275    * an overlapping region.
 276    */
 277   public final FileLock tryLock() throws IOException
 278   {
 279     return tryLock(0, Long.MAX_VALUE, false);
 280   }
 281
 282   /**
 283    * Tries to aqquire a lock on a region of the assoziated file.
 284    *
 285    * @exception ClosedChannelException If this channel is closed.
 286    * @exception IllegalArgumentException If the preconditions on the parameters
 287    * do not hold.
 288    * @exception IOException If an I/O error occurs.
 289    * @exception OverlappingFileLockException If a lock that overlaps the
 290    * requested region is already held by this Java virtual machine, or if
 291    * another thread is already blocked in this method and is attempting to lock
 292    * an overlapping region.
 293    */
 294   public abstract FileLock tryLock(long position, long size, boolean shared)
 295     throws IOException;
 296
 297   /**
 298    * Returns the current position on the file.
 299    *
 300    * @exception ClosedChannelException If this channel is closed.
 301    * @exception IOException If an I/O error occurs.
 302    */
 303   public abstract long position() throws IOException;
 304
 305   /**
 306    * Sets the position of the channel on the assoziated file.
 307    *
 308    * @exception ClosedChannelException If this channel is closed.
 309    * @exception IllegalArgumentException If newPosition is negative.
 310    * @exception IOException If an I/O error occurs.
 311    */
 312   public abstract FileChannel position(long newPosition)
 313     throws IOException;
 314
 315   /**
 316    * Transfers bytes from this channel's file to the given writable byte
 317    * channel.
 318    *
 319    * @exception AsynchronousCloseException If another thread closes this channel
 320    * while the transfer is in progress.
 321    * @exception ClosedByInterruptException If another thread interrupts the
 322    * current thread while the transfer is in progress, thereby closing both
 323    * channels and setting the current thread's interrupt status.
 324    * @exception ClosedChannelException If this channel is closed.
 325    * @exception IllegalArgumentException If the preconditions on the parameters
 326    * do not hold.
 327    * @exception IOException If an I/O error occurs.
 328    * @exception NonReadableChannelException If this channel was not opened for
 329    * reading.
 330    * @exception NonWritableChannelException If the target channel was not
 331    * opened for writing.
 332    */
 333   public abstract long transferTo(long position, long count,
 334                                   WritableByteChannel target)
 335     throws IOException;
 336
 337   /**
 338    * Transfers bytes from the given readable channel into this channel.
 339    *
 340    * @exception AsynchronousCloseException If another thread closes this channel
 341    * while the transfer is in progress.
 342    * @exception ClosedByInterruptException If another thread interrupts the
 343    * current thread while the transfer is in progress, thereby closing both
 344    * channels and setting the current thread's interrupt status.
 345    * @exception ClosedChannelException If this channel is closed.
 346    * @exception IllegalArgumentException If the preconditions on the parameters
 347    * do not hold.
 348    * @exception IOException If an I/O error occurs.
 349    * @exception NonReadableChannelException If the source channel was not
 350    * opened for reading.
 351    * @exception NonWritableChannelException If this channel was not opened for
 352    * writing.
 353    */
 354   public abstract long transferFrom(ReadableByteChannel src, long position,
 355                                     long count) throws IOException;
 356
 357   /**
 358    * Truncates the channel's file at <code>size</code>.
 359    *
 360    * @exception ClosedChannelException If this channel is closed.
 361    * @exception IllegalArgumentException If size is negative.
 362    * @exception IOException If an I/O error occurs.
 363    * @exception NonWritableChannelException If this channel was not opened for
 364    * writing.
 365    */
 366   public abstract FileChannel truncate(long size) throws IOException;
 367 }