151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 246805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.nio.channels; 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.io.*; 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.nio.ByteBuffer; 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.nio.MappedByteBuffer; 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.nio.channels.spi.AbstractInterruptibleChannel; 32e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.nio.file.*; 33e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.nio.file.attribute.FileAttribute; 34e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmeraimport java.nio.file.spi.*; 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.Set; 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.HashSet; 3751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskiimport java.util.Collections; 3851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 3951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 4051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A channel for reading, writing, mapping, and manipulating a file. 4151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A file channel is a {@link SeekableByteChannel} that is connected to 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a file. It has a current <i>position</i> within its file which can 4451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * be both {@link #position() <i>queried</i>} and {@link #position(long) 4551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>modified</i>}. The file itself contains a variable-length sequence 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of bytes that can be read and written and whose current {@link #size 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>size</i>} can be queried. The size of the file increases 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * when bytes are written beyond its current size; the size of the file 4946805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * decreases when it is {@link #truncate <i>truncated</i>}. The 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file may also have some associated <i>metadata</i> such as access 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * permissions, content type, and last-modification time; this class does not 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * define methods for metadata access. 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> In addition to the familiar read, write, and close operations of byte 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channels, this class defines the following file-specific operations: </p> 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <ul> 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> Bytes may be {@link #read(ByteBuffer, long) read} or 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #write(ByteBuffer, long) <i>written</i>} at an absolute 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position in a file in a way that does not affect the channel's current 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position. </p></li> 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> A region of a file may be {@link #map <i>mapped</i>} 6551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * directly into memory; for large files this is often much more efficient 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * than invoking the usual <tt>read</tt> or <tt>write</tt> methods. 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </p></li> 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> Updates made to a file may be {@link #force <i>forced 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * out</i>} to the underlying storage device, ensuring that data are not 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * lost in the event of a system crash. </p></li> 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> Bytes can be transferred from a file {@link #transferTo <i>to 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * some other channel</i>}, and {@link #transferFrom <i>vice 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * versa</i>}, in a way that can be optimized by many operating systems 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * into a very fast transfer directly to or from the filesystem cache. 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </p></li> 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> A region of a file may be {@link FileLock <i>locked</i>} 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * against access by other programs. </p></li> 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </ul> 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> File channels are safe for use by multiple concurrent threads. The 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link Channel#close close} method may be invoked at any time, as specified 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by the {@link Channel} interface. Only one operation that involves the 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel's position or can change its file's size may be in progress at any 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given time; attempts to initiate a second such operation while the first is 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * still in progress will block until the first operation completes. Other 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operations, in particular those that take an explicit position, may proceed 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * concurrently; whether they in fact do so is dependent upon the underlying 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * implementation and is therefore unspecified. 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The view of a file provided by an instance of this class is guaranteed 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to be consistent with other views of the same file provided by other 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * instances in the same program. The view provided by an instance of this 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * class may or may not, however, be consistent with the views seen by other 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * concurrently-running programs due to caching performed by the underlying 9951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operating system and delays induced by network-filesystem protocols. This 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is true regardless of the language in which these other programs are 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * written, and whether they are running on the same machine or on some other 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * machine. The exact nature of any such inconsistencies are system-dependent 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and are therefore unspecified. 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 105e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> A file channel is created by invoking one of the {@link #open open} 106e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * methods defined by this class. A file channel can also be obtained from an 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * existing {@link java.io.FileInputStream#getChannel FileInputStream}, {@link 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.FileOutputStream#getChannel FileOutputStream}, or {@link 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.RandomAccessFile#getChannel RandomAccessFile} object by invoking 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that object's <tt>getChannel</tt> method, which returns a file channel that 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is connected to the same underlying file. Where the file channel is obtained 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * from an existing stream or random access file then the state of the file 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel is intimately connected to that of the object whose <tt>getChannel</tt> 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method returned the channel. Changing the channel's position, whether 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * explicitly or by reading or writing bytes, will change the file position of 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the originating object, and vice versa. Changing the file's length via the 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file channel will change the length seen via the originating object, and vice 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * versa. Changing the file's content by writing bytes will change the content 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * seen by the originating object, and vice versa. 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <a name="open-mode"></a> <p> At various points this class specifies that an 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * instance that is "open for reading," "open for writing," or "open for 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * reading and writing" is required. A channel obtained via the {@link 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.FileInputStream#getChannel getChannel} method of a {@link 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.FileInputStream} instance will be open for reading. A channel 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * obtained via the {@link java.io.FileOutputStream#getChannel getChannel} 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method of a {@link java.io.FileOutputStream} instance will be open for 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * writing. Finally, a channel obtained via the {@link 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.RandomAccessFile#getChannel getChannel} method of a {@link 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.RandomAccessFile} instance will be open for reading if the instance 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * was created with mode <tt>"r"</tt> and will be open for reading and writing 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * if the instance was created with mode <tt>"rw"</tt>. 13351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <a name="append-mode"></a><p> A file channel that is open for writing may be in 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <i>append mode</i>, for example if it was obtained from a file-output stream 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that was created by invoking the {@link 13751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * java.io.FileOutputStream#FileOutputStream(java.io.File,boolean) 13851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FileOutputStream(File,boolean)} constructor and passing <tt>true</tt> for 13951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the second parameter. In this mode each invocation of a relative write 14051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operation first advances the position to the end of the file and then writes 14151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the requested data. Whether the advancement of the position and the writing 14251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of the data are done in a single atomic operation is system-dependent and 14351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * therefore unspecified. 14451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 14551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.io.FileInputStream#getChannel() 14651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.io.FileOutputStream#getChannel() 14751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.io.RandomAccessFile#getChannel() 14851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 14951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Mark Reinhold 15051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Mike McCloskey 15151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author JSR-51 Expert Group 15251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.4 15351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 15451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 15551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic abstract class FileChannel 15651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski extends AbstractInterruptibleChannel 15751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski implements SeekableByteChannel, GatheringByteChannel, ScatteringByteChannel 15851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski{ 15951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 16051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Initializes a new instance of this class. 16151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 16251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski protected FileChannel() { } 16351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 164e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 165e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Opens or creates a file, returning a file channel to access the file. 166e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 167e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> The {@code options} parameter determines how the file is opened. 168e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE 169e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * WRITE} options determine if the file should be opened for reading and/or 170e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * writing. If neither option (or the {@link StandardOpenOption#APPEND APPEND} 171e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * option) is contained in the array then the file is opened for reading. 172e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * By default reading or writing commences at the beginning of the file. 173e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 174e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> In the addition to {@code READ} and {@code WRITE}, the following 175e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * options may be present: 176e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 177e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <table border=1 cellpadding=5 summary=""> 178e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> <th>Option</th> <th>Description</th> </tr> 179e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 180e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> {@link StandardOpenOption#APPEND APPEND} </td> 181e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> If this option is present then the file is opened for writing and 182e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * each invocation of the channel's {@code write} method first advances 183e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the position to the end of the file and then writes the requested 184e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * data. Whether the advancement of the position and the writing of the 185e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * data are done in a single atomic operation is system-dependent and 186e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * therefore unspecified. This option may not be used in conjunction 187e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td> 188e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 189e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 190e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </td> 191e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> If this option is present then the existing file is truncated to 192e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * a size of 0 bytes. This option is ignored when the file is opened only 193e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * for reading. </td> 194e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 195e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 196e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </td> 197e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> If this option is present then a new file is created, failing if 198e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the file already exists. When creating a file the check for the 199e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * existence of the file and the creation of the file if it does not exist 200e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * is atomic with respect to other file system operations. This option is 201e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * ignored when the file is opened only for reading. </td> 202e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 203e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 204e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td > {@link StandardOpenOption#CREATE CREATE} </td> 205e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> If this option is present then an existing file is opened if it 206e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * exists, otherwise a new file is created. When creating a file the check 207e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * for the existence of the file and the creation of the file if it does 208e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * not exist is atomic with respect to other file system operations. This 209e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * option is ignored if the {@code CREATE_NEW} option is also present or 210e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the file is opened only for reading. </td> 211e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 212e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 213e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </td> 214e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> When this option is present then the implementation makes a 215e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <em>best effort</em> attempt to delete the file when closed by the 216e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * the {@link #close close} method. If the {@code close} method is not 217e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * invoked then a <em>best effort</em> attempt is made to delete the file 218e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * when the Java virtual machine terminates. </td> 219e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 220e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 221e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td>{@link StandardOpenOption#SPARSE SPARSE} </td> 222e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> When creating a new file this option is a <em>hint</em> that the 223e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * new file will be sparse. This option is ignored when not creating 224e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * a new file. </td> 225e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 226e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 227e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> {@link StandardOpenOption#SYNC SYNC} </td> 228e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> Requires that every update to the file's content or metadata be 229e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * written synchronously to the underlying storage device. (see <a 230e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * href="../file/package-summary.html#integrity"> Synchronized I/O file 231e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * integrity</a>). </td> 23246805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * </tr> 233e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <tr> 234e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> {@link StandardOpenOption#DSYNC DSYNC} </td> 235e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <td> Requires that every update to the file's content be written 236e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * synchronously to the underlying storage device. (see <a 237e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * href="../file/package-summary.html#integrity"> Synchronized I/O file 238e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * integrity</a>). </td> 239e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </tr> 240e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </table> 241e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 242e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> An implementation may also support additional options. 243e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 244e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> The {@code attrs} parameter is an optional array of file {@link 245e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * FileAttribute file-attributes} to set atomically when creating the file. 246e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 247e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> The new channel is created by invoking the {@link 248e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * FileSystemProvider#newFileChannel newFileChannel} method on the 249e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * provider that created the {@code Path}. 250e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 251e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param path 252e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * The path of the file to open or create 253e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param options 254e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Options specifying how the file is opened 255e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param attrs 256e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * An optional list of file attributes to set atomically when 257e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * creating the file 258e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 259e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return A new file channel 260e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 261e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IllegalArgumentException 262e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If the set contains an invalid combination of options 263e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws UnsupportedOperationException 264e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If the {@code path} is associated with a provider that does not 265e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * support creating file channels, or an unsupported open option is 266e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * specified, or the array contains an attribute that cannot be set 267e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * atomically when creating the file 268e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IOException 269e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If an I/O error occurs 270e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws SecurityException 271e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If a security manager is installed and it denies an 272e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * unspecified permission required by the implementation. 273e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * In the case of the default provider, the {@link 274e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * SecurityManager#checkRead(String)} method is invoked to check 275e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * read access if the file is opened for reading. The {@link 276e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * SecurityManager#checkWrite(String)} method is invoked to check 277e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * write access if the file is opened for writing 278e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 279e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @since 1.7 280e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 281e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera public static FileChannel open(Path path, 282e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera Set<? extends OpenOption> options, 283e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera FileAttribute<?>... attrs) 284e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera throws IOException 285e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera { 286e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera FileSystemProvider provider = path.getFileSystem().provider(); 287e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera return provider.newFileChannel(path, options, attrs); 288e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera } 289e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 29046805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera @SuppressWarnings({"unchecked", "rawtypes"}) // generic array construction 291e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0]; 292e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 293e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera /** 294e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Opens or creates a file, returning a file channel to access the file. 295e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 296e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <p> An invocation of this method behaves in exactly the same way as the 297e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * invocation 298e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * <pre> 299e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * fc.{@link #open(Path,Set,FileAttribute[]) open}(file, opts, new FileAttribute<?>[0]); 300e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * </pre> 301e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * where {@code opts} is a set of the options specified in the {@code 302e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * options} array. 303e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 304e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param path 305e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * The path of the file to open or create 306e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @param options 307e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * Options specifying how the file is opened 308e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 309e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @return A new file channel 310e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 311e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IllegalArgumentException 312e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If the set contains an invalid combination of options 313e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws UnsupportedOperationException 314e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If the {@code path} is associated with a provider that does not 315e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * support creating file channels, or an unsupported open option is 316e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * specified 317e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws IOException 318e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If an I/O error occurs 319e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @throws SecurityException 320e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * If a security manager is installed and it denies an 321e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * unspecified permission required by the implementation. 322e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * In the case of the default provider, the {@link 323e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * SecurityManager#checkRead(String)} method is invoked to check 324e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * read access if the file is opened for reading. The {@link 325e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * SecurityManager#checkWrite(String)} method is invoked to check 326e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * write access if the file is opened for writing 327e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * 328e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera * @since 1.7 329e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera */ 330e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera public static FileChannel open(Path path, OpenOption... options) 331e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera throws IOException 332e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera { 333e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera Set<OpenOption> set = new HashSet<OpenOption>(options.length); 334e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera Collections.addAll(set, options); 335e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera return open(path, set, NO_ATTRIBUTES); 336e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera } 337e6bac4bf9c85c2454ce22c91da6c654552c268e0Shubham Ajmera 33851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // -- Channel operations -- 33951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 34051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 34151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Reads a sequence of bytes from this channel into the given buffer. 34251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 34351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are read starting at this channel's current file position, and 34451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * then the file position is updated with the number of bytes actually 34551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * read. Otherwise this method behaves exactly as specified in the {@link 34651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ReadableByteChannel} interface. </p> 34751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 34851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int read(ByteBuffer dst) throws IOException; 34951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 35051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 35151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Reads a sequence of bytes from this channel into a subsequence of the 35251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given buffers. 35351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 35451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are read starting at this channel's current file position, and 35551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * then the file position is updated with the number of bytes actually 35651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * read. Otherwise this method behaves exactly as specified in the {@link 35751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ScatteringByteChannel} interface. </p> 35851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 35951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long read(ByteBuffer[] dsts, int offset, int length) 36051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 36151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 36251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 36351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Reads a sequence of bytes from this channel into the given buffers. 36451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 36551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are read starting at this channel's current file position, and 36651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * then the file position is updated with the number of bytes actually 36751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * read. Otherwise this method behaves exactly as specified in the {@link 36851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ScatteringByteChannel} interface. </p> 36951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 37051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final long read(ByteBuffer[] dsts) throws IOException { 37151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return read(dsts, 0, dsts.length); 37251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 37351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 37451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 37551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Writes a sequence of bytes to this channel from the given buffer. 37651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 37751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are written starting at this channel's current file position 37851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * unless the channel is in append mode, in which case the position is 37951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * first advanced to the end of the file. The file is grown, if necessary, 38051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to accommodate the written bytes, and then the file position is updated 38151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with the number of bytes actually written. Otherwise this method 38251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * behaves exactly as specified by the {@link WritableByteChannel} 38351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interface. </p> 38451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 38551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int write(ByteBuffer src) throws IOException; 38651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 38751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 38851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Writes a sequence of bytes to this channel from a subsequence of the 38951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given buffers. 39051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 39151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are written starting at this channel's current file position 39251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * unless the channel is in append mode, in which case the position is 39351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * first advanced to the end of the file. The file is grown, if necessary, 39451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to accommodate the written bytes, and then the file position is updated 39551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with the number of bytes actually written. Otherwise this method 39651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * behaves exactly as specified in the {@link GatheringByteChannel} 39751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interface. </p> 39851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 39951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long write(ByteBuffer[] srcs, int offset, int length) 40051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 40151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 40251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 40351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Writes a sequence of bytes to this channel from the given buffers. 40451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 40551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Bytes are written starting at this channel's current file position 40651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * unless the channel is in append mode, in which case the position is 40751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * first advanced to the end of the file. The file is grown, if necessary, 40851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to accommodate the written bytes, and then the file position is updated 40951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * with the number of bytes actually written. Otherwise this method 41051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * behaves exactly as specified in the {@link GatheringByteChannel} 41151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interface. </p> 41251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 41351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final long write(ByteBuffer[] srcs) throws IOException { 41451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return write(srcs, 0, srcs.length); 41551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 41651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 41751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 41851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // -- Other operations -- 41951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 42051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 42146805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * Returns this channel's file position. 42251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 42351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This channel's file position, 42451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * a non-negative integer counting the number of bytes 42551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * from the beginning of the file to the current position 42651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 42751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 42851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 42951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 43051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 43151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 43251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 43351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long position() throws IOException; 43451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 43551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 43651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Sets this channel's file position. 43751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 43851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Setting the position to a value that is greater than the file's 43951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * current size is legal but does not change the size of the file. A later 44051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * attempt to read bytes at such a position will immediately return an 44151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * end-of-file indication. A later attempt to write bytes at such a 44251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position will cause the file to be grown to accommodate the new bytes; 44351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the values of any bytes between the previous end-of-file and the 44451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * newly-written bytes are unspecified. </p> 44551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 44651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param newPosition 44751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The new position, a non-negative integer counting 44851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the number of bytes from the beginning of the file 44951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This file channel 45151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 45351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 45451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 45651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the new position is negative 45751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 45851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 45951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 46051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 46151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FileChannel position(long newPosition) throws IOException; 46251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 46351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 46446805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * Returns the current size of this channel's file. 46551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 46651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The current size of this channel's file, 46751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * measured in bytes 46851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 46951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 47051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 47151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 47251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 47351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 47451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 47551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long size() throws IOException; 47651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 47751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 47851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Truncates this channel's file to the given size. 47951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 48051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If the given size is less than the file's current size then the file 48151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is truncated, discarding any bytes beyond the new end of the file. If 48251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the given size is greater than or equal to the file's current size then 48351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the file is not modified. In either case, if this channel's file 48451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is greater than the given size then it is set to that size. 48551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </p> 48651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 48751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param size 48851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The new size, a non-negative byte count 48951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return This file channel 49151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 49351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for writing 49451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 49651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 49751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 49851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 49951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the new size is negative 50051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 50151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 50251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 50351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 50451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FileChannel truncate(long size) throws IOException; 50551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 50651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 50751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Forces any updates to this channel's file to be written to the storage 50851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * device that contains it. 50951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 51051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If this channel's file resides on a local storage device then when 51151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this method returns it is guaranteed that all changes made to the file 51251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * since this channel was created, or since this method was last invoked, 51351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * will have been written to that device. This is useful for ensuring that 51451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * critical information is not lost in the event of a system crash. 51551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 51651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If the file does not reside on a local device then no such guarantee 51751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is made. 51851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 51951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The <tt>metaData</tt> parameter can be used to limit the number of 52051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * I/O operations that this method is required to perform. Passing 52151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>false</tt> for this parameter indicates that only updates to the 52251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * file's content need be written to storage; passing <tt>true</tt> 52351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * indicates that updates to both the file's content and metadata must be 52451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * written, which generally requires at least one more I/O operation. 52551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Whether this parameter actually has any effect is dependent upon the 52651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * underlying operating system and is therefore unspecified. 52751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 52851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Invoking this method may cause an I/O operation to occur even if the 52951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel was only opened for reading. Some operating systems, for 53051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * example, maintain a last-access time as part of a file's metadata, and 53151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this time is updated whenever the file is read. Whether or not this is 53251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * actually done is system-dependent and is therefore unspecified. 53351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 53451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method is only guaranteed to force changes that were made to 53551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this channel's file via the methods defined in this class. It may or 53651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * may not force changes that were made by modifying the content of a 53751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link MappedByteBuffer <i>mapped byte buffer</i>} obtained by 53851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * invoking the {@link #map map} method. Invoking the {@link 53951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * MappedByteBuffer#force force} method of the mapped byte buffer will 54051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * force changes made to the buffer's content to be written. </p> 54151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 54251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param metaData 54351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If <tt>true</tt> then this method is required to force changes 54451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to both the file's content and metadata to be written to 54551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * storage; otherwise, it need only force content changes to be 54651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * written 54751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 54851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 54951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 55051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 55151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 55251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 55351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 55451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract void force(boolean metaData) throws IOException; 55551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 55651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 55751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers bytes from this channel's file to the given writable byte 55851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel. 55951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 56051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> An attempt is made to read up to <tt>count</tt> bytes starting at 56151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the given <tt>position</tt> in this channel's file and write them to the 56251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * target channel. An invocation of this method may or may not transfer 56351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * all of the requested bytes; whether or not it does so depends upon the 56451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * natures and states of the channels. Fewer than the requested number of 56551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * bytes are transferred if this channel's file contains fewer than 56651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>count</tt> bytes starting at the given <tt>position</tt>, or if the 56751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * target channel is non-blocking and it has fewer than <tt>count</tt> 56851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * bytes free in its output buffer. 56951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 57051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method does not modify this channel's position. If the given 57151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is greater than the file's current size then no bytes are 57251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transferred. If the target channel has a position then bytes are 57351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * written starting at that position and then the position is incremented 57451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by the number of bytes written. 57551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 57651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method is potentially much more efficient than a simple loop 57751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that reads from this channel and writes to the target channel. Many 57851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operating systems can transfer bytes directly from the filesystem cache 57951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to the target channel without actually copying them. </p> 58051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 58151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 58251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The position within the file at which the transfer is to begin; 58351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * must be non-negative 58451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 58551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param count 58651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The maximum number of bytes to be transferred; must be 58751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * non-negative 58851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 58951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param target 59051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The target channel 59151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 59251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The number of bytes, possibly zero, 59351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that were actually transferred 59451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 59551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 59651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the preconditions on the parameters do not hold 59751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 59851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonReadableChannelException 59951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for reading 60051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 60151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 60251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the target channel was not opened for writing 60351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 60451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 60551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If either this channel or the target channel is closed 60651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 60751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 60851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes either channel 60951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the transfer is in progress 61051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 61151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedByInterruptException 61251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread interrupts the current thread while the 61351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer is in progress, thereby closing both channels and 61451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * setting the current thread's interrupt status 61551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 61651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 61751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 61851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 61951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long transferTo(long position, long count, 62051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski WritableByteChannel target) 62151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 62251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 62351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 62451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Transfers bytes into this channel's file from the given readable byte 62551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel. 62651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 62751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> An attempt is made to read up to <tt>count</tt> bytes from the 62851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * source channel and write them to this channel's file starting at the 62951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given <tt>position</tt>. An invocation of this method may or may not 63051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer all of the requested bytes; whether or not it does so depends 63151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * upon the natures and states of the channels. Fewer than the requested 63251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * number of bytes will be transferred if the source channel has fewer than 63351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>count</tt> bytes remaining, or if the source channel is non-blocking 63451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * and has fewer than <tt>count</tt> bytes immediately available in its 63551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * input buffer. 63651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 63751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method does not modify this channel's position. If the given 63851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is greater than the file's current size then no bytes are 63951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transferred. If the source channel has a position then bytes are read 64051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * starting at that position and then the position is incremented by the 64151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * number of bytes read. 64251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 64351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method is potentially much more efficient than a simple loop 64451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that reads from the source channel and writes to this channel. Many 64551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * operating systems can transfer bytes directly from the source channel 64651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * into the filesystem cache without actually copying them. </p> 64751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 64851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param src 64951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The source channel 65051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 65151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 65251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The position within the file at which the transfer is to begin; 65351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * must be non-negative 65451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 65551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param count 65651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The maximum number of bytes to be transferred; must be 65751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * non-negative 65851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 65951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The number of bytes, possibly zero, 66051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that were actually transferred 66151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 66251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 66351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the preconditions on the parameters do not hold 66451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 66551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonReadableChannelException 66651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the source channel was not opened for reading 66751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 66851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 66951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for writing 67051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 67151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 67251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If either this channel or the source channel is closed 67351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 67451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 67551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes either channel 67651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the transfer is in progress 67751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 67851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedByInterruptException 67951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread interrupts the current thread while the 68051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * transfer is in progress, thereby closing both channels and 68151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * setting the current thread's interrupt status 68251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 68351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 68451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 68551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 68651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract long transferFrom(ReadableByteChannel src, 68751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski long position, long count) 68851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 68951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 69051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 69151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Reads a sequence of bytes from this channel into the given buffer, 69251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * starting at the given file position. 69351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 69451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method works in the same manner as the {@link 69551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * #read(ByteBuffer)} method, except that bytes are read starting at the 69651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given file position rather than at the channel's current position. This 69751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method does not modify this channel's position. If the given position 69851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is greater than the file's current size then no bytes are read. </p> 69951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 70051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param dst 70151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The buffer into which bytes are to be transferred 70251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 70351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 70451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The file position at which the transfer is to begin; 70551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * must be non-negative 70651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 70751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The number of bytes read, possibly zero, or <tt>-1</tt> if the 70851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * given position is greater than or equal to the file's current 70951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * size 71051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 71151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 71251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the position is negative 71351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 71451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonReadableChannelException 71551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for reading 71651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 71751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 71851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 71951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 72051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 72151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes this channel 72251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the read operation is in progress 72351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 72451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedByInterruptException 72551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread interrupts the current thread 72651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the read operation is in progress, thereby 72751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * closing the channel and setting the current thread's 72851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interrupt status 72951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 73051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 73151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 73251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 73351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int read(ByteBuffer dst, long position) throws IOException; 73451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 73551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 73651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Writes a sequence of bytes to this channel from the given buffer, 73751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * starting at the given file position. 73851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 73951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method works in the same manner as the {@link 74051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * #write(ByteBuffer)} method, except that bytes are written starting at 74151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the given file position rather than at the channel's current position. 74251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This method does not modify this channel's position. If the given 74351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * position is greater than the file's current size then the file will be 74451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * grown to accommodate the new bytes; the values of any bytes between the 74551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * previous end-of-file and the newly-written bytes are unspecified. </p> 74651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 74751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param src 74851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The buffer from which bytes are to be transferred 74951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 75051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 75151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The file position at which the transfer is to begin; 75251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * must be non-negative 75351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 75451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The number of bytes written, possibly zero 75551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 75651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 75751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the position is negative 75851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 75951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 76051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for writing 76151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 76251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 76351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 76451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 76551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 76651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes this channel 76751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the write operation is in progress 76851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 76951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedByInterruptException 77051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread interrupts the current thread 77151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * while the write operation is in progress, thereby 77251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * closing the channel and setting the current thread's 77351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interrupt status 77451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 77551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 77651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 77751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 77851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract int write(ByteBuffer src, long position) throws IOException; 77951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 78051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 78151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // -- Memory-mapped buffers -- 78251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 78351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 78451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * A typesafe enumeration for file-mapping modes. 78551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 78651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.4 78751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 78851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.nio.channels.FileChannel#map 78951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 79051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static class MapMode { 79151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 79251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 79351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Mode for a read-only mapping. 79451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 79551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static final MapMode READ_ONLY 79651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski = new MapMode("READ_ONLY"); 79751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 79851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 79951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Mode for a read/write mapping. 80051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 80151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static final MapMode READ_WRITE 80251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski = new MapMode("READ_WRITE"); 80351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 80451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 80551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Mode for a private (copy-on-write) mapping. 80651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 80751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public static final MapMode PRIVATE 80851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski = new MapMode("PRIVATE"); 80951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 81051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private final String name; 81151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 81251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski private MapMode(String name) { 81351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski this.name = name; 81451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 81551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 81651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 81751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a string describing this file-mapping mode. 81851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 81951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A descriptive string 82051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 82151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public String toString() { 82251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return name; 82351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 82451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 82551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 82651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 82751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 82851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Maps a region of this channel's file directly into memory. 82951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 83051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A region of a file may be mapped into memory in one of three modes: 83151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </p> 83251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 83346805d66f32e857c885434b4fa8cb6b32dcc4bf7Shubham Ajmera * <ul> 83451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 83551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> <i>Read-only:</i> Any attempt to modify the resulting buffer 83651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown. 83751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p></li> 83851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 83951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> <i>Read/write:</i> Changes made to the resulting buffer will 84051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * eventually be propagated to the file; they may or may not be made 84151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * visible to other programs that have mapped the same file. ({@link 84251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * MapMode#READ_WRITE MapMode.READ_WRITE}) </p></li> 84351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 84451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li><p> <i>Private:</i> Changes made to the resulting buffer will not 84551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * be propagated to the file and will not be visible to other programs 84651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that have mapped the same file; instead, they will cause private 84751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * copies of the modified portions of the buffer to be created. ({@link 84851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * MapMode#PRIVATE MapMode.PRIVATE}) </p></li> 84951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 85051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </ul> 85151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 85251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> For a read-only mapping, this channel must have been opened for 85351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * reading; for a read/write or private mapping, this channel must have 85451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * been opened for both reading and writing. 85551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 85651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The {@link MappedByteBuffer <i>mapped byte buffer</i>} 85751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returned by this method will have a position of zero and a limit and 85851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * capacity of <tt>size</tt>; its mark will be undefined. The buffer and 85951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the mapping that it represents will remain valid until the buffer itself 86051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is garbage-collected. 86151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 86251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> A mapping, once established, is not dependent upon the file channel 86351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that was used to create it. Closing the channel, in particular, has no 86451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * effect upon the validity of the mapping. 86551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 86651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Many of the details of memory-mapped files are inherently dependent 86751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * upon the underlying operating system and are therefore unspecified. The 86851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * behavior of this method when the requested region is not completely 86951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * contained within this channel's file is unspecified. Whether changes 87051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * made to the content or size of the underlying file, by this program or 87151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * another, are propagated to the buffer is unspecified. The rate at which 87251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * changes to the buffer are propagated to the file is unspecified. 87351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 87451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> For most operating systems, mapping a file into memory is more 87551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * expensive than reading or writing a few tens of kilobytes of data via 87651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the usual {@link #read read} and {@link #write write} methods. From the 87751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * standpoint of performance it is generally only worth mapping relatively 87851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * large files into memory. </p> 87951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 88051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param mode 88151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link 88251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE 88351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * PRIVATE} defined in the {@link MapMode} class, according to 88451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * whether the file is to be mapped read-only, read/write, or 88551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * privately (copy-on-write), respectively 88651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 88751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 88851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The position within the file at which the mapped region 88951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * is to start; must be non-negative 89051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 89151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param size 89251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The size of the region to be mapped; must be non-negative and 89351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * no greater than {@link java.lang.Integer#MAX_VALUE} 89451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 89551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return The mapped byte buffer 89651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 89751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonReadableChannelException 89851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the <tt>mode</tt> is {@link MapMode#READ_ONLY READ_ONLY} but 89951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this channel was not opened for reading 90051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 90151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 90251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the <tt>mode</tt> is {@link MapMode#READ_WRITE READ_WRITE} or 90351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened 90451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * for both reading and writing 90551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 90651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 90751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the preconditions on the parameters do not hold 90851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 90951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 91051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 91151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 91251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.nio.channels.FileChannel.MapMode 91351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see java.nio.MappedByteBuffer 91451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 91551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract MappedByteBuffer map(MapMode mode, 91651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski long position, long size) 91751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 91851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 91951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 92051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski // -- Locks -- 92151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 92251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 92351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Acquires a lock on the given region of this channel's file. 92451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 92551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> An invocation of this method will block until the region can be 92651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * locked, this channel is closed, or the invoking thread is interrupted, 92751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * whichever comes first. 92851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 92951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If this channel is closed by another thread during an invocation of 93051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this method then an {@link AsynchronousCloseException} will be thrown. 93151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 93251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> If the invoking thread is interrupted while waiting to acquire the 93351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * lock then its interrupt status will be set and a {@link 93451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FileLockInterruptionException} will be thrown. If the invoker's 93551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interrupt status is set when this method is invoked then that exception 93651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * will be thrown immediately; the thread's interrupt status will not be 93751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * changed. 93851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 93951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The region specified by the <tt>position</tt> and <tt>size</tt> 94051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * parameters need not be contained within, or even overlap, the actual 94151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * underlying file. Lock regions are fixed in size; if a locked region 94251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * initially contains the end of the file and the file grows beyond the 94351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region then the new portion of the file will not be covered by the lock. 94451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a file is expected to grow in size and a lock on the entire file is 94551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * required then a region starting at zero, and no smaller than the 94651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * expected maximum size of the file, should be locked. The zero-argument 94751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #lock()} method simply locks a region of size {@link 94851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Long#MAX_VALUE}. 94951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 95051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Some operating systems do not support shared locks, in which case a 95151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * request for a shared lock is automatically converted into a request for 95251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * an exclusive lock. Whether the newly-acquired lock is shared or 95351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * exclusive may be tested by invoking the resulting lock object's {@link 95451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FileLock#isShared() isShared} method. 95551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 95651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> File locks are held on behalf of the entire Java virtual machine. 95751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * They are not suitable for controlling access to a file by multiple 95851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * threads within the same virtual machine. </p> 95951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 96051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 96151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The position at which the locked region is to start; must be 96251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * non-negative 96351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 96451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param size 96551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The size of the locked region; must be non-negative, and the sum 96651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>position</tt> + <tt>size</tt> must be non-negative 96751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 96851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param shared 96951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>true</tt> to request a shared lock, in which case this 97051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel must be open for reading (and possibly writing); 97151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>false</tt> to request an exclusive lock, in which case this 97251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * channel must be open for writing (and possibly reading) 97351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 97451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A lock object representing the newly-acquired lock 97551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 97651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 97751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the preconditions on the parameters do not hold 97851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 97951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 98051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 98151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 98251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 98351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes this channel while the invoking 98451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * thread is blocked in this method 98551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 98651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FileLockInterruptionException 98751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the invoking thread is interrupted while blocked in this 98851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method 98951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 99051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws OverlappingFileLockException 99151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a lock that overlaps the requested region is already held by 99251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this Java virtual machine, or if another thread is already 99351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * blocked in this method and is attempting to lock an overlapping 99451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region 99551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 99651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonReadableChannelException 99751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If <tt>shared</tt> is <tt>true</tt> this channel was not 99851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * opened for reading 99951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 100051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 100151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If <tt>shared</tt> is <tt>false</tt> but this channel was not 100251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * opened for writing 100351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 100451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 100551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 100651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 100751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock() 100851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock() 100951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock(long,long,boolean) 101051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 101151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FileLock lock(long position, long size, boolean shared) 101251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 101351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 101451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 101551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Acquires an exclusive lock on this channel's file. 101651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 101751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> An invocation of this method of the form <tt>fc.lock()</tt> behaves 101851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * in exactly the same way as the invocation 101951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 102051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 102151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre> 102251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 102351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A lock object representing the newly-acquired lock 102451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 102551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 102651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 102751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 102851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws AsynchronousCloseException 102951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If another thread closes this channel while the invoking 103051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * thread is blocked in this method 103151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 103251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws FileLockInterruptionException 103351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the invoking thread is interrupted while blocked in this 103451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * method 103551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 103651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws OverlappingFileLockException 103751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a lock that overlaps the requested region is already held by 103851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this Java virtual machine, or if another thread is already 103951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * blocked in this method and is attempting to lock an overlapping 104051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region of the same file 104151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 104251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws NonWritableChannelException 104351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel was not opened for writing 104451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 104551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 104651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 104751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 104851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock(long,long,boolean) 104951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock() 105051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock(long,long,boolean) 105151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 105251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final FileLock lock() throws IOException { 105351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return lock(0L, Long.MAX_VALUE, false); 105451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 105551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 105651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 105751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to acquire a lock on the given region of this channel's file. 105851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 105951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> This method does not block. An invocation always returns 106051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * immediately, either having acquired a lock on the requested region or 106151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * having failed to do so. If it fails to acquire a lock because an 106251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * overlapping lock is held by another program then it returns 106351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>null</tt>. If it fails to acquire a lock for any other reason then 106451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * an appropriate exception is thrown. 106551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 106651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> The region specified by the <tt>position</tt> and <tt>size</tt> 106751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * parameters need not be contained within, or even overlap, the actual 106851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * underlying file. Lock regions are fixed in size; if a locked region 106951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * initially contains the end of the file and the file grows beyond the 107051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region then the new portion of the file will not be covered by the lock. 107151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a file is expected to grow in size and a lock on the entire file is 107251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * required then a region starting at zero, and no smaller than the 107351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * expected maximum size of the file, should be locked. The zero-argument 107451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link #tryLock()} method simply locks a region of size {@link 107551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Long#MAX_VALUE}. 107651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 107751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> Some operating systems do not support shared locks, in which case a 107851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * request for a shared lock is automatically converted into a request for 107951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * an exclusive lock. Whether the newly-acquired lock is shared or 108051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * exclusive may be tested by invoking the resulting lock object's {@link 108151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FileLock#isShared() isShared} method. 108251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 108351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> File locks are held on behalf of the entire Java virtual machine. 108451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * They are not suitable for controlling access to a file by multiple 108551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * threads within the same virtual machine. </p> 108651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 108751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param position 108851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The position at which the locked region is to start; must be 108951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * non-negative 109051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 109151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param size 109251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The size of the locked region; must be non-negative, and the sum 109351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>position</tt> + <tt>size</tt> must be non-negative 109451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 109551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @param shared 109651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>true</tt> to request a shared lock, 109751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>false</tt> to request an exclusive lock 109851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 109951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A lock object representing the newly-acquired lock, 110051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or <tt>null</tt> if the lock could not be acquired 110151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * because another program holds an overlapping lock 110251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 110351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IllegalArgumentException 110451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If the preconditions on the parameters do not hold 110551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 110651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 110751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 110851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 110951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws OverlappingFileLockException 111051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a lock that overlaps the requested region is already held by 111151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this Java virtual machine, or if another thread is already 111251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * blocked in this method and is attempting to lock an overlapping 111351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region of the same file 111451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 111551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 111651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 111751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 111851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock() 111951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock(long,long,boolean) 112051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock() 112151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 112251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public abstract FileLock tryLock(long position, long size, boolean shared) 112351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski throws IOException; 112451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 112551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 112651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Attempts to acquire an exclusive lock on this channel's file. 112751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 112851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p> An invocation of this method of the form <tt>fc.tryLock()</tt> 112951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * behaves in exactly the same way as the invocation 113051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 113151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 113251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre> 113351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 113451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return A lock object representing the newly-acquired lock, 113551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or <tt>null</tt> if the lock could not be acquired 113651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * because another program holds an overlapping lock 113751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 113851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws ClosedChannelException 113951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If this channel is closed 114051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 114151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws OverlappingFileLockException 114251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If a lock that overlaps the requested region is already held by 114351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * this Java virtual machine, or if another thread is already 114451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * blocked in this method and is attempting to lock an overlapping 114551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * region 114651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 114751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @throws IOException 114851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * If some other I/O error occurs 114951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 115051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock() 115151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #lock(long,long,boolean) 115251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @see #tryLock(long,long,boolean) 115351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 115451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski public final FileLock tryLock() throws IOException { 115551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski return tryLock(0L, Long.MAX_VALUE, false); 115651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski } 115751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 115851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 1159