|
Read-only: Any attempt to modify the resulting buffer * will cause a {@link java.nio.ReadOnlyBufferException} to be thrown. * ({@link MapMode#READ_ONLY MapMode.READ_ONLY}) </p> * * <li>
Read/write: Changes made to the resulting buffer will * eventually be propagated to the file; they may or may not be made * visible to other programs that have mapped the same file. ({@link * MapMode#READ_WRITE MapMode.READ_WRITE}) </p> * * <li>
Private: Changes made to the resulting buffer will not * be propagated to the file and will not be visible to other programs * that have mapped the same file; instead, they will cause private * copies of the modified portions of the buffer to be created. ({@link * MapMode#PRIVATE MapMode.PRIVATE}) </p> * * </ul> * * <p> For a read-only mapping, this channel must have been opened for * reading; for a read/write or private mapping, this channel must have * been opened for both reading and writing. * * <p> The {@link MappedByteBuffer mapped byte buffer} * returned by this method will have a position of zero and a limit and * capacity of <tt>size; its mark will be undefined. The buffer and * the mapping that it represents will remain valid until the buffer itself * is garbage-collected. * * <p> A mapping, once established, is not dependent upon the file channel * that was used to create it. Closing the channel, in particular, has no * effect upon the validity of the mapping. * * <p> Many of the details of memory-mapped files are inherently dependent * upon the underlying operating system and are therefore unspecified. The * behavior of this method when the requested region is not completely * contained within this channel's file is unspecified. Whether changes * made to the content or size of the underlying file, by this program or * another, are propagated to the buffer is unspecified. The rate at which * changes to the buffer are propagated to the file is unspecified. * * <p> For most operating systems, mapping a file into memory is more * expensive than reading or writing a few tens of kilobytes of data via * the usual {@link #read read} and {@link #write write} methods. From the * standpoint of performance it is generally only worth mapping relatively * large files into memory. </p> * * @param mode * One of the constants {@link MapMode#READ_ONLY READ_ONLY}, {@link * MapMode#READ_WRITE READ_WRITE}, or {@link MapMode#PRIVATE * PRIVATE} defined in the {@link MapMode} class, according to * whether the file is to be mapped read-only, read/write, or * privately (copy-on-write), respectively * * @param position * The position within the file at which the mapped region * is to start; must be non-negative * * @param size * The size of the region to be mapped; must be non-negative and * no greater than {@link java.lang.Integer#MAX_VALUE} * * @return The mapped byte buffer * * @throws NonReadableChannelException * If the <tt>mode is {@link MapMode#READ_ONLY READ_ONLY} but * this channel was not opened for reading * * @throws NonWritableChannelException * If the <tt>mode is {@link MapMode#READ_WRITE READ_WRITE} or * {@link MapMode#PRIVATE PRIVATE} but this channel was not opened * for both reading and writing * * @throws IllegalArgumentException * If the preconditions on the parameters do not hold * * @throws IOException * If some other I/O error occurs * * @see java.nio.channels.FileChannel.MapMode * @see java.nio.MappedByteBuffer */ public abstract MappedByteBuffer map(MapMode mode, long position, long size) throws IOException; // -- Locks -- /** * Acquires a lock on the given region of this channel's file. * * <p> An invocation of this method will block until the region can be * locked, this channel is closed, or the invoking thread is interrupted, * whichever comes first. * * <p> If this channel is closed by another thread during an invocation of * this method then an {@link AsynchronousCloseException} will be thrown. * * <p> If the invoking thread is interrupted while waiting to acquire the * lock then its interrupt status will be set and a {@link * FileLockInterruptionException} will be thrown. If the invoker's * interrupt status is set when this method is invoked then that exception * will be thrown immediately; the thread's interrupt status will not be * changed. * * <p> The region specified by the position and size * parameters need not be contained within, or even overlap, the actual * underlying file. Lock regions are fixed in size; if a locked region * initially contains the end of the file and the file grows beyond the * region then the new portion of the file will not be covered by the lock. * If a file is expected to grow in size and a lock on the entire file is * required then a region starting at zero, and no smaller than the * expected maximum size of the file, should be locked. The zero-argument * {@link #lock()} method simply locks a region of size {@link * Long#MAX_VALUE}. * * <p> Some operating systems do not support shared locks, in which case a * request for a shared lock is automatically converted into a request for * an exclusive lock. Whether the newly-acquired lock is shared or * exclusive may be tested by invoking the resulting lock object's {@link * FileLock#isShared() isShared} method. * * <p> File locks are held on behalf of the entire Java virtual machine. * They are not suitable for controlling access to a file by multiple * threads within the same virtual machine. </p> * * @param position * The position at which the locked region is to start; must be * non-negative * * @param size * The size of the locked region; must be non-negative, and the sum * <tt>position + size must be non-negative * * @param shared * <tt>true to request a shared lock, in which case this * channel must be open for reading (and possibly writing); * <tt>false to request an exclusive lock, in which case this * channel must be open for writing (and possibly reading) * * @return A lock object representing the newly-acquired lock * * @throws IllegalArgumentException * If the preconditions on the parameters do not hold * * @throws ClosedChannelException * If this channel is closed * * @throws AsynchronousCloseException * If another thread closes this channel while the invoking * thread is blocked in this method * * @throws FileLockInterruptionException * If the invoking thread is interrupted while blocked in this * method * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region * * @throws NonReadableChannelException * If <tt>shared is true this channel was not * opened for reading * * @throws NonWritableChannelException * If <tt>shared is false but this channel was not * opened for writing * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #tryLock() * @see #tryLock(long,long,boolean) */ public abstract FileLock lock(long position, long size, boolean shared) throws IOException; /** * Acquires an exclusive lock on this channel's file. * * <p> An invocation of this method of the form fc.lock() behaves * in exactly the same way as the invocation * * <pre> * fc.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false) </pre> * * @return A lock object representing the newly-acquired lock * * @throws ClosedChannelException * If this channel is closed * * @throws AsynchronousCloseException * If another thread closes this channel while the invoking * thread is blocked in this method * * @throws FileLockInterruptionException * If the invoking thread is interrupted while blocked in this * method * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region of the same file * * @throws NonWritableChannelException * If this channel was not opened for writing * * @throws IOException * If some other I/O error occurs * * @see #lock(long,long,boolean) * @see #tryLock() * @see #tryLock(long,long,boolean) */ public final FileLock lock() throws IOException { return lock(0L, Long.MAX_VALUE, false); } /** * Attempts to acquire a lock on the given region of this channel's file. * * <p> This method does not block. An invocation always returns * immediately, either having acquired a lock on the requested region or * having failed to do so. If it fails to acquire a lock because an * overlapping lock is held by another program then it returns * <tt>null. If it fails to acquire a lock for any other reason then * an appropriate exception is thrown. * * <p> The region specified by the position and size * parameters need not be contained within, or even overlap, the actual * underlying file. Lock regions are fixed in size; if a locked region * initially contains the end of the file and the file grows beyond the * region then the new portion of the file will not be covered by the lock. * If a file is expected to grow in size and a lock on the entire file is * required then a region starting at zero, and no smaller than the * expected maximum size of the file, should be locked. The zero-argument * {@link #tryLock()} method simply locks a region of size {@link * Long#MAX_VALUE}. * * <p> Some operating systems do not support shared locks, in which case a * request for a shared lock is automatically converted into a request for * an exclusive lock. Whether the newly-acquired lock is shared or * exclusive may be tested by invoking the resulting lock object's {@link * FileLock#isShared() isShared} method. * * <p> File locks are held on behalf of the entire Java virtual machine. * They are not suitable for controlling access to a file by multiple * threads within the same virtual machine. </p> * * @param position * The position at which the locked region is to start; must be * non-negative * * @param size * The size of the locked region; must be non-negative, and the sum * <tt>position + size must be non-negative * * @param shared * <tt>true to request a shared lock, * <tt>false to request an exclusive lock * * @return A lock object representing the newly-acquired lock, * or <tt>null if the lock could not be acquired * because another program holds an overlapping lock * * @throws IllegalArgumentException * If the preconditions on the parameters do not hold * * @throws ClosedChannelException * If this channel is closed * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region of the same file * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #lock(long,long,boolean) * @see #tryLock() */ public abstract FileLock tryLock(long position, long size, boolean shared) throws IOException; /** * Attempts to acquire an exclusive lock on this channel's file. * * <p> An invocation of this method of the form fc.tryLock() * behaves in exactly the same way as the invocation * * <pre> * fc.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre> * * @return A lock object representing the newly-acquired lock, * or <tt>null if the lock could not be acquired * because another program holds an overlapping lock * * @throws ClosedChannelException * If this channel is closed * * @throws OverlappingFileLockException * If a lock that overlaps the requested region is already held by * this Java virtual machine, or if another thread is already * blocked in this method and is attempting to lock an overlapping * region * * @throws IOException * If some other I/O error occurs * * @see #lock() * @see #lock(long,long,boolean) * @see #tryLock(long,long,boolean) */ public final FileLock tryLock() throws IOException { return tryLock(0L, Long.MAX_VALUE, false); } }
Here is a short list of links related to this Java FileChannel.java source code file:
Java example source code file (FileChannel.java)
The FileChannel.java Java example source code/* * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.nio.channels; import java.io.*; import java.nio.ByteBuffer; import java.nio.MappedByteBuffer; import java.nio.channels.spi.AbstractInterruptibleChannel; import java.nio.file.*; import java.nio.file.attribute.FileAttribute; import java.nio.file.spi.*; import java.util.Set; import java.util.HashSet; import java.util.Collections; /** * A channel for reading, writing, mapping, and manipulating a file. * * <p> A file channel is a {@link SeekableByteChannel} that is connected to * a file. It has a current <i>position within its file which can * be both {@link #position() <i>queried} and {@link #position(long) * <i>modified}. The file itself contains a variable-length sequence * of bytes that can be read and written and whose current {@link #size * <i>size} can be queried. The size of the file increases * when bytes are written beyond its current size; the size of the file * decreases when it is {@link #truncate <i>truncated}. The * file may also have some associated <i>metadata such as access * permissions, content type, and last-modification time; this class does not * define methods for metadata access. * * <p> In addition to the familiar read, write, and close operations of byte * channels, this class defines the following file-specific operations: </p> * * <ul> * * <li> | Option | Description |
---|
... this post is sponsored by my books ... | |
#1 New Release! |
FP Best Seller |
Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.
A percentage of advertising revenue from
pages under the /java/jwarehouse
URI on this website is
paid back to open source projects.