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 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 */ 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 value of the file position pointer. 285 * 286 * @return the current position as a positive integer number of bytes from 287 * the start of the file. 288 * @throws ClosedChannelException 289 * if this channel is closed. 290 * @throws IOException 291 * if another I/O error occurs. 292 */ position()293 public abstract long position() throws IOException; 294 295 /** 296 * Sets the file position pointer to a new value. 297 * <p> 298 * The argument is the number of bytes counted from the start of the file. 299 * The position cannot be set to a value that is negative. The new position 300 * can be set beyond the current file size. If set beyond the current file 301 * size, attempts to read will return end of file. Write operations will 302 * succeed but they will fill the bytes between the current end of file and 303 * the new position with the required number of (unspecified) byte values. 304 * 305 * @param offset 306 * the new file position, in bytes. 307 * @return the receiver. 308 * @throws IllegalArgumentException 309 * if the new position is negative. 310 * @throws ClosedChannelException 311 * if this channel is closed. 312 * @throws IOException 313 * if another I/O error occurs. 314 */ position(long offset)315 public abstract FileChannel position(long offset) throws IOException; 316 317 /** 318 * Reads bytes from this file channel into the given buffer. 319 * <p> 320 * The maximum number of bytes that will be read is the remaining number of 321 * bytes in the buffer when the method is invoked. The bytes will be copied 322 * into the buffer starting at the buffer's current position. 323 * <p> 324 * The call may block if other threads are also attempting to read from this 325 * channel. 326 * <p> 327 * Upon completion, the buffer's position is set to the end of the bytes 328 * that have been read. The buffer's limit is not changed. 329 * 330 * @param buffer 331 * the byte buffer to receive the bytes. 332 * @return the number of bytes actually read. 333 * @throws AsynchronousCloseException 334 * if another thread closes the channel during the read. 335 * @throws ClosedByInterruptException 336 * if another thread interrupts the calling thread during the 337 * read. 338 * @throws ClosedChannelException 339 * if this channel is closed. 340 * @throws IOException 341 * if another I/O error occurs, details are in the message. 342 * @throws NonReadableChannelException 343 * if the channel has not been opened in a mode that permits 344 * reading. 345 */ read(ByteBuffer buffer)346 public abstract int read(ByteBuffer buffer) throws IOException; 347 348 /** 349 * Reads bytes from this file channel into the given buffer starting from 350 * the specified file position. 351 * <p> 352 * The bytes are read starting at the given file position (up to the 353 * remaining number of bytes in the buffer). The number of bytes actually 354 * read is returned. 355 * <p> 356 * If {@code position} is beyond the current end of file, then no bytes are 357 * read. 358 * <p> 359 * Note that the file position is unmodified by this method. 360 * 361 * @param buffer 362 * the buffer to receive the bytes. 363 * @param position 364 * the (non-negative) position at which to read the bytes. 365 * @return the number of bytes actually read. 366 * @throws AsynchronousCloseException 367 * if this channel is closed by another thread while this method 368 * is executing. 369 * @throws ClosedByInterruptException 370 * if another thread interrupts the calling thread while this 371 * operation is in progress. The calling thread will have the 372 * interrupt state set, and the channel will be closed. 373 * @throws ClosedChannelException 374 * if this channel is closed. 375 * @throws IllegalArgumentException 376 * if <code>position</code> is less than 0. 377 * @throws IOException 378 * if another I/O error occurs. 379 * @throws NonReadableChannelException 380 * if the channel has not been opened in a mode that permits 381 * reading. 382 */ read(ByteBuffer buffer, long position)383 public abstract int read(ByteBuffer buffer, long position) 384 throws IOException; 385 386 /** 387 * Reads bytes from this file channel and stores them in the specified array 388 * of buffers. This method attempts to read as many bytes as can be stored 389 * in the buffer array from this channel and returns the number of bytes 390 * actually read. It also increases the file position by the number of bytes 391 * read. 392 * <p> 393 * If a read operation is in progress, subsequent threads will block until 394 * the read is completed and will then contend for the ability to read. 395 * <p> 396 * Calling this method is equivalent to calling 397 * {@code read(buffers, 0, buffers.length);} 398 * 399 * @param buffers 400 * the array of byte buffers into which the bytes will be copied. 401 * @return the number of bytes actually read. 402 * @throws AsynchronousCloseException 403 * if this channel is closed by another thread during this read 404 * operation. 405 * @throws ClosedByInterruptException 406 * if the thread is interrupted by another thread during this 407 * read operation. 408 * @throws ClosedChannelException 409 * if this channel is closed. 410 * @throws IOException 411 * if another I/O error occurs; details are in the message. 412 * @throws NonReadableChannelException 413 * if the channel has not been opened in a mode that permits 414 * reading. 415 */ read(ByteBuffer[] buffers)416 public final long read(ByteBuffer[] buffers) throws IOException { 417 return read(buffers, 0, buffers.length); 418 } 419 420 /** 421 * Reads bytes from this file channel into a subset of the given buffers. 422 * This method attempts to read all {@code remaining()} bytes from {@code 423 * length} byte buffers, in order, starting at {@code targets[offset]}. It 424 * increases the file position by the number of bytes actually read. The 425 * number of bytes actually read is returned. 426 * <p> 427 * If a read operation is in progress, subsequent threads will block until 428 * the read is completed and will then contend for the ability to read. 429 * 430 * @param buffers 431 * the array of byte buffers into which the bytes will be copied. 432 * @param start 433 * the index of the first buffer to store bytes in. 434 * @param number 435 * the maximum number of buffers to store bytes in. 436 * @return the number of bytes actually read. 437 * @throws AsynchronousCloseException 438 * if this channel is closed by another thread during this read 439 * operation. 440 * @throws ClosedByInterruptException 441 * if the thread is interrupted by another thread during this 442 * read operation. 443 * @throws ClosedChannelException 444 * if this channel is closed. 445 * @throws IndexOutOfBoundsException 446 * if {@code start < 0} or {@code number < 0}, or if 447 * {@code start + number} is greater than the size of 448 * {@code buffers}. 449 * @throws IOException 450 * if another I/O error occurs; details are in the message. 451 * @throws NonReadableChannelException 452 * if the channel has not been opened in a mode that permits 453 * reading. 454 */ read(ByteBuffer[] buffers, int start, int number)455 public abstract long read(ByteBuffer[] buffers, int start, int number) 456 throws IOException; 457 458 /** 459 * Returns the size of the file underlying this channel in bytes. 460 * 461 * @return the size of the file in bytes. 462 * @throws ClosedChannelException 463 * if this channel is closed. 464 * @throws IOException 465 * if an I/O error occurs while getting the size of the file. 466 */ size()467 public abstract long size() throws IOException; 468 469 /** 470 * Reads up to {@code count} bytes from {@code src} and stores them in this 471 * channel's file starting at {@code position}. No bytes are transferred if 472 * {@code position} is larger than the size of this channel's file. Less 473 * than {@code count} bytes are transferred if there are less bytes 474 * remaining in the source channel or if the source channel is non-blocking 475 * and has less than {@code count} bytes immediately available in its output 476 * buffer. 477 * <p> 478 * Note that this channel's position is not modified. 479 * 480 * @param src 481 * the source channel to read bytes from. 482 * @param position 483 * the non-negative start position. 484 * @param count 485 * the non-negative number of bytes to transfer. 486 * @return the number of bytes that are transferred. 487 * @throws IllegalArgumentException 488 * if the parameters are invalid. 489 * @throws NonReadableChannelException 490 * if the source channel is not readable. 491 * @throws NonWritableChannelException 492 * if this channel is not writable. 493 * @throws ClosedChannelException 494 * if either channel has already been closed. 495 * @throws AsynchronousCloseException 496 * if either channel is closed by other threads during this 497 * operation. 498 * @throws ClosedByInterruptException 499 * if the thread is interrupted during this operation. 500 * @throws IOException 501 * if any I/O error occurs. 502 */ transferFrom(ReadableByteChannel src, long position, long count)503 public abstract long transferFrom(ReadableByteChannel src, long position, 504 long count) throws IOException; 505 506 /** 507 * Reads up to {@code count} bytes from this channel's file starting at 508 * {@code position} and writes them to {@code target}. No bytes are 509 * transferred if {@code position} is larger than the size of this channel's 510 * file. Less than {@code count} bytes are transferred if there less bytes 511 * available from this channel's file or if the target channel is 512 * non-blocking and has less than {@code count} bytes free in its input 513 * buffer. 514 * <p> 515 * Note that this channel's position is not modified. 516 * 517 * @param position 518 * the non-negative position to begin. 519 * @param count 520 * the non-negative number of bytes to transfer. 521 * @param target 522 * the target channel to write to. 523 * @return the number of bytes that were transferred. 524 * @throws IllegalArgumentException 525 * if the parameters are invalid. 526 * @throws NonReadableChannelException 527 * if this channel is not readable. 528 * @throws NonWritableChannelException 529 * if the target channel is not writable. 530 * @throws ClosedChannelException 531 * if either channel has already been closed. 532 * @throws AsynchronousCloseException 533 * if either channel is closed by other threads during this 534 * operation. 535 * @throws ClosedByInterruptException 536 * if the thread is interrupted during this operation. 537 * @throws IOException 538 * if any I/O error occurs. 539 */ transferTo(long position, long count, WritableByteChannel target)540 public abstract long transferTo(long position, long count, 541 WritableByteChannel target) throws IOException; 542 543 /** 544 * Truncates the file underlying this channel to a given size. Any bytes 545 * beyond the given size are removed from the file. If there are no bytes 546 * beyond the given size then the file contents are unmodified. 547 * <p> 548 * If the file position is currently greater than the given size, then it is 549 * set to the new size. 550 * 551 * @param size 552 * the maximum size of the underlying file. 553 * @throws IllegalArgumentException 554 * if the requested size is negative. 555 * @throws ClosedChannelException 556 * if this channel is closed. 557 * @throws NonWritableChannelException 558 * if the channel cannot be written to. 559 * @throws IOException 560 * if another I/O error occurs. 561 * @return this channel. 562 */ truncate(long size)563 public abstract FileChannel truncate(long size) throws IOException; 564 565 /** 566 * Attempts to acquire an exclusive lock on this file without blocking. 567 * <p> 568 * This is a convenience method for attempting to acquire a maximum length 569 * lock on the file. It is equivalent to: 570 * {@code fileChannel.tryLock(0L, Long.MAX_VALUE, false);} 571 * <p> 572 * The method returns {@code null} if the acquisition would result in an 573 * overlapped lock with another OS process. 574 * 575 * @return the file lock object, or {@code null} if the lock would overlap 576 * with an existing exclusive lock in another OS process. 577 * @throws ClosedChannelException 578 * if the file channel is closed. 579 * @throws OverlappingFileLockException 580 * if a lock already exists that overlaps this lock request or 581 * another thread is waiting to acquire a lock that will overlap 582 * with this request. 583 * @throws IOException 584 * if any I/O error occurs. 585 */ tryLock()586 public final FileLock tryLock() throws IOException { 587 return tryLock(0L, Long.MAX_VALUE, false); 588 } 589 590 /** 591 * Attempts to acquire an exclusive lock on this file without blocking. The 592 * method returns {@code null} if the acquisition would result in an 593 * overlapped lock with another OS process. 594 * <p> 595 * It is possible to acquire a lock for any region even if it's completely 596 * outside of the file's size. The size of the lock is fixed. If the file 597 * grows outside of the lock that region of the file won't be locked by this 598 * lock. 599 * 600 * @param position 601 * the starting position. 602 * @param size 603 * the size of file to lock. 604 * @param shared 605 * true if the lock is shared. 606 * @return the file lock object, or {@code null} if the lock would overlap 607 * with an existing exclusive lock in another OS process. 608 * @throws IllegalArgumentException 609 * if any parameters are invalid. 610 * @throws ClosedChannelException 611 * if the file channel is closed. 612 * @throws OverlappingFileLockException 613 * if a lock is already held that overlaps this lock request or 614 * another thread is waiting to acquire a lock that will overlap 615 * with this request. 616 * @throws IOException 617 * if any I/O error occurs. 618 */ tryLock(long position, long size, boolean shared)619 public abstract FileLock tryLock(long position, long size, boolean shared) 620 throws IOException; 621 622 /** 623 * Writes bytes from the given byte buffer to this file channel. 624 * <p> 625 * The bytes are written starting at the current file position, and after 626 * some number of bytes are written (up to the remaining number of bytes in 627 * the buffer) the file position is increased by the number of bytes 628 * actually written. 629 * 630 * @param src 631 * the byte buffer containing the bytes to be written. 632 * @return the number of bytes actually written. 633 * @throws NonWritableChannelException 634 * if the channel was not opened for writing. 635 * @throws ClosedChannelException 636 * if the channel was already closed. 637 * @throws AsynchronousCloseException 638 * if another thread closes the channel during the write. 639 * @throws ClosedByInterruptException 640 * if another thread interrupts the calling thread while this 641 * operation is in progress. The interrupt state of the calling 642 * thread is set and the channel is closed. 643 * @throws IOException 644 * if another I/O error occurs, details are in the message. 645 * @see java.nio.channels.WritableByteChannel#write(java.nio.ByteBuffer) 646 */ write(ByteBuffer src)647 public abstract int write(ByteBuffer src) throws IOException; 648 649 /** 650 * Writes bytes from the given buffer to this file channel starting at the 651 * given file position. 652 * <p> 653 * The bytes are written starting at the given file position (up to the 654 * remaining number of bytes in the buffer). The number of bytes actually 655 * written is returned. 656 * <p> 657 * If the position is beyond the current end of file, then the file is first 658 * extended up to the given position by the required number of unspecified 659 * byte values. 660 * <p> 661 * Note that the file position is not modified by this method. 662 * 663 * @param buffer 664 * the buffer containing the bytes to be written. 665 * @param position 666 * the (non-negative) position at which to write the bytes. 667 * @return the number of bytes actually written. 668 * @throws IllegalArgumentException 669 * if <code>position</code> is less than 0. 670 * @throws ClosedChannelException 671 * if this channel is closed. 672 * @throws NonWritableChannelException 673 * if the channel was not opened in write-mode. 674 * @throws AsynchronousCloseException 675 * if this channel is closed by another thread while this method 676 * is executing. 677 * @throws ClosedByInterruptException 678 * if another thread interrupts the calling thread while this 679 * operation is in progress. The interrupt state of the calling 680 * thread is set and the channel is closed. 681 * @throws IOException 682 * if another I/O error occurs. 683 */ write(ByteBuffer buffer, long position)684 public abstract int write(ByteBuffer buffer, long position) 685 throws IOException; 686 687 /** 688 * Writes bytes from all the given byte buffers to this file channel. 689 * <p> 690 * The bytes are written starting at the current file position, and after 691 * the bytes are written (up to the remaining number of bytes in all the 692 * buffers), the file position is increased by the number of bytes actually 693 * written. 694 * <p> 695 * Calling this method is equivalent to calling 696 * {@code write(buffers, 0, buffers.length);} 697 * 698 * @param buffers 699 * the buffers containing bytes to write. 700 * @return the number of bytes actually written. 701 * @throws AsynchronousCloseException 702 * if this channel is closed by another thread during this write 703 * operation. 704 * @throws ClosedByInterruptException 705 * if another thread interrupts the calling thread while this 706 * operation is in progress. The interrupt state of the calling 707 * thread is set and the channel is closed. 708 * @throws ClosedChannelException 709 * if this channel is closed. 710 * @throws IOException 711 * if another I/O error occurs; details are in the message. 712 * @throws NonWritableChannelException 713 * if this channel was not opened for writing. 714 */ write(ByteBuffer[] buffers)715 public final long write(ByteBuffer[] buffers) throws IOException { 716 return write(buffers, 0, buffers.length); 717 } 718 719 /** 720 * Attempts to write a subset of the given bytes from the buffers to this 721 * file channel. This method attempts to write all {@code remaining()} 722 * bytes from {@code length} byte buffers, in order, starting at {@code 723 * sources[offset]}. The number of bytes actually written is returned. 724 * <p> 725 * If a write operation is in progress, subsequent threads will block until 726 * the write is completed and then contend for the ability to write. 727 * 728 * @param buffers 729 * the array of byte buffers that is the source for bytes written 730 * to this channel. 731 * @param offset 732 * the index of the first buffer in {@code buffers }to get bytes 733 * from. 734 * @param length 735 * the number of buffers to get bytes from. 736 * @return the number of bytes actually written to this channel. 737 * @throws AsynchronousCloseException 738 * if this channel is closed by another thread during this write 739 * operation. 740 * @throws ClosedByInterruptException 741 * if another thread interrupts the calling thread while this 742 * operation is in progress. The interrupt state of the calling 743 * thread is set and the channel is closed. 744 * @throws ClosedChannelException 745 * if this channel is closed. 746 * @throws IndexOutOfBoundsException 747 * if {@code offset < 0} or {@code length < 0}, or if 748 * {@code offset + length} is greater than the size of 749 * {@code buffers}. 750 * @throws IOException 751 * if another I/O error occurs; details are in the message. 752 * @throws NonWritableChannelException 753 * if this channel was not opened for writing. 754 */ write(ByteBuffer[] buffers, int offset, int length)755 public abstract long write(ByteBuffer[] buffers, int offset, int length) 756 throws IOException; 757 } 758