Source for java.nio.channels.FileChannel

   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:     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: }