1 /* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package java.nio.channels; 18 19 import java.io.IOException; 20 import java.nio.ByteBuffer; 21 import java.nio.MappedByteBuffer; 22 import java.nio.channels.spi.AbstractInterruptibleChannel; 23 24 /** 25 * An abstract channel type for interaction with a platform file. 26 * <p> 27 * A {@code FileChannel} defines the methods for reading, writing, memory 28 * mapping, and manipulating the logical state of a platform file. This type 29 * does not have a method for opening files, since this behavior has been 30 * delegated to the {@link java.io.FileInputStream}, 31 * {@link java.io.FileOutputStream} and {@link java.io.RandomAccessFile} types. 32 * <p> 33 * FileChannels created from a {@code FileInputStream} or a 34 * {@code RandomAccessFile} created in mode "r", are read-only. FileChannels 35 * created from a {@code FileOutputStream} are write-only. FileChannels created 36 * from a {@code RandomAccessFile} created in mode "rw" are read/write. 37 * FileChannels created from a {@code RandomAccessFile} that was opened in 38 * append-mode will also be in append-mode -- meaning that each write will be 39 * proceeded by a seek to the end of file. 40 * <p> 41 * FileChannels have a virtual pointer into the file which is referred to as a 42 * file <em>position</em>. The position can be manipulated by moving it 43 * within the file, and the current position can be queried. 44 * <p> 45 * FileChannels also have an associated <em>size</em>. The size of the file 46 * is the number of bytes that it currently contains. The size can be 47 * manipulated by adding more bytes to the end of the file (which increases the 48 * size) or truncating the file (which decreases the size). The current size can 49 * also be queried. 50 * <p> 51 * FileChannels have operations beyond the simple read, write, and close. They 52 * can also: 53 * <ul> 54 * <li>request that cached data be forced onto the disk,</li> 55 * <li>lock ranges of bytes associated with the file,</li> 56 * <li>transfer data directly to another channel in a manner that has the 57 * potential to be optimized by the platform,</li> 58 * <li>memory-mapping files into NIO buffers to provide efficient manipulation 59 * of file data,</li> 60 * <li>read and write to the file at absolute byte offsets in a fashion that 61 * does not modify the current position.</li> 62 * </ul> 63 * <p> 64 * FileChannels are thread-safe. Only one operation involving manipulation of 65 * the file position may be executed at the same time. Subsequent calls to such 66 * operations will block, and one of those blocked will be freed to continue 67 * when the first operation has completed. There is no ordered queue or fairness 68 * applied to the blocked threads. 69 * <p> 70 * It is undefined whether operations that do not manipulate the file position 71 * will also block when there are any other operations in-flight. 72 * <p> 73 * The logical view of the underlying file is consistent across all FileChannels 74 * and I/O streams opened on the same file by the same VM. 75 * Therefore, modifications performed via a channel will be visible to the 76 * stream and vice versa; this includes modifications to the file position, 77 * content, size, etc. 78 */ 79 public abstract class FileChannel extends AbstractInterruptibleChannel 80 implements ByteChannel, GatheringByteChannel, ScatteringByteChannel { 81 82 /** 83 * {@code MapMode} defines file mapping mode constants. 84 */ 85 public static class MapMode { 86 /** 87 * Private mapping mode (equivalent to copy on write). 88 */ 89 public static final MapMode PRIVATE = new MapMode("PRIVATE"); 90 91 /** 92 * Read-only mapping mode. 93 */ 94 public static final MapMode READ_ONLY = new MapMode("READ_ONLY"); 95 96 /** 97 * Read-write mapping mode. 98 */ 99 public static final MapMode READ_WRITE = new MapMode("READ_WRITE"); 100 101 // The string used to display the mapping mode. 102 private final String displayName; 103 104 /* 105 * Private constructor prevents others creating new modes. 106 */ MapMode(String displayName)107 private MapMode(String displayName) { 108 this.displayName = displayName; 109 } 110 111 /** 112 * Returns a string version of the mapping mode. 113 * 114 * @return this map mode as string. 115 */ 116 @Override toString()117 public String toString() { 118 return displayName; 119 } 120 } 121 122 /** 123 * Protected default constructor. 124 */ FileChannel()125 protected FileChannel() { 126 } 127 128 /** 129 * Requests that all updates to this channel are committed to the storage 130 * device. 131 * <p> 132 * When this method returns, all modifications made to the platform file 133 * underlying this channel have been committed if the file resides on a 134 * local storage device. If the file is not hosted locally, for example on a 135 * networked file system, then applications cannot be certain that the 136 * modifications have been committed. 137 * <p> 138 * There are no assurances given that changes made to the file using methods 139 * defined elsewhere will be committed. For example, changes made via a 140 * mapped byte buffer may not be committed. 141 * <p> 142 * The <code>metadata</code> parameter indicates whether the update should 143 * include the file's metadata such as last modification time, last access 144 * time, etc. Note that passing <code>true</code> may invoke an underlying 145 * write to the operating system (if the platform is maintaining metadata 146 * such as last access time), even if the channel is opened read-only. 147 * 148 * @param metadata 149 * {@code true} if the file metadata should be flushed in 150 * addition to the file content, {@code false} otherwise. 151 * @throws ClosedChannelException 152 * if this channel is already closed. 153 * @throws IOException 154 * if another I/O error occurs. 155 */ force(boolean metadata)156 public abstract void force(boolean metadata) throws IOException; 157 158 /** 159 * Obtains an exclusive lock on this file. 160 * <p> 161 * This is a convenience method for acquiring a maximum length lock on a 162 * file. It is equivalent to: 163 * {@code fileChannel.lock(0L, Long.MAX_VALUE, false);} 164 * 165 * @return the lock object representing the locked file area. 166 * @throws ClosedChannelException 167 * the file channel is closed. 168 * @throws NonWritableChannelException 169 * this channel was not opened for writing. 170 * @throws OverlappingFileLockException 171 * either a lock is already held that overlaps this lock 172 * request, or another thread is waiting to acquire a lock that 173 * will overlap with this request. 174 * @throws FileLockInterruptionException 175 * the calling thread was interrupted while waiting to acquire 176 * the lock. 177 * @throws AsynchronousCloseException 178 * the channel was closed while the calling thread was waiting 179 * to acquire the lock. 180 * @throws IOException 181 * if another I/O error occurs while obtaining the requested 182 * lock. 183 */ lock()184 public final FileLock lock() throws IOException { 185 return lock(0L, Long.MAX_VALUE, false); 186 } 187 188 /** 189 * Obtains a lock on a specified region of the file. 190 * <p> 191 * This is the blocking version of lock acquisition, see also the 192 * <code>tryLock()</code> methods. 193 * <p> 194 * Attempts to acquire an overlapping lock region will fail. The attempt 195 * will fail if the overlapping lock has already been obtained, or if 196 * another thread is currently waiting to acquire the overlapping lock. 197 * <p> 198 * If the request is not for an overlapping lock, the thread calling this 199 * method will block until the lock is obtained (likely by no contention or 200 * another process releasing a lock), or until this thread is interrupted or 201 * the channel is closed. 202 * <p> 203 * If the lock is obtained successfully then the {@link FileLock} object 204 * returned represents the lock for subsequent operations on the locked 205 * region. 206 * <p> 207 * If the thread is interrupted while waiting for the lock, the thread is 208 * set to the interrupted state and throws a 209 * {@link FileLockInterruptionException}. If this channel is closed while 210 * the thread is waiting to obtain the lock then the thread throws a 211 * {@link AsynchronousCloseException}. 212 * <p> 213 * There is no requirement for the position and size to be within the 214 * current start and length of the file. 215 * <p> 216 * Some platforms do not support shared locks, and if a request is made for 217 * a shared lock on such a platform, this method will attempt to acquire an 218 * exclusive lock instead. It is undefined whether the lock obtained is 219 * advisory or mandatory. 220 * 221 * @param position 222 * the starting position for the locked region. 223 * @param size 224 * the length of the locked region in bytes. 225 * @param shared 226 * a flag indicating whether an attempt should be made to acquire 227 * a shared lock. 228 * @return the file lock object. 229 * @throws IllegalArgumentException 230 * if {@code position} or {@code size} is negative. 231 * @throws ClosedChannelException 232 * if this channel is closed. 233 * @throws OverlappingFileLockException 234 * if the requested region overlaps an existing lock or pending 235 * lock request. 236 * @throws NonReadableChannelException 237 * if the channel is not opened in read-mode but shared is true. 238 * @throws NonWritableChannelException 239 * if the channel is not opened in write mode but shared is 240 * false. 241 * @throws AsynchronousCloseException 242 * if this channel is closed by another thread while this method 243 * is executing. 244 * @throws FileLockInterruptionException 245 * if the thread is interrupted while in the state of waiting on 246 * the desired file lock. 247 * @throws IOException 248 * if another I/O error occurs. 249 */ lock(long position, long size, boolean shared)250 public abstract FileLock lock(long position, long size, boolean shared) 251 throws IOException; 252 253 /** 254 * Maps the file into memory. There can be three modes: read-only, 255 * read/write and private. After mapping, changes made to memory or the file 256 * channel do not affect the other storage place. 257 * <p> 258 * Note: mapping a file into memory is usually expensive. 259 * 260 * @param mode 261 * one of the three mapping modes. 262 * @param position 263 * the starting position of the file. 264 * @param size 265 * the size of the region to map into memory. 266 * @return the mapped byte buffer. 267 * @throws NonReadableChannelException 268 * if the FileChannel is not opened for reading but the given 269 * mode is "READ_ONLY". 270 * @throws NonWritableChannelException 271 * if the FileChannel is not opened for writing but the given 272 * mode is not "READ_ONLY". 273 * @throws IllegalArgumentException 274 * if the given parameters of position and size are not correct. 275 * Both must be non negative. {@code size} also must not be 276 * bigger than max integer. 277 * @throws IOException 278 * if any I/O error occurs. 279 */ map(FileChannel.MapMode mode, long position, long size)280 public abstract MappedByteBuffer map(FileChannel.MapMode mode, 281 long position, long size) throws IOException; 282 283 /** 284 * Returns the current position as a positive integer number of bytes from 285 * the start of the file. 286 * 287 * @throws ClosedChannelException 288 * if this channel is closed. 289 * @throws IOException 290 * if another I/O error occurs. 291 */ position()292 public abstract long position() throws IOException; 293 294 /** 295 * Sets the file position pointer to a new value. 296 * <p> 297 * The argument is the number of bytes counted from the start of the file. 298 * The position cannot be set to a value that is negative. The new position 299 * can be set beyond the current file size. If set beyond the current file 300 * size, attempts to read will return end of file. Write operations will 301 * succeed but they will fill the bytes between the current end of file and 302 * the new position with the required number of (unspecified) byte values. 303 * 304 * @return this. 305 * @throws IllegalArgumentException 306 * if the new position is negative. 307 * @throws ClosedChannelException 308 * if this channel is closed. 309 * @throws IOException 310 * if another I/O error occurs. 311 */ position(long newPosition)312 public abstract FileChannel position(long newPosition) throws IOException; 313 314 /** 315 * Reads bytes from this file channel into the given buffer. 316 * <p> 317 * The maximum number of bytes that will be read is the remaining number of 318 * bytes in the buffer when the method is invoked. The bytes will be copied 319 * into the buffer starting at the buffer's current position. 320 * <p> 321 * The call may block if other threads are also attempting to read from this 322 * channel. 323 * <p> 324 * Upon completion, the buffer's position is set to the end of the bytes 325 * that have been read. The buffer's limit is not changed. 326 * 327 * @param buffer 328 * the byte buffer to receive the bytes. 329 * @return the number of bytes actually read. 330 * @throws AsynchronousCloseException 331 * if another thread closes the channel during the read. 332 * @throws ClosedByInterruptException 333 * if another thread interrupts the calling thread during the 334 * read. 335 * @throws ClosedChannelException 336 * if this channel is closed. 337 * @throws IOException 338 * if another I/O error occurs, details are in the message. 339 * @throws NonReadableChannelException 340 * if the channel has not been opened in a mode that permits 341 * reading. 342 */ read(ByteBuffer buffer)343 public abstract int read(ByteBuffer buffer) throws IOException; 344 345 /** 346 * Reads bytes from this file channel into the given buffer starting from 347 * the specified file position. 348 * <p> 349 * The bytes are read starting at the given file position (up to the 350 * remaining number of bytes in the buffer). The number of bytes actually 351 * read is returned. 352 * <p> 353 * If {@code position} is beyond the current end of file, then no bytes are 354 * read. 355 * <p> 356 * Note that the file position is unmodified by this method. 357 * 358 * @param buffer 359 * the buffer to receive the bytes. 360 * @param position 361 * the (non-negative) position at which to read the bytes. 362 * @return the number of bytes actually read, or -1 if the end of the file has been reached. 363 * @throws AsynchronousCloseException 364 * if this channel is closed by another thread while this method 365 * is executing. 366 * @throws ClosedByInterruptException 367 * if another thread interrupts the calling thread while this 368 * operation is in progress. The calling thread will have the 369 * interrupt state set, and the channel will be closed. 370 * @throws ClosedChannelException 371 * if this channel is closed. 372 * @throws IllegalArgumentException 373 * if <code>position</code> is less than 0. 374 * @throws IOException 375 * if another I/O error occurs. 376 * @throws NonReadableChannelException 377 * if the channel has not been opened in a mode that permits 378 * reading. 379 */ read(ByteBuffer buffer, long position)380 public abstract int read(ByteBuffer buffer, long position) 381 throws IOException; 382 383 /** 384 * Reads bytes from this file channel and stores them in the specified array 385 * of buffers. This method attempts to read as many bytes as can be stored 386 * in the buffer array from this channel and returns the number of bytes 387 * actually read. It also increases the file position by the number of bytes 388 * read. 389 * <p> 390 * If a read operation is in progress, subsequent threads will block until 391 * the read is completed and will then contend for the ability to read. 392 * <p> 393 * Calling this method is equivalent to calling 394 * {@code read(buffers, 0, buffers.length);} 395 * 396 * @param buffers 397 * the array of byte buffers into which the bytes will be copied. 398 * @return the number of bytes actually read, or -1 if the end of the file has been reached. 399 * @throws AsynchronousCloseException 400 * if this channel is closed by another thread during this read 401 * operation. 402 * @throws ClosedByInterruptException 403 * if the thread is interrupted by another thread during this 404 * read operation. 405 * @throws ClosedChannelException 406 * if this channel is closed. 407 * @throws IOException 408 * if another I/O error occurs; details are in the message. 409 * @throws NonReadableChannelException 410 * if the channel has not been opened in a mode that permits 411 * reading. 412 */ 413 @Override read(ByteBuffer[] buffers)414 public final long read(ByteBuffer[] buffers) throws IOException { 415 return read(buffers, 0, buffers.length); 416 } 417 418 /** 419 * Reads bytes from this file channel into a subset of the given buffers. 420 * This method attempts to read all {@code remaining()} bytes from {@code 421 * length} byte buffers, in order, starting at {@code targets[offset]}. It 422 * increases the file position by the number of bytes actually read. The 423 * number of bytes actually read is returned. 424 * <p> 425 * If a read operation is in progress, subsequent threads will block until 426 * the read is completed and will then contend for the ability to read. 427 * 428 * @param buffers 429 * the array of byte buffers into which the bytes will be copied. 430 * @param start 431 * the index of the first buffer to store bytes in. 432 * @param number 433 * the maximum number of buffers to store bytes in. 434 * @return the number of bytes actually read, or -1 if the end of the file has been reached. 435 * @throws AsynchronousCloseException 436 * if this channel is closed by another thread during this read 437 * operation. 438 * @throws ClosedByInterruptException 439 * if the thread is interrupted by another thread during this 440 * read operation. 441 * @throws ClosedChannelException 442 * if this channel is closed. 443 * @throws IndexOutOfBoundsException 444 * if {@code start < 0} or {@code number < 0}, or if 445 * {@code start + number} is greater than the size of 446 * {@code buffers}. 447 * @throws IOException 448 * if another I/O error occurs; details are in the message. 449 * @throws NonReadableChannelException 450 * if the channel has not been opened in a mode that permits 451 * reading. 452 */ read(ByteBuffer[] buffers, int start, int number)453 public abstract long read(ByteBuffer[] buffers, int start, int number) 454 throws IOException; 455 456 /** 457 * Returns the size of the file underlying this channel in bytes. 458 * 459 * @throws ClosedChannelException 460 * if this channel is closed. 461 * @throws IOException 462 * if an I/O error occurs while getting the size of the file. 463 */ size()464 public abstract long size() throws IOException; 465 466 /** 467 * Reads up to {@code count} bytes from {@code src} and stores them in this 468 * channel's file starting at {@code position}. No bytes are transferred if 469 * {@code position} is larger than the size of this channel's file. Less 470 * than {@code count} bytes are transferred if there are less bytes 471 * remaining in the source channel or if the source channel is non-blocking 472 * and has less than {@code count} bytes immediately available in its output 473 * buffer. 474 * <p> 475 * Note that this channel's position is not modified. 476 * 477 * @param src 478 * the source channel to read bytes from. 479 * @param position 480 * the non-negative start position. 481 * @param count 482 * the non-negative number of bytes to transfer. 483 * @return the number of bytes that are transferred. 484 * @throws IllegalArgumentException 485 * if the parameters are invalid. 486 * @throws NonReadableChannelException 487 * if the source channel is not readable. 488 * @throws NonWritableChannelException 489 * if this channel is not writable. 490 * @throws ClosedChannelException 491 * if either channel has already been closed. 492 * @throws AsynchronousCloseException 493 * if either channel is closed by other threads during this 494 * operation. 495 * @throws ClosedByInterruptException 496 * if the thread is interrupted during this operation. 497 * @throws IOException 498 * if any I/O error occurs. 499 */ transferFrom(ReadableByteChannel src, long position, long count)500 public abstract long transferFrom(ReadableByteChannel src, long position, 501 long count) throws IOException; 502 503 /** 504 * Reads up to {@code count} bytes from this channel's file starting at 505 * {@code position} and writes them to {@code target}. No bytes are 506 * transferred if {@code position} is larger than the size of this channel's 507 * file. Less than {@code count} bytes are transferred if there less bytes 508 * available from this channel's file or if the target channel is 509 * non-blocking and has less than {@code count} bytes free in its input 510 * buffer. 511 * <p> 512 * Note that this channel's position is not modified. 513 * 514 * @param position 515 * the non-negative position to begin. 516 * @param count 517 * the non-negative number of bytes to transfer. 518 * @param target 519 * the target channel to write to. 520 * @return the number of bytes that were transferred. 521 * @throws IllegalArgumentException 522 * if the parameters are invalid. 523 * @throws NonReadableChannelException 524 * if this channel is not readable. 525 * @throws NonWritableChannelException 526 * if the target channel is not writable. 527 * @throws ClosedChannelException 528 * if either channel has already been closed. 529 * @throws AsynchronousCloseException 530 * if either channel is closed by other threads during this 531 * operation. 532 * @throws ClosedByInterruptException 533 * if the thread is interrupted during this operation. 534 * @throws IOException 535 * if any I/O error occurs. 536 */ transferTo(long position, long count, WritableByteChannel target)537 public abstract long transferTo(long position, long count, 538 WritableByteChannel target) throws IOException; 539 540 /** 541 * Truncates the file underlying this channel to a given size. Any bytes 542 * beyond the given size are removed from the file. If there are no bytes 543 * beyond the given size then the file contents are unmodified. 544 * <p> 545 * If the file position is currently greater than the given size, then it is 546 * set to the new size. 547 * 548 * @param size 549 * the maximum size of the underlying file. 550 * @throws IllegalArgumentException 551 * if the requested size is negative. 552 * @throws ClosedChannelException 553 * if this channel is closed. 554 * @throws NonWritableChannelException 555 * if the channel cannot be written to. 556 * @throws IOException 557 * if another I/O error occurs. 558 * @return this channel. 559 */ truncate(long size)560 public abstract FileChannel truncate(long size) throws IOException; 561 562 /** 563 * Attempts to acquire an exclusive lock on this file without blocking. 564 * <p> 565 * This is a convenience method for attempting to acquire a maximum length 566 * lock on the file. It is equivalent to: 567 * {@code fileChannel.tryLock(0L, Long.MAX_VALUE, false);} 568 * <p> 569 * The method returns {@code null} if the acquisition would result in an 570 * overlapped lock with another OS process. 571 * 572 * @return the file lock object, or {@code null} if the lock would overlap 573 * with an existing exclusive lock in another OS process. 574 * @throws ClosedChannelException 575 * if the file channel is closed. 576 * @throws OverlappingFileLockException 577 * if a lock already exists that overlaps this lock request or 578 * another thread is waiting to acquire a lock that will overlap 579 * with this request. 580 * @throws IOException 581 * if any I/O error occurs. 582 */ tryLock()583 public final FileLock tryLock() throws IOException { 584 return tryLock(0L, Long.MAX_VALUE, false); 585 } 586 587 /** 588 * Attempts to acquire an exclusive lock on this file without blocking. The 589 * method returns {@code null} if the acquisition would result in an 590 * overlapped lock with another OS process. 591 * <p> 592 * It is possible to acquire a lock for any region even if it's completely 593 * outside of the file's size. The size of the lock is fixed. If the file 594 * grows outside of the lock that region of the file won't be locked by this 595 * lock. 596 * 597 * @param position 598 * the starting position. 599 * @param size 600 * the size of file to lock. 601 * @param shared 602 * true if the lock is shared. 603 * @return the file lock object, or {@code null} if the lock would overlap 604 * with an existing exclusive lock in another OS process. 605 * @throws IllegalArgumentException 606 * if any parameters are invalid. 607 * @throws ClosedChannelException 608 * if the file channel is closed. 609 * @throws OverlappingFileLockException 610 * if a lock is already held that overlaps this lock request or 611 * another thread is waiting to acquire a lock that will overlap 612 * with this request. 613 * @throws IOException 614 * if any I/O error occurs. 615 */ tryLock(long position, long size, boolean shared)616 public abstract FileLock tryLock(long position, long size, boolean shared) 617 throws IOException; 618 619 /** 620 * Writes bytes from the given byte buffer to this file channel. 621 * <p> 622 * The bytes are written starting at the current file position, and after 623 * some number of bytes are written (up to the remaining number of bytes in 624 * the buffer) the file position is increased by the number of bytes 625 * actually written. 626 * 627 * @param src 628 * the byte buffer containing the bytes to be written. 629 * @return the number of bytes actually written. 630 * @throws NonWritableChannelException 631 * if the channel was not opened for writing. 632 * @throws ClosedChannelException 633 * if the channel was already closed. 634 * @throws AsynchronousCloseException 635 * if another thread closes the channel during the write. 636 * @throws ClosedByInterruptException 637 * if another thread interrupts the calling thread while this 638 * operation is in progress. The interrupt state of the calling 639 * thread is set and the channel is closed. 640 * @throws IOException 641 * if another I/O error occurs, details are in the message. 642 * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 643 */ write(ByteBuffer src)644 public abstract int write(ByteBuffer src) throws IOException; 645 646 /** 647 * Writes bytes from the given buffer to this file channel starting at the 648 * given file position. 649 * <p> 650 * The bytes are written starting at the given file position (up to the 651 * remaining number of bytes in the buffer). The number of bytes actually 652 * written is returned. 653 * <p> 654 * If the position is beyond the current end of file, then the file is first 655 * extended up to the given position by the required number of unspecified 656 * byte values. 657 * <p> 658 * Note that the file position is not modified by this method. 659 * 660 * @param buffer 661 * the buffer containing the bytes to be written. 662 * @param position 663 * the (non-negative) position at which to write the bytes. 664 * @return the number of bytes actually written. 665 * @throws IllegalArgumentException 666 * if <code>position</code> is less than 0. 667 * @throws ClosedChannelException 668 * if this channel is closed. 669 * @throws NonWritableChannelException 670 * if the channel was not opened in write-mode. 671 * @throws AsynchronousCloseException 672 * if this channel is closed by another thread while this method 673 * is executing. 674 * @throws ClosedByInterruptException 675 * if another thread interrupts the calling thread while this 676 * operation is in progress. The interrupt state of the calling 677 * thread is set and the channel is closed. 678 * @throws IOException 679 * if another I/O error occurs. 680 */ write(ByteBuffer buffer, long position)681 public abstract int write(ByteBuffer buffer, long position) 682 throws IOException; 683 684 /** 685 * Writes bytes from all the given byte buffers to this file channel. 686 * <p> 687 * The bytes are written starting at the current file position, and after 688 * the bytes are written (up to the remaining number of bytes in all the 689 * buffers), the file position is increased by the number of bytes actually 690 * written. 691 * <p> 692 * Calling this method is equivalent to calling 693 * {@code write(buffers, 0, buffers.length);} 694 * 695 * @param buffers 696 * the buffers containing bytes to write. 697 * @return the number of bytes actually written. 698 * @throws AsynchronousCloseException 699 * if this channel is closed by another thread during this write 700 * operation. 701 * @throws ClosedByInterruptException 702 * if another thread interrupts the calling thread while this 703 * operation is in progress. The interrupt state of the calling 704 * thread is set and the channel is closed. 705 * @throws ClosedChannelException 706 * if this channel is closed. 707 * @throws IOException 708 * if another I/O error occurs; details are in the message. 709 * @throws NonWritableChannelException 710 * if this channel was not opened for writing. 711 */ 712 @Override write(ByteBuffer[] buffers)713 public final long write(ByteBuffer[] buffers) throws IOException { 714 return write(buffers, 0, buffers.length); 715 } 716 717 /** 718 * Attempts to write a subset of the given bytes from the buffers to this 719 * file channel. This method attempts to write all {@code remaining()} 720 * bytes from {@code length} byte buffers, in order, starting at {@code 721 * sources[offset]}. The number of bytes actually written is returned. 722 * <p> 723 * If a write operation is in progress, subsequent threads will block until 724 * the write is completed and then contend for the ability to write. 725 * 726 * @param buffers 727 * the array of byte buffers that is the source for bytes written 728 * to this channel. 729 * @param offset 730 * the index of the first buffer in {@code buffers }to get bytes 731 * from. 732 * @param length 733 * the number of buffers to get bytes from. 734 * @return the number of bytes actually written to this channel. 735 * @throws AsynchronousCloseException 736 * if this channel is closed by another thread during this write 737 * operation. 738 * @throws ClosedByInterruptException 739 * if another thread interrupts the calling thread while this 740 * operation is in progress. The interrupt state of the calling 741 * thread is set and the channel is closed. 742 * @throws ClosedChannelException 743 * if this channel is closed. 744 * @throws IndexOutOfBoundsException 745 * if {@code offset < 0} or {@code length < 0}, or if 746 * {@code offset + length} is greater than the size of 747 * {@code buffers}. 748 * @throws IOException 749 * if another I/O error occurs; details are in the message. 750 * @throws NonWritableChannelException 751 * if this channel was not opened for writing. 752 */ 753 @Override write(ByteBuffer[] buffers, int offset, int length)754 public abstract long write(ByteBuffer[] buffers, int offset, int length) 755 throws IOException; 756 } 757