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