FileChannel
This class implements a communication channel for efficiently reading and and writing files. It implements the standard read( ) and write( ) methods of the ReadableByteChannel , WritableByteChannel , GatheringByteChannel and ScatteringByteChannel methods. In addition, however, FileChannel provides methods for: random-access to the file, efficient transfer of bytes between the file and another channel, file locking, memory mapping, querying and setting the file size and forcing buffered updates to be written to disk. These important features are described in further detail below. Note that since file operations do not typically block for extended periods the way network operations can, FileChannel does not subclass SelectableChannel (it is the only channel class that does not) and cannot be used with Selector objects. FileChannel has no public constructor and no static factory methods. To obtain a FileChannel , first create a FileInputStream , FileOutputStream , or RandomAccessFile object (see the java.io package) and then call the getChannel( ) method of that object. If you use a FileInputStream , the resulting channel will allow reading but not writing, and if you use a FileOutputStream , the channel will allow writing but not reading. If you obtain a FileChannel from a RandomAccessFile , then the channel will allow reading, or both reading and writing, depending on the mode argument to the RandomAccessFile constructor. A FileChannel has a position or file pointer that specifies the current point in the file. You can set or query the file position with two methods, both of which share the name position( ) . The position of a FileChannel and of the stream or RandomAccessFile from which it is derived are always the same: changing the position of the channel changes the position of the stream, and vice versa. The initial position of a FileChannel is the position of the stream or RandomAccessFile when the getChannel( ) method was called. If you create a FileChannel from a FileOutputStream that was opened in append mode, then any output to the channel always occurs at the end of the file, and sets the file position to the end end of the file. Once you have a FileChannel object, you can use the standard read( ) and write( ) methods defined by the various channel interfaces. In addition to updating the buffer position as they read and write bytes, these methods also update the file position to or from which those bytes are written or read. These standard read( ) methods return the number of bytes actually read, and return -1 if there are no bytes left in the file to read. The write( ) methods enlarge the file if they write past the current end-of-file. FileChannel also defines position-independent read( ) and write( ) methods that take a file position as an explicit argument: they read or write starting at that position of the file, and although they update the position of the ByteBuffer , they do not update the file position of the FileChannel . If the specified position is past the end-of-file, the read( ) method does not read any bytes and returns -1, and the write( ) method enlarges the file, leaving any bytes between the old end-of-file and the specified position undefined. It is common to read bytes from a FileChannel and then immediately write them out to some other channel (such as a SocketChannel : think of a web server, for example), or to read bytes from a channel and immediately write them to a FileChannel (consider an FTP client). FileChannel provides two methods, transferTo( ) and TRansferFrom( ) that do this very efficiently, without the need for a temporary ByteBuffer . TRansferTo( ) reads up to the specified number of bytes starting at the specified location from this FileChannel and writes them to the specified channel. It does not alter the file position of the FileChannel , and it returns the number of bytes actually transferred. transferFrom( ) does the reverse: it reads up to the specified number of available bytes from the specified channel, and writes them to this FileChannel at the specified location, without altering the file position of this channel, and returns the actual number of bytes transferred. For both methods, if the destination or source channel is a FileChannel itself, then the file position of that channel is updated. The size( ) method returns the size (in bytes) of the underlying file. truncate( ) reduces the file size to the specified value, discarding any file content that exceeds that size. If the specified size is greater than or equal to the current file size, the file is unchanged. If the file position is greater than the new size of the file, it the position is changed to the new size. Use the force( ) method to force any buffered modifications to the file to be written to the underlying storage device. If the file resides on a local device, (as opposed to a network filesystem, for example) then force( ) guarantees that any changes to the file made since the channel was opened or since a previous call to force( ) will have been written to the device. The argument to this method is a hint as to whether file meta-data (such as last modification time) is to be forced out in addition to file content. If this argument is true , the system will force content and meta-data. If false , the system may omit updates to meta-data. Note that force( ) is only required to output change made directly through the FileChannel . File updates made through a MappedByteBuffer returned by the map( ) method (described below)y should be forced out with the force( ) method of MappedByteBuffer . FileChannel defines two blocking lock( ) and two nonblocking tryLock( ) methods for locking a file or a region of a file against concurrent access by another program. (These methods are not suitable for preventing concurrent access to a file by two threads within the same Java virtual machine.) The no-argument versions of these methods attempt to acquire an exclusive lock on the entire file. The three-argument versions of the methods attempt to lock a specified region of the file, and may acquire shared locks in addition to exclusive locks. (A shared lock prevents any other process from acquiring an exclusive lock, but does not prevent other shared locks: typically, you acquire a shared lock when reading a file that should not be concurrently updated, and acquire an exclusive lock before writing file content to ensure that no one else is trying to read it at the same time.) The tryLock( ) methods return a FileLock object, or null if there was already a conflicting lock on the file. The lock( ) methods block if there is already a conflicting lock and never return null . See FileLock for more information about locks. The FileChannel file locking mechanism uses whatever locking capability is provided by the underlying platform. Some operating systems enforce file locking: if one process holds a lock, other processes are prevented by the operating system from accessing the file. Other operating systems merely prevent other processes from acquiring a conflicting lock: in this case, successful file locking requires the cooperation of all processes. Some operating systems do not support shared locks: on these systems an exclusive lock is returned even when a shared lock is requested . The map( ) method returns a MappedByteBuffer that represents the specified region of the file. File contents can be read directly from the buffer, and (if the mapping is done in read/write mode) bytes placed in the buffer will be written to the file. The mapping represented by a MappedByteBuffer remains valid until the buffer is garbage collected; the buffer continues to function even if the FileChannel from which it was created is closed. File mappings can be done in three different modes which specify whether bytes can be written into the buffer and what happens when this is done. See FileChannel.MapMode for a description of the three modes. The map( ) method relies on the memory-mapping facilities provided by the underlying operating system. This means that a number of details may vary from implementation to implementation. In particular, it is not specified whether changes to the underlying file made after the call to map( ) are visible through the MappedByteBuffer . Using a mapped file is typically more efficient that an unmapped file only when the file is a large one. Figure 13-23. java.nio.channels.FileChannel public abstract class FileChannel extends java.nio.channels.spi. AbstractInterruptibleChannel implements ByteChannel, GatheringByteChannel, ScatteringByteChannel { // Protected Constructors protected FileChannel ( ); // Nested Types public static class MapMode ; // Public Instance Methods public abstract void force (boolean metaData ) throws java.io.IOException; public final FileLock lock ( ) throws java.io.IOException; public abstract FileLock lock (long position , long size , boolean shared ) throws java.io.IOException; public abstract java.nio.MappedByteBuffer map (FileChannel.MapMode mode , long position , long size ) throws java.io.IOException; public abstract long position ( ) throws java.io.IOException; public abstract FileChannel position (long newPosition ) throws java.io.IOException; public abstract int read (java.nio.ByteBuffer dst , long position ) throws java.io.IOException; public abstract long size ( ) throws java.io.IOException; public abstract long transferFrom (ReadableByteChannel src , long position , long count ) throws java.io.IOException; public abstract long transferTo (long position , long count , WritableByteChannel target ) throws java.io.IOException; public abstract FileChannel truncate (long size ) throws java.io.IOException; public final FileLock tryLock ( ) throws java.io.IOException; public abstract FileLock tryLock (long position , long size , boolean shared ) throws java.io.IOException; public abstract int write (java.nio.ByteBuffer src , long position ) throws java.io.IOException; // Methods Implementing GatheringByteChannel public final long write (java.nio.ByteBuffer[ ] srcs ) throws java.io.IOException; public abstract long write (java.nio.ByteBuffer[ ] srcs , int offset , int length ) throws java.io.IOException; // Methods Implementing ReadableByteChannel public abstract int read (java.nio.ByteBuffer dst ) throws java.io.IOException; // Methods Implementing ScatteringByteChannel public final long read (java.nio.ByteBuffer[ ] dsts ) throws java.io.IOException; public abstract long read (java.nio.ByteBuffer[ ] dsts , int offset , int length ) throws java.io.IOException; // Methods Implementing WritableByteChannel public abstract int write (java.nio.ByteBuffer src ) throws java.io.IOException; } Passed ToFileLock.FileLock( ) Returned Byjava.io.FileInputStream.getChannel( ) , java.io.FileOutputStream.getChannel( ) , java.io.RandomAccessFile.getChannel( ) , FileLock.channel( ) |
EAN: 2147483647
Pages: 1220