IT. Expert System.

Android Reference

FileChannel


java.nio.channels

Class FileChannel

  • All Implemented Interfaces:
    Closeable, AutoCloseable, ByteChannel, Channel, GatheringByteChannel, InterruptibleChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel


    public abstract class FileChannel
    extends AbstractInterruptibleChannel
    implements GatheringByteChannel, ScatteringByteChannel, ByteChannel
    An abstract channel type for interaction with a platform file.

    A FileChannel defines the methods for reading, writing, memory mapping, and manipulating the logical state of a platform file. This type does not have a method for opening files, since this behavior has been delegated to the FileInputStream, FileOutputStream and RandomAccessFile types.

    FileChannels created from a FileInputStream or a RandomAccessFile created in mode "r", are read-only. FileChannels created from a FileOutputStream are write-only. FileChannels created from a RandomAccessFile created in mode "rw" are read/write. FileChannels created from a RandomAccessFile that was opened in append-mode will also be in append-mode -- meaning that each write will be proceeded by a seek to the end of file.

    FileChannels have a virtual pointer into the file which is referred to as a file position. The position can be manipulated by moving it within the file, and the current position can be queried.

    FileChannels also have an associated size. The size of the file is the number of bytes that it currently contains. The size can be manipulated by adding more bytes to the end of the file (which increases the size) or truncating the file (which decreases the size). The current size can also be queried.

    FileChannels have operations beyond the simple read, write, and close. They can also:

    • request that cached data be forced onto the disk,
    • lock ranges of bytes associated with the file,
    • transfer data directly to another channel in a manner that has the potential to be optimized by the platform,
    • memory-mapping files into NIO buffers to provide efficient manipulation of file data,
    • read and write to the file at absolute byte offsets in a fashion that does not modify the current position.

    FileChannels are thread-safe. Only one operation involving manipulation of the file position may be executed at the same time. Subsequent calls to such operations will block, and one of those blocked will be freed to continue when the first operation has completed. There is no ordered queue or fairness applied to the blocked threads.

    It is undefined whether operations that do not manipulate the file position will also block when there are any other operations in-flight.

    The logical view of the underlying file is consistent across all FileChannels and I/O streams opened on the same file by the same VM. Therefore, modifications performed via a channel will be visible to the stream and vice versa; this includes modifications to the file position, content, size, etc.

    • Nested Class Summary

      Nested Classes
      Modifier and Type Class and Description
      static class FileChannel.MapMode
      MapMode defines file mapping mode constants.
    • Constructor Summary

      Constructors
      Modifier Constructor and Description
      protected FileChannel()
      Protected default constructor.
    • Method Summary

      Methods
      Modifier and Type Method and Description
      abstract void force(boolean metadata)
      Requests that all updates to this channel are committed to the storage device.
      FileLock lock()
      Obtains an exclusive lock on this file.
      abstract FileLock lock(long position, long size, boolean shared)
      Obtains a lock on a specified region of the file.
      abstract MappedByteBuffer map(FileChannel.MapMode mode, long position, long size)
      Maps the file into memory.
      abstract long position()
      Returns the current value of the file position pointer.
      abstract FileChannel position(long offset)
      Sets the file position pointer to a new value.
      abstract int read(ByteBuffer buffer)
      Reads bytes from this file channel into the given buffer.
      long read(ByteBuffer[] buffers)
      Reads bytes from this file channel and stores them in the specified array of buffers.
      abstract long read(ByteBuffer[] buffers, int start, int number)
      Reads bytes from this file channel into a subset of the given buffers.
      abstract int read(ByteBuffer buffer, long position)
      Reads bytes from this file channel into the given buffer starting from the specified file position.
      abstract long size()
      Returns the size of the file underlying this channel in bytes.
      abstract long transferFrom(ReadableByteChannel src, long position, long count)
      Reads up to count bytes from src and stores them in this channel's file starting at position.
      abstract long transferTo(long position, long count, WritableByteChannel target)
      Reads up to count bytes from this channel's file starting at position and writes them to target.
      abstract FileChannel truncate(long size)
      Truncates the file underlying this channel to a given size.
      FileLock tryLock()
      Attempts to acquire an exclusive lock on this file without blocking.
      abstract FileLock tryLock(long position, long size, boolean shared)
      Attempts to acquire an exclusive lock on this file without blocking.
      abstract int write(ByteBuffer src)
      Writes bytes from the given byte buffer to this file channel.
      long write(ByteBuffer[] buffers)
      Writes bytes from all the given byte buffers to this file channel.
      abstract long write(ByteBuffer[] buffers, int offset, int length)
      Attempts to write a subset of the given bytes from the buffers to this file channel.
      abstract int write(ByteBuffer buffer, long position)
      Writes bytes from the given buffer to this file channel starting at the given file position.
    • Constructor Detail

      • FileChannel

        protected FileChannel()
        Protected default constructor.
    • Method Detail

      • force

        public abstract void force(boolean metadata)
                            throws IOException
        Requests that all updates to this channel are committed to the storage device.

        When this method returns, all modifications made to the platform file underlying this channel have been committed if the file resides on a local storage device. If the file is not hosted locally, for example on a networked file system, then applications cannot be certain that the modifications have been committed.

        There are no assurances given that changes made to the file using methods defined elsewhere will be committed. For example, changes made via a mapped byte buffer may not be committed.

        The metadata parameter indicates whether the update should include the file's metadata such as last modification time, last access time, etc. Note that passing true may invoke an underlying write to the operating system (if the platform is maintaining metadata such as last access time), even if the channel is opened read-only.

        Parameters:
        metadata - true if the file metadata should be flushed in addition to the file content, false otherwise.
        Throws:
        ClosedChannelException - if this channel is already closed.
        IOException - if another I/O error occurs.
      • lock

        public final FileLock lock()
                            throws IOException
        Obtains an exclusive lock on this file.

        This is a convenience method for acquiring a maximum length lock on a file. It is equivalent to: fileChannel.lock(0L, Long.MAX_VALUE, false);

        Returns:
        the lock object representing the locked file area.
        Throws:
        ClosedChannelException - the file channel is closed.
        NonWritableChannelException - this channel was not opened for writing.
        OverlappingFileLockException - either a lock is already held that overlaps this lock request, or another thread is waiting to acquire a lock that will overlap with this request.
        FileLockInterruptionException - the calling thread was interrupted while waiting to acquire the lock.
        AsynchronousCloseException - the channel was closed while the calling thread was waiting to acquire the lock.
        IOException - if another I/O error occurs while obtaining the requested lock.
      • lock

        public abstract FileLock lock(long position,
                    long size,
                    boolean shared)
                               throws IOException
        Obtains a lock on a specified region of the file.

        This is the blocking version of lock acquisition, see also the tryLock() methods.

        Attempts to acquire an overlapping lock region will fail. The attempt will fail if the overlapping lock has already been obtained, or if another thread is currently waiting to acquire the overlapping lock.

        If the request is not for an overlapping lock, the thread calling this method will block until the lock is obtained (likely by no contention or another process releasing a lock), or until this thread is interrupted or the channel is closed.

        If the lock is obtained successfully then the FileLock object returned represents the lock for subsequent operations on the locked region.

        If the thread is interrupted while waiting for the lock, the thread is set to the interrupted state and throws a FileLockInterruptionException. If this channel is closed while the thread is waiting to obtain the lock then the thread throws a AsynchronousCloseException.

        There is no requirement for the position and size to be within the current start and length of the file.

        Some platforms do not support shared locks, and if a request is made for a shared lock on such a platform, this method will attempt to acquire an exclusive lock instead. It is undefined whether the lock obtained is advisory or mandatory.

        Parameters:
        position - the starting position for the locked region.
        size - the length of the locked region in bytes.
        shared - a flag indicating whether an attempt should be made to acquire a shared lock.
        Returns:
        the file lock object.
        Throws:
        IllegalArgumentException - if position or size is negative.
        ClosedChannelException - if this channel is closed.
        OverlappingFileLockException - if the requested region overlaps an existing lock or pending lock request.
        NonReadableChannelException - if the channel is not opened in read-mode but shared is true.
        NonWritableChannelException - if the channel is not opened in write mode but shared is false.
        AsynchronousCloseException - if this channel is closed by another thread while this method is executing.
        FileLockInterruptionException - if the thread is interrupted while in the state of waiting on the desired file lock.
        IOException - if another I/O error occurs.
      • map

        public abstract MappedByteBuffer map(FileChannel.MapMode mode,
                           long position,
                           long size)
                                      throws IOException
        Maps the file into memory. There can be three modes: read-only, read/write and private. After mapping, changes made to memory or the file channel do not affect the other storage place.

        Note: mapping a file into memory is usually expensive.

        Parameters:
        mode - one of the three mapping modes.
        position - the starting position of the file.
        size - the size of the region to map into memory.
        Returns:
        the mapped byte buffer.
        Throws:
        NonReadableChannelException - if the FileChannel is not opened for reading but the given mode is "READ_ONLY".
        NonWritableChannelException - if the FileChannel is not opened for writing but the given mode is not "READ_ONLY".
        IllegalArgumentException - if the given parameters of position and size are not correct. Both must be non negative. size also must not be bigger than max integer.
        IOException - if any I/O error occurs.
      • position

        public abstract long position()
                               throws IOException
        Returns the current value of the file position pointer.
        Returns:
        the current position as a positive integer number of bytes from the start of the file.
        Throws:
        ClosedChannelException - if this channel is closed.
        IOException - if another I/O error occurs.
      • position

        public abstract FileChannel position(long offset)
                                      throws IOException
        Sets the file position pointer to a new value.

        The argument is the number of bytes counted from the start of the file. The position cannot be set to a value that is negative. The new position can be set beyond the current file size. If set beyond the current file size, attempts to read will return end of file. Write operations will succeed but they will fill the bytes between the current end of file and the new position with the required number of (unspecified) byte values.

        Parameters:
        offset - the new file position, in bytes.
        Returns:
        the receiver.
        Throws:
        IllegalArgumentException - if the new position is negative.
        ClosedChannelException - if this channel is closed.
        IOException - if another I/O error occurs.
      • read

        public abstract int read(ByteBuffer buffer)
                          throws IOException
        Reads bytes from this file channel into the given buffer.

        The maximum number of bytes that will be read is the remaining number of bytes in the buffer when the method is invoked. The bytes will be copied into the buffer starting at the buffer's current position.

        The call may block if other threads are also attempting to read from this channel.

        Upon completion, the buffer's position is set to the end of the bytes that have been read. The buffer's limit is not changed.

        Specified by:
        read in interface ReadableByteChannel
        Parameters:
        buffer - the byte buffer to receive the bytes.
        Returns:
        the number of bytes actually read.
        Throws:
        AsynchronousCloseException - if another thread closes the channel during the read.
        ClosedByInterruptException - if another thread interrupts the calling thread during the read.
        ClosedChannelException - if this channel is closed.
        IOException - if another I/O error occurs, details are in the message.
        NonReadableChannelException - if the channel has not been opened in a mode that permits reading.
      • read

        public abstract int read(ByteBuffer buffer,
               long position)
                          throws IOException
        Reads bytes from this file channel into the given buffer starting from the specified file position.

        The bytes are read starting at the given file position (up to the remaining number of bytes in the buffer). The number of bytes actually read is returned.

        If position is beyond the current end of file, then no bytes are read.

        Note that the file position is unmodified by this method.

        Parameters:
        buffer - the buffer to receive the bytes.
        position - the (non-negative) position at which to read the bytes.
        Returns:
        the number of bytes actually read.
        Throws:
        AsynchronousCloseException - if this channel is closed by another thread while this method is executing.
        ClosedByInterruptException - if another thread interrupts the calling thread while this operation is in progress. The calling thread will have the interrupt state set, and the channel will be closed.
        ClosedChannelException - if this channel is closed.
        IllegalArgumentException - if position is less than 0.
        IOException - if another I/O error occurs.
        NonReadableChannelException - if the channel has not been opened in a mode that permits reading.
      • read

        public final long read(ByteBuffer[] buffers)
                        throws IOException
        Reads bytes from this file channel and stores them in the specified array of buffers. This method attempts to read as many bytes as can be stored in the buffer array from this channel and returns the number of bytes actually read. It also increases the file position by the number of bytes read.

        If a read operation is in progress, subsequent threads will block until the read is completed and will then contend for the ability to read.

        Calling this method is equivalent to calling read(buffers, 0, buffers.length);

        Specified by:
        read in interface ScatteringByteChannel
        Parameters:
        buffers - the array of byte buffers into which the bytes will be copied.
        Returns:
        the number of bytes actually read.
        Throws:
        AsynchronousCloseException - if this channel is closed by another thread during this read operation.
        ClosedByInterruptException - if the thread is interrupted by another thread during this read operation.
        ClosedChannelException - if this channel is closed.
        IOException - if another I/O error occurs; details are in the message.
        NonReadableChannelException - if the channel has not been opened in a mode that permits reading.
      • read

        public abstract long read(ByteBuffer[] buffers,
                int start,
                int number)
                           throws IOException
        Reads bytes from this file channel into a subset of the given buffers. This method attempts to read all remaining() bytes from length byte buffers, in order, starting at targets[offset]. It increases the file position by the number of bytes actually read. The number of bytes actually read is returned.

        If a read operation is in progress, subsequent threads will block until the read is completed and will then contend for the ability to read.

        Specified by:
        read in interface ScatteringByteChannel
        Parameters:
        buffers - the array of byte buffers into which the bytes will be copied.
        start - the index of the first buffer to store bytes in.
        number - the maximum number of buffers to store bytes in.
        Returns:
        the number of bytes actually read.
        Throws:
        AsynchronousCloseException - if this channel is closed by another thread during this read operation.
        ClosedByInterruptException - if the thread is interrupted by another thread during this read operation.
        ClosedChannelException - if this channel is closed.
        IndexOutOfBoundsException - if start < 0 or number < 0, or if start + number is greater than the size of buffers.
        IOException - if another I/O error occurs; details are in the message.
        NonReadableChannelException - if the channel has not been opened in a mode that permits reading.
      • size

        public abstract long size()
                           throws IOException
        Returns the size of the file underlying this channel in bytes.
        Returns:
        the size of the file in bytes.
        Throws:
        ClosedChannelException - if this channel is closed.
        IOException - if an I/O error occurs while getting the size of the file.
      • transferFrom

        public abstract long transferFrom(ReadableByteChannel src,
                        long position,
                        long count)
                                   throws IOException
        Reads up to count bytes from src and stores them in this channel's file starting at position. No bytes are transferred if position is larger than the size of this channel's file. Less than count bytes are transferred if there are less bytes remaining in the source channel or if the source channel is non-blocking and has less than count bytes immediately available in its output buffer.

        Note that this channel's position is not modified.

        Parameters:
        src - the source channel to read bytes from.
        position - the non-negative start position.
        count - the non-negative number of bytes to transfer.
        Returns:
        the number of bytes that are transferred.
        Throws:
        IllegalArgumentException - if the parameters are invalid.
        NonReadableChannelException - if the source channel is not readable.
        NonWritableChannelException - if this channel is not writable.
        ClosedChannelException - if either channel has already been closed.
        AsynchronousCloseException - if either channel is closed by other threads during this operation.
        ClosedByInterruptException - if the thread is interrupted during this operation.
        IOException - if any I/O error occurs.
      • transferTo

        public abstract long transferTo(long position,
                      long count,
                      WritableByteChannel target)
                                 throws IOException
        Reads up to count bytes from this channel's file starting at position and writes them to target. No bytes are transferred if position is larger than the size of this channel's file. Less than count bytes are transferred if there less bytes available from this channel's file or if the target channel is non-blocking and has less than count bytes free in its input buffer.

        Note that this channel's position is not modified.

        Parameters:
        position - the non-negative position to begin.
        count - the non-negative number of bytes to transfer.
        target - the target channel to write to.
        Returns:
        the number of bytes that were transferred.
        Throws:
        IllegalArgumentException - if the parameters are invalid.
        NonReadableChannelException - if this channel is not readable.
        NonWritableChannelException - if the target channel is not writable.
        ClosedChannelException - if either channel has already been closed.
        AsynchronousCloseException - if either channel is closed by other threads during this operation.
        ClosedByInterruptException - if the thread is interrupted during this operation.
        IOException - if any I/O error occurs.
      • truncate

        public abstract FileChannel truncate(long size)
                                      throws IOException
        Truncates the file underlying this channel to a given size. Any bytes beyond the given size are removed from the file. If there are no bytes beyond the given size then the file contents are unmodified.

        If the file position is currently greater than the given size, then it is set to the new size.

        Parameters:
        size - the maximum size of the underlying file.
        Returns:
        this channel.
        Throws:
        IllegalArgumentException - if the requested size is negative.
        ClosedChannelException - if this channel is closed.
        NonWritableChannelException - if the channel cannot be written to.
        IOException - if another I/O error occurs.
      • tryLock

        public final FileLock tryLock()
                               throws IOException
        Attempts to acquire an exclusive lock on this file without blocking.

        This is a convenience method for attempting to acquire a maximum length lock on the file. It is equivalent to: fileChannel.tryLock(0L, Long.MAX_VALUE, false);

        The method returns null if the acquisition would result in an overlapped lock with another OS process.

        Returns:
        the file lock object, or null if the lock would overlap with an existing exclusive lock in another OS process.
        Throws:
        ClosedChannelException - if the file channel is closed.
        OverlappingFileLockException - if a lock already exists that overlaps this lock request or another thread is waiting to acquire a lock that will overlap with this request.
        IOException - if any I/O error occurs.
      • tryLock

        public abstract FileLock tryLock(long position,
                       long size,
                       boolean shared)
                                  throws IOException
        Attempts to acquire an exclusive lock on this file without blocking. The method returns null if the acquisition would result in an overlapped lock with another OS process.

        It is possible to acquire a lock for any region even if it's completely outside of the file's size. The size of the lock is fixed. If the file grows outside of the lock that region of the file won't be locked by this lock.

        Parameters:
        position - the starting position.
        size - the size of file to lock.
        shared - true if the lock is shared.
        Returns:
        the file lock object, or null if the lock would overlap with an existing exclusive lock in another OS process.
        Throws:
        IllegalArgumentException - if any parameters are invalid.
        ClosedChannelException - if the file channel is closed.
        OverlappingFileLockException - if a lock is already held that overlaps this lock request or another thread is waiting to acquire a lock that will overlap with this request.
        IOException - if any I/O error occurs.
      • write

        public abstract int write(ByteBuffer src)
                           throws IOException
        Writes bytes from the given byte buffer to this file channel.

        The bytes are written starting at the current file position, and after some number of bytes are written (up to the remaining number of bytes in the buffer) the file position is increased by the number of bytes actually written.

        Specified by:
        write in interface WritableByteChannel
        Parameters:
        src - the byte buffer containing the bytes to be written.
        Returns:
        the number of bytes actually written.
        Throws:
        NonWritableChannelException - if the channel was not opened for writing.
        ClosedChannelException - if the channel was already closed.
        AsynchronousCloseException - if another thread closes the channel during the write.
        ClosedByInterruptException - if another thread interrupts the calling thread while this operation is in progress. The interrupt state of the calling thread is set and the channel is closed.
        IOException - if another I/O error occurs, details are in the message.
        See Also:
        WritableByteChannel.write(java.nio.ByteBuffer)
      • write

        public abstract int write(ByteBuffer buffer,
                long position)
                           throws IOException
        Writes bytes from the given buffer to this file channel starting at the given file position.

        The bytes are written starting at the given file position (up to the remaining number of bytes in the buffer). The number of bytes actually written is returned.

        If the position is beyond the current end of file, then the file is first extended up to the given position by the required number of unspecified byte values.

        Note that the file position is not modified by this method.

        Parameters:
        buffer - the buffer containing the bytes to be written.
        position - the (non-negative) position at which to write the bytes.
        Returns:
        the number of bytes actually written.
        Throws:
        IllegalArgumentException - if position is less than 0.
        ClosedChannelException - if this channel is closed.
        NonWritableChannelException - if the channel was not opened in write-mode.
        AsynchronousCloseException - if this channel is closed by another thread while this method is executing.
        ClosedByInterruptException - if another thread interrupts the calling thread while this operation is in progress. The interrupt state of the calling thread is set and the channel is closed.
        IOException - if another I/O error occurs.
      • write

        public final long write(ByteBuffer[] buffers)
                         throws IOException
        Writes bytes from all the given byte buffers to this file channel.

        The bytes are written starting at the current file position, and after the bytes are written (up to the remaining number of bytes in all the buffers), the file position is increased by the number of bytes actually written.

        Calling this method is equivalent to calling write(buffers, 0, buffers.length);

        Specified by:
        write in interface GatheringByteChannel
        Parameters:
        buffers - the buffers containing bytes to write.
        Returns:
        the number of bytes actually written.
        Throws:
        AsynchronousCloseException - if this channel is closed by another thread during this write operation.
        ClosedByInterruptException - if another thread interrupts the calling thread while this operation is in progress. The interrupt state of the calling thread is set and the channel is closed.
        ClosedChannelException - if this channel is closed.
        IOException - if another I/O error occurs; details are in the message.
        NonWritableChannelException - if this channel was not opened for writing.
      • write

        public abstract long write(ByteBuffer[] buffers,
                 int offset,
                 int length)
                            throws IOException
        Attempts to write a subset of the given bytes from the buffers to this file channel. This method attempts to write all remaining() bytes from length byte buffers, in order, starting at sources[offset]. The number of bytes actually written is returned.

        If a write operation is in progress, subsequent threads will block until the write is completed and then contend for the ability to write.

        Specified by:
        write in interface GatheringByteChannel
        Parameters:
        buffers - the array of byte buffers that is the source for bytes written to this channel.
        offset - the index of the first buffer in buffers to get bytes from.
        length - the number of buffers to get bytes from.
        Returns:
        the number of bytes actually written to this channel.
        Throws:
        AsynchronousCloseException - if this channel is closed by another thread during this write operation.
        ClosedByInterruptException - if another thread interrupts the calling thread while this operation is in progress. The interrupt state of the calling thread is set and the channel is closed.
        ClosedChannelException - if this channel is closed.
        IndexOutOfBoundsException - if offset < 0 or length < 0, or if offset + length is greater than the size of buffers.
        IOException - if another I/O error occurs; details are in the message.
        NonWritableChannelException - if this channel was not opened for writing.


Content

Android Reference

Java basics

Java Enterprise Edition (EE)

Java Standard Edition (SE)

SQL

HTML

PHP

CSS

Java Script

MYSQL

JQUERY

VBS

REGEX

C

C++

C#

Design patterns

RFC (standard status)

RFC (proposed standard status)

RFC (draft standard status)

RFC (informational status)

RFC (experimental status)

RFC (best current practice status)

RFC (historic status)

RFC (unknown status)

IT dictionary

License.
All information of this service is derived from the free sources and is provided solely in the form of quotations. This service provides information and interfaces solely for the familiarization (not ownership) and under the "as is" condition.
Copyright 2016 © ELTASK.COM. All rights reserved.
Site is optimized for mobile devices.
Downloads: 1541 / . Delta: 0.02391 с