1 /*

     2  * Copyright (c) 2007, 2017, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package java.nio.channels;

    27 

    28 import java.nio.file.*;

    29 import java.nio.file.attribute.FileAttribute;

    30 import java.nio.file.spi.*;

    31 import java.nio.ByteBuffer;

    32 import java.io.IOException;

    33 import java.util.concurrent.Future;

    34 import java.util.concurrent.ExecutorService;

    35 import java.util.Set;

    36 import java.util.HashSet;

    37 import java.util.Collections;

    38 

    39 /**

    40  * An asynchronous channel for reading, writing, and manipulating a file.

    41  *

    42  * <p> An asynchronous file channel is created when a file is opened by invoking

    43  * one of the {@link #open open} methods defined by this class. The file contains

    44  * a variable-length sequence of bytes that can be read and written and whose

    45  * current size can be {@link #size() queried}. The size of the file increases

    46  * when bytes are written beyond its  current size; the size of the file decreases

    47  * when it is {@link #truncate truncated}.

    48  *

    49  * <p> An asynchronous file channel does not have a <i>current position</i>

    50  * within the file. Instead, the file position is specified to each read and

    51  * write method that initiates asynchronous operations. A {@link CompletionHandler}

    52  * is specified as a parameter and is invoked to consume the result of the I/O

    53  * operation. This class also defines read and write methods that initiate

    54  * asynchronous operations, returning a {@link Future} to represent the pending

    55  * result of the operation. The {@code Future} may be used to check if the

    56  * operation has completed, wait for its completion, and retrieve the result.

    57  *

    58  * <p> In addition to read and write operations, this class defines the

    59  * following operations: </p>

    60  *

    61  * <ul>

    62  *

    63  *   <li><p> Updates made to a file may be {@link #force <i>forced

    64  *   out</i>} to the underlying storage device, ensuring that data are not

    65  *   lost in the event of a system crash.  </p></li>

    66  *

    67  *   <li><p> A region of a file may be {@link #lock <i>locked</i>} against

    68  *   access by other programs.  </p></li>

    69  *

    70  * </ul>

    71  *

    72  * <p> An {@code AsynchronousFileChannel} is associated with a thread pool to

    73  * which tasks are submitted to handle I/O events and dispatch to completion

    74  * handlers that consume the results of I/O operations on the channel. The

    75  * completion handler for an I/O operation initiated on a channel is guaranteed

    76  * to be invoked by one of the threads in the thread pool (This ensures that the

    77  * completion handler is run by a thread with the expected <em>identity</em>).

    78  * Where an I/O operation completes immediately, and the initiating thread is

    79  * itself a thread in the thread pool, then the completion handler may be invoked

    80  * directly by the initiating thread. When an {@code AsynchronousFileChannel} is

    81  * created without specifying a thread pool then the channel is associated with

    82  * a system-dependent default thread pool that may be shared with other

    83  * channels. The default thread pool is configured by the system properties

    84  * defined by the {@link AsynchronousChannelGroup} class.

    85  *

    86  * <p> Channels of this type are safe for use by multiple concurrent threads. The

    87  * {@link Channel#close close} method may be invoked at any time, as specified

    88  * by the {@link Channel} interface. This causes all outstanding asynchronous

    89  * operations on the channel to complete with the exception {@link

    90  * AsynchronousCloseException}. Multiple read and write operations may be

    91  * outstanding at the same time. When multiple read and write operations are

    92  * outstanding then the ordering of the I/O operations, and the order that the

    93  * completion handlers are invoked, is not specified; they are not, in particular,

    94  * guaranteed to execute in the order that the operations were initiated. The

    95  * {@link java.nio.ByteBuffer ByteBuffers} used when reading or writing are not

    96  * safe for use by multiple concurrent I/O operations. Furthermore, after an I/O

    97  * operation is initiated then care should be taken to ensure that the buffer is

    98  * not accessed until after the operation has completed.

    99  *

   100  * <p> As with {@link FileChannel}, the view of a file provided by an instance of

   101  * this class is guaranteed to be consistent with other views of the same file

   102  * provided by other instances in the same program.  The view provided by an

   103  * instance of this class may or may not, however, be consistent with the views

   104  * seen by other concurrently-running programs due to caching performed by the

   105  * underlying operating system and delays induced by network-filesystem protocols.

   106  * This is true regardless of the language in which these other programs are

   107  * written, and whether they are running on the same machine or on some other

   108  * machine.  The exact nature of any such inconsistencies are system-dependent

   109  * and are therefore unspecified.

   110  *

   111  * @since 1.7

   112  */

   113 

   114 public abstract class AsynchronousFileChannel

   115     implements AsynchronousChannel

   116 {

   117     /**

   118      * Initializes a new instance of this class.

   119      */

   120     protected AsynchronousFileChannel() {

   121     }

   122 

   123     /**

   124      * Opens or creates a file for reading and/or writing, returning an

   125      * asynchronous file channel to access the file.

   126      *

   127      * <p> The {@code options} parameter determines how the file is opened.

   128      * The {@link StandardOpenOption#READ READ} and {@link StandardOpenOption#WRITE

   129      * WRITE} options determines if the file should be opened for reading and/or

   130      * writing. If neither option is contained in the array then an existing file

   131      * is opened for  reading.

   132      *

   133      * <p> In addition to {@code READ} and {@code WRITE}, the following options

   134      * may be present:

   135      *

   136      * <table class="striped">

   137      * <caption style="display:none">additional options</caption>

   138      * <thead>

   139      * <tr> <th scope="col">Option</th> <th scope="col">Description</th> </tr>

   140      * </thead>

   141      * <tbody>

   142      * <tr>

   143      *   <th scope="row"> {@link StandardOpenOption#TRUNCATE_EXISTING TRUNCATE_EXISTING} </th>

   144      *   <td> When opening an existing file, the file is first truncated to a

   145      *   size of 0 bytes. This option is ignored when the file is opened only

   146      *   for reading.</td>

   147      * </tr>

   148      * <tr>

   149      *   <th scope="row"> {@link StandardOpenOption#CREATE_NEW CREATE_NEW} </th>

   150      *   <td> If this option is present then a new file is created, failing if

   151      *   the file already exists. When creating a file the check for the

   152      *   existence of the file and the creation of the file if it does not exist

   153      *   is atomic with respect to other file system operations. This option is

   154      *   ignored when the file is opened only for reading. </td>

   155      * </tr>

   156      * <tr>

   157      *   <th scope="row" > {@link StandardOpenOption#CREATE CREATE} </th>

   158      *   <td> If this option is present then an existing file is opened if it

   159      *   exists, otherwise a new file is created. When creating a file the check

   160      *   for the existence of the file and the creation of the file if it does

   161      *   not exist is atomic with respect to other file system operations. This

   162      *   option is ignored if the {@code CREATE_NEW} option is also present or

   163      *   the file is opened only for reading. </td>

   164      * </tr>

   165      * <tr>

   166      *   <th scope="row" > {@link StandardOpenOption#DELETE_ON_CLOSE DELETE_ON_CLOSE} </th>

   167      *   <td> When this option is present then the implementation makes a

   168      *   <em>best effort</em> attempt to delete the file when closed by the

   169      *   the {@link #close close} method. If the {@code close} method is not

   170      *   invoked then a <em>best effort</em> attempt is made to delete the file

   171      *   when the Java virtual machine terminates. </td>

   172      * </tr>

   173      * <tr>

   174      *   <th scope="row">{@link StandardOpenOption#SPARSE SPARSE} </th>

   175      *   <td> When creating a new file this option is a <em>hint</em> that the

   176      *   new file will be sparse. This option is ignored when not creating

   177      *   a new file. </td>

   178      * </tr>

   179      * <tr>

   180      *   <th scope="row"> {@link StandardOpenOption#SYNC SYNC} </th>

   181      *   <td> Requires that every update to the file's content or metadata be

   182      *   written synchronously to the underlying storage device. (see <a

   183      *   href="../file/package-summary.html#integrity"> Synchronized I/O file

   184      *   integrity</a>). </td>

   185      * </tr>

   186      * <tr>

   187      *   <th scope="row"> {@link StandardOpenOption#DSYNC DSYNC} </th>

   188      *   <td> Requires that every update to the file's content be written

   189      *   synchronously to the underlying storage device. (see <a

   190      *   href="../file/package-summary.html#integrity"> Synchronized I/O file

   191      *   integrity</a>). </td>

   192      * </tr>

   193      * </tbody>

   194      * </table>

   195      *

   196      * <p> An implementation may also support additional options.

   197      *

   198      * <p> The {@code executor} parameter is the {@link ExecutorService} to

   199      * which tasks are submitted to handle I/O events and dispatch completion

   200      * results for operations initiated on resulting channel.

   201      * The nature of these tasks is highly implementation specific and so care

   202      * should be taken when configuring the {@code Executor}. Minimally it

   203      * should support an unbounded work queue and should not run tasks on the

   204      * caller thread of the {@link ExecutorService#execute execute} method.

   205      * Shutting down the executor service while the channel is open results in

   206      * unspecified behavior.

   207      *

   208      * <p> The {@code attrs} parameter is an optional array of file {@link

   209      * FileAttribute file-attributes} to set atomically when creating the file.

   210      *

   211      * <p> The new channel is created by invoking the {@link

   212      * FileSystemProvider#newFileChannel newFileChannel} method on the

   213      * provider that created the {@code Path}.

   214      *

   215      * @param   file

   216      *          The path of the file to open or create

   217      * @param   options

   218      *          Options specifying how the file is opened

   219      * @param   executor

   220      *          The thread pool or {@code null} to associate the channel with

   221      *          the default thread pool

   222      * @param   attrs

   223      *          An optional list of file attributes to set atomically when

   224      *          creating the file

   225      *

   226      * @return  A new asynchronous file channel

   227      *

   228      * @throws  IllegalArgumentException

   229      *          If the set contains an invalid combination of options

   230      * @throws  UnsupportedOperationException

   231      *          If the {@code file} is associated with a provider that does not

   232      *          support creating asynchronous file channels, or an unsupported

   233      *          open option is specified, or the array contains an attribute that

   234      *          cannot be set atomically when creating the file

   235      * @throws  IOException

   236      *          If an I/O error occurs

   237      * @throws  SecurityException

   238      *          If a security manager is installed and it denies an

   239      *          unspecified permission required by the implementation.

   240      *          In the case of the default provider, the {@link

   241      *          SecurityManager#checkRead(String)} method is invoked to check

   242      *          read access if the file is opened for reading. The {@link

   243      *          SecurityManager#checkWrite(String)} method is invoked to check

   244      *          write access if the file is opened for writing

   245      */

   246     public static AsynchronousFileChannel open(Path file,

   247                                                Set<? extends OpenOption> options,

   248                                                ExecutorService executor,

   249                                                FileAttribute<?>... attrs)

   250         throws IOException

   251     {

   252         FileSystemProvider provider = file.getFileSystem().provider();

   253         return provider.newAsynchronousFileChannel(file, options, executor, attrs);

   254     }

   255 

   256     @SuppressWarnings({"unchecked", "rawtypes"}) // generic array construction

   257     private static final FileAttribute<?>[] NO_ATTRIBUTES = new FileAttribute[0];

   258 

   259     /**

   260      * Opens or creates a file for reading and/or writing, returning an

   261      * asynchronous file channel to access the file.

   262      *

   263      * <p> An invocation of this method behaves in exactly the same way as the

   264      * invocation

   265      * <pre>

   266      *     ch.{@link #open(Path,Set,ExecutorService,FileAttribute[])

   267      *       open}(file, opts, null, new FileAttribute<?>[0]);

   268      * </pre>

   269      * where {@code opts} is a {@code Set} containing the options specified to

   270      * this method.

   271      *

   272      * <p> The resulting channel is associated with default thread pool to which

   273      * tasks are submitted to handle I/O events and dispatch to completion

   274      * handlers that consume the result of asynchronous operations performed on

   275      * the resulting channel.

   276      *

   277      * @param   file

   278      *          The path of the file to open or create

   279      * @param   options

   280      *          Options specifying how the file is opened

   281      *

   282      * @return  A new asynchronous file channel

   283      *

   284      * @throws  IllegalArgumentException

   285      *          If the set contains an invalid combination of options

   286      * @throws  UnsupportedOperationException

   287      *          If the {@code file} is associated with a provider that does not

   288      *          support creating file channels, or an unsupported open option is

   289      *          specified

   290      * @throws  IOException

   291      *          If an I/O error occurs

   292      * @throws  SecurityException

   293      *          If a security manager is installed and it denies an

   294      *          unspecified permission required by the implementation.

   295      *          In the case of the default provider, the {@link

   296      *          SecurityManager#checkRead(String)} method is invoked to check

   297      *          read access if the file is opened for reading. The {@link

   298      *          SecurityManager#checkWrite(String)} method is invoked to check

   299      *          write access if the file is opened for writing

   300      */

   301     public static AsynchronousFileChannel open(Path file, OpenOption... options)

   302         throws IOException

   303     {

   304         Set<OpenOption> set = new HashSet<>(options.length);

   305         Collections.addAll(set, options);

   306         return open(file, set, null, NO_ATTRIBUTES);

   307     }

   308 

   309     /**

   310      * Returns the current size of this channel's file.

   311      *

   312      * @return  The current size of this channel's file, measured in bytes

   313      *

   314      * @throws  ClosedChannelException

   315      *          If this channel is closed

   316      * @throws  IOException

   317      *          If some other I/O error occurs

   318      */

   319     public abstract long size() throws IOException;

   320 

   321     /**

   322      * Truncates this channel's file to the given size.

   323      *

   324      * <p> If the given size is less than the file's current size then the file

   325      * is truncated, discarding any bytes beyond the new end of the file.  If

   326      * the given size is greater than or equal to the file's current size then

   327      * the file is not modified. </p>

   328      *

   329      * @param  size

   330      *         The new size, a non-negative byte count

   331      *

   332      * @return  This file channel

   333      *

   334      * @throws  NonWritableChannelException

   335      *          If this channel was not opened for writing

   336      *

   337      * @throws  ClosedChannelException

   338      *          If this channel is closed

   339      *

   340      * @throws  IllegalArgumentException

   341      *          If the new size is negative

   342      *

   343      * @throws  IOException

   344      *          If some other I/O error occurs

   345      */

   346     public abstract AsynchronousFileChannel truncate(long size) throws IOException;

   347 

   348     /**

   349      * Forces any updates to this channel's file to be written to the storage

   350      * device that contains it.

   351      *

   352      * <p> If this channel's file resides on a local storage device then when

   353      * this method returns it is guaranteed that all changes made to the file

   354      * since this channel was created, or since this method was last invoked,

   355      * will have been written to that device.  This is useful for ensuring that

   356      * critical information is not lost in the event of a system crash.

   357      *

   358      * <p> If the file does not reside on a local device then no such guarantee

   359      * is made.

   360      *

   361      * <p> The {@code metaData} parameter can be used to limit the number of

   362      * I/O operations that this method is required to perform.  Passing

   363      * {@code false} for this parameter indicates that only updates to the

   364      * file's content need be written to storage; passing {@code true}

   365      * indicates that updates to both the file's content and metadata must be

   366      * written, which generally requires at least one more I/O operation.

   367      * Whether this parameter actually has any effect is dependent upon the

   368      * underlying operating system and is therefore unspecified.

   369      *

   370      * <p> Invoking this method may cause an I/O operation to occur even if the

   371      * channel was only opened for reading.  Some operating systems, for

   372      * example, maintain a last-access time as part of a file's metadata, and

   373      * this time is updated whenever the file is read.  Whether or not this is

   374      * actually done is system-dependent and is therefore unspecified.

   375      *

   376      * <p> This method is only guaranteed to force changes that were made to

   377      * this channel's file via the methods defined in this class.

   378      *

   379      * @param   metaData

   380      *          If {@code true} then this method is required to force changes

   381      *          to both the file's content and metadata to be written to

   382      *          storage; otherwise, it need only force content changes to be

   383      *          written

   384      *

   385      * @throws  ClosedChannelException

   386      *          If this channel is closed

   387      *

   388      * @throws  IOException

   389      *          If some other I/O error occurs

   390      */

   391     public abstract void force(boolean metaData) throws IOException;

   392 

   393     /**

   394      * Acquires a lock on the given region of this channel's file.

   395      *

   396      * <p> This method initiates an operation to acquire a lock on the given

   397      * region of this channel's file. The {@code handler} parameter is a

   398      * completion handler that is invoked when the lock is acquired (or the

   399      * operation fails). The result passed to the completion handler is the

   400      * resulting {@code FileLock}.

   401      *

   402      * <p> The region specified by the {@code position} and {@code size}

   403      * parameters need not be contained within, or even overlap, the actual

   404      * underlying file.  Lock regions are fixed in size; if a locked region

   405      * initially contains the end of the file and the file grows beyond the

   406      * region then the new portion of the file will not be covered by the lock.

   407      * If a file is expected to grow in size and a lock on the entire file is

   408      * required then a region starting at zero, and no smaller than the

   409      * expected maximum size of the file, should be locked.  The two-argument

   410      * {@link #lock(Object,CompletionHandler)} method simply locks a region

   411      * of size {@link Long#MAX_VALUE}. If a lock that overlaps the requested

   412      * region is already held by this Java virtual machine, or this method has

   413      * been invoked to lock an overlapping region and that operation has not

   414      * completed, then this method throws {@link OverlappingFileLockException}.

   415      *

   416      * <p> Some operating systems do not support a mechanism to acquire a file

   417      * lock in an asynchronous manner. Consequently an implementation may

   418      * acquire the file lock in a background thread or from a task executed by

   419      * a thread in the associated thread pool. If there are many lock operations

   420      * outstanding then it may consume threads in the Java virtual machine for

   421      * indefinite periods.

   422      *

   423      * <p> Some operating systems do not support shared locks, in which case a

   424      * request for a shared lock is automatically converted into a request for

   425      * an exclusive lock.  Whether the newly-acquired lock is shared or

   426      * exclusive may be tested by invoking the resulting lock object's {@link

   427      * FileLock#isShared() isShared} method.

   428      *

   429      * <p> File locks are held on behalf of the entire Java virtual machine.

   430      * They are not suitable for controlling access to a file by multiple

   431      * threads within the same virtual machine.

   432      *

   433      * @param   <A>

   434      *          The type of the attachment

   435      * @param   position

   436      *          The position at which the locked region is to start; must be

   437      *          non-negative

   438      * @param   size

   439      *          The size of the locked region; must be non-negative, and the sum

   440      *          {@code position} + {@code size} must be non-negative

   441      * @param   shared

   442      *          {@code true} to request a shared lock, in which case this

   443      *          channel must be open for reading (and possibly writing);

   444      *          {@code false} to request an exclusive lock, in which case this

   445      *          channel must be open for writing (and possibly reading)

   446      * @param   attachment

   447      *          The object to attach to the I/O operation; can be {@code null}

   448      * @param   handler

   449      *          The handler for consuming the result

   450      *

   451      * @throws  OverlappingFileLockException

   452      *          If a lock that overlaps the requested region is already held by

   453      *          this Java virtual machine, or there is already a pending attempt

   454      *          to lock an overlapping region

   455      * @throws  IllegalArgumentException

   456      *          If the preconditions on the parameters do not hold

   457      * @throws  NonReadableChannelException

   458      *          If {@code shared} is true but this channel was not opened for reading

   459      * @throws  NonWritableChannelException

   460      *          If {@code shared} is false but this channel was not opened for writing

   461      */

   462     public abstract <A> void lock(long position,

   463                                   long size,

   464                                   boolean shared,

   465                                   A attachment,

   466                                   CompletionHandler<FileLock,? super A> handler);

   467 

   468     /**

   469      * Acquires an exclusive lock on this channel's file.

   470      *

   471      * <p> This method initiates an operation to acquire a lock on the given

   472      * region of this channel's file. The {@code handler} parameter is a

   473      * completion handler that is invoked when the lock is acquired (or the

   474      * operation fails). The result passed to the completion handler is the

   475      * resulting {@code FileLock}.

   476      *

   477      * <p> An invocation of this method of the form {@code ch.lock(att,handler)}

   478      * behaves in exactly the same way as the invocation

   479      * <pre>

   480      *     ch.{@link #lock(long,long,boolean,Object,CompletionHandler) lock}(0L, Long.MAX_VALUE, false, att, handler)

   481      * </pre>

   482      *

   483      * @param   <A>

   484      *          The type of the attachment

   485      * @param   attachment

   486      *          The object to attach to the I/O operation; can be {@code null}

   487      * @param   handler

   488      *          The handler for consuming the result

   489      *

   490      * @throws  OverlappingFileLockException

   491      *          If a lock is already held by this Java virtual machine, or there

   492      *          is already a pending attempt to lock a region

   493      * @throws  NonWritableChannelException

   494      *          If this channel was not opened for writing

   495      */

   496     public final <A> void lock(A attachment,

   497                                CompletionHandler<FileLock,? super A> handler)

   498     {

   499         lock(0L, Long.MAX_VALUE, false, attachment, handler);

   500     }

   501 

   502     /**

   503      * Acquires a lock on the given region of this channel's file.

   504      *

   505      * <p> This method initiates an operation to acquire a lock on the given

   506      * region of this channel's file.  The method behaves in exactly the same

   507      * manner as the {@link #lock(long, long, boolean, Object, CompletionHandler)}

   508      * method except that instead of specifying a completion handler, this

   509      * method returns a {@code Future} representing the pending result. The

   510      * {@code Future}'s {@link Future#get() get} method returns the {@link

   511      * FileLock} on successful completion.

   512      *

   513      * @param   position

   514      *          The position at which the locked region is to start; must be

   515      *          non-negative

   516      * @param   size

   517      *          The size of the locked region; must be non-negative, and the sum

   518      *          {@code position} + {@code size} must be non-negative

   519      * @param   shared

   520      *          {@code true} to request a shared lock, in which case this

   521      *          channel must be open for reading (and possibly writing);

   522      *          {@code false} to request an exclusive lock, in which case this

   523      *          channel must be open for writing (and possibly reading)

   524      *

   525      * @return  a {@code Future} object representing the pending result

   526      *

   527      * @throws  OverlappingFileLockException

   528      *          If a lock is already held by this Java virtual machine, or there

   529      *          is already a pending attempt to lock a region

   530      * @throws  IllegalArgumentException

   531      *          If the preconditions on the parameters do not hold

   532      * @throws  NonReadableChannelException

   533      *          If {@code shared} is true but this channel was not opened for reading

   534      * @throws  NonWritableChannelException

   535      *          If {@code shared} is false but this channel was not opened for writing

   536      */

   537     public abstract Future<FileLock> lock(long position, long size, boolean shared);

   538 

   539     /**

   540      * Acquires an exclusive lock on this channel's file.

   541      *

   542      * <p> This method initiates an operation to acquire an exclusive lock on this

   543      * channel's file. The method returns a {@code Future} representing the

   544      * pending result of the operation. The {@code Future}'s {@link Future#get()

   545      * get} method returns the {@link FileLock} on successful completion.

   546      *

   547      * <p> An invocation of this method behaves in exactly the same way as the

   548      * invocation

   549      * <pre>

   550      *     ch.{@link #lock(long,long,boolean) lock}(0L, Long.MAX_VALUE, false)

   551      * </pre>

   552      *

   553      * @return  a {@code Future} object representing the pending result

   554      *

   555      * @throws  OverlappingFileLockException

   556      *          If a lock is already held by this Java virtual machine, or there

   557      *          is already a pending attempt to lock a region

   558      * @throws  NonWritableChannelException

   559      *          If this channel was not opened for writing

   560      */

   561     public final Future<FileLock> lock() {

   562         return lock(0L, Long.MAX_VALUE, false);

   563     }

   564 

   565     /**

   566      * Attempts to acquire a lock on the given region of this channel's file.

   567      *

   568      * <p> This method does not block. An invocation always returns immediately,

   569      * either having acquired a lock on the requested region or having failed to

   570      * do so.  If it fails to acquire a lock because an overlapping lock is held

   571      * by another program then it returns {@code null}.  If it fails to acquire

   572      * a lock for any other reason then an appropriate exception is thrown.

   573      *

   574      * @param  position

   575      *         The position at which the locked region is to start; must be

   576      *         non-negative

   577      *

   578      * @param  size

   579      *         The size of the locked region; must be non-negative, and the sum

   580      *         {@code position} + {@code size} must be non-negative

   581      *

   582      * @param  shared

   583      *         {@code true} to request a shared lock,

   584      *         {@code false} to request an exclusive lock

   585      *

   586      * @return  A lock object representing the newly-acquired lock,

   587      *          or {@code null} if the lock could not be acquired

   588      *          because another program holds an overlapping lock

   589      *

   590      * @throws  IllegalArgumentException

   591      *          If the preconditions on the parameters do not hold

   592      * @throws  ClosedChannelException

   593      *          If this channel is closed

   594      * @throws  OverlappingFileLockException

   595      *          If a lock that overlaps the requested region is already held by

   596      *          this Java virtual machine, or if another thread is already

   597      *          blocked in this method and is attempting to lock an overlapping

   598      *          region of the same file

   599      * @throws  NonReadableChannelException

   600      *          If {@code shared} is true but this channel was not opened for reading

   601      * @throws  NonWritableChannelException

   602      *          If {@code shared} is false but this channel was not opened for writing

   603      *

   604      * @throws  IOException

   605      *          If some other I/O error occurs

   606      *

   607      * @see     #lock(Object,CompletionHandler)

   608      * @see     #lock(long,long,boolean,Object,CompletionHandler)

   609      * @see     #tryLock()

   610      */

   611     public abstract FileLock tryLock(long position, long size, boolean shared)

   612         throws IOException;

   613 

   614     /**

   615      * Attempts to acquire an exclusive lock on this channel's file.

   616      *

   617      * <p> An invocation of this method of the form {@code ch.tryLock()}

   618      * behaves in exactly the same way as the invocation

   619      *

   620      * <pre>

   621      *     ch.{@link #tryLock(long,long,boolean) tryLock}(0L, Long.MAX_VALUE, false) </pre>

   622      *

   623      * @return  A lock object representing the newly-acquired lock,

   624      *          or {@code null} if the lock could not be acquired

   625      *          because another program holds an overlapping lock

   626      *

   627      * @throws  ClosedChannelException

   628      *          If this channel is closed

   629      * @throws  OverlappingFileLockException

   630      *          If a lock that overlaps the requested region is already held by

   631      *          this Java virtual machine, or if another thread is already

   632      *          blocked in this method and is attempting to lock an overlapping

   633      *          region

   634      * @throws  NonWritableChannelException

   635      *          If {@code shared} is false but this channel was not opened for writing

   636      *

   637      * @throws  IOException

   638      *          If some other I/O error occurs

   639      *

   640      * @see     #lock(Object,CompletionHandler)

   641      * @see     #lock(long,long,boolean,Object,CompletionHandler)

   642      * @see     #tryLock(long,long,boolean)

   643      */

   644     public final FileLock tryLock() throws IOException {

   645         return tryLock(0L, Long.MAX_VALUE, false);

   646     }

   647 

   648     /**

   649      * Reads a sequence of bytes from this channel into the given buffer,

   650      * starting at the given file position.

   651      *

   652      * <p> This method initiates the reading of a sequence of bytes from this

   653      * channel into the given buffer, starting at the given file position. The

   654      * result of the read is the number of bytes read or {@code -1} if the given

   655      * position is greater than or equal to the file's size at the time that the

   656      * read is attempted.

   657      *

   658      * <p> This method works in the same manner as the {@link

   659      * AsynchronousByteChannel#read(ByteBuffer,Object,CompletionHandler)}

   660      * method, except that bytes are read starting at the given file position.

   661      * If the given file position is greater than the file's size at the time

   662      * that the read is attempted then no bytes are read.

   663      *

   664      * @param   <A>

   665      *          The type of the attachment

   666      * @param   dst

   667      *          The buffer into which bytes are to be transferred

   668      * @param   position

   669      *          The file position at which the transfer is to begin;

   670      *          must be non-negative

   671      * @param   attachment

   672      *          The object to attach to the I/O operation; can be {@code null}

   673      * @param   handler

   674      *          The handler for consuming the result

   675      *

   676      * @throws  IllegalArgumentException

   677      *          If the position is negative or the buffer is read-only

   678      * @throws  NonReadableChannelException

   679      *          If this channel was not opened for reading

   680      */

   681     public abstract <A> void read(ByteBuffer dst,

   682                                   long position,

   683                                   A attachment,

   684                                   CompletionHandler<Integer,? super A> handler);

   685 

   686     /**

   687      * Reads a sequence of bytes from this channel into the given buffer,

   688      * starting at the given file position.

   689      *

   690      * <p> This method initiates the reading of a sequence of bytes from this

   691      * channel into the given buffer, starting at the given file position. This

   692      * method returns a {@code Future} representing the pending result of the

   693      * operation. The {@code Future}'s {@link Future#get() get} method returns

   694      * the number of bytes read or {@code -1} if the given position is greater

   695      * than or equal to the file's size at the time that the read is attempted.

   696      *

   697      * <p> This method works in the same manner as the {@link

   698      * AsynchronousByteChannel#read(ByteBuffer)} method, except that bytes are

   699      * read starting at the given file position. If the given file position is

   700      * greater than the file's size at the time that the read is attempted then

   701      * no bytes are read.

   702      *

   703      * @param   dst

   704      *          The buffer into which bytes are to be transferred

   705      * @param   position

   706      *          The file position at which the transfer is to begin;

   707      *          must be non-negative

   708      *

   709      * @return  A {@code Future} object representing the pending result

   710      *

   711      * @throws  IllegalArgumentException

   712      *          If the position is negative or the buffer is read-only

   713      * @throws  NonReadableChannelException

   714      *          If this channel was not opened for reading

   715      */

   716     public abstract Future<Integer> read(ByteBuffer dst, long position);

   717 

   718     /**

   719      * Writes a sequence of bytes to this channel from the given buffer, starting

   720      * at the given file position.

   721      *

   722      * <p> This method works in the same manner as the {@link

   723      * AsynchronousByteChannel#write(ByteBuffer,Object,CompletionHandler)}

   724      * method, except that bytes are written starting at the given file position.

   725      * If the given position is greater than the file's size, at the time that

   726      * the write is attempted, then the file will be grown to accommodate the new

   727      * bytes; the values of any bytes between the previous end-of-file and the

   728      * newly-written bytes are unspecified.

   729      *

   730      * @param   <A>

   731      *          The type of the attachment

   732      * @param   src

   733      *          The buffer from which bytes are to be transferred

   734      * @param   position

   735      *          The file position at which the transfer is to begin;

   736      *          must be non-negative

   737      * @param   attachment

   738      *          The object to attach to the I/O operation; can be {@code null}

   739      * @param   handler

   740      *          The handler for consuming the result

   741      *

   742      * @throws  IllegalArgumentException

   743      *          If the position is negative

   744      * @throws  NonWritableChannelException

   745      *          If this channel was not opened for writing

   746      */

   747     public abstract <A> void write(ByteBuffer src,

   748                                    long position,

   749                                    A attachment,

   750                                    CompletionHandler<Integer,? super A> handler);

   751 

   752     /**

   753      * Writes a sequence of bytes to this channel from the given buffer, starting

   754      * at the given file position.

   755      *

   756      * <p> This method initiates the writing of a sequence of bytes to this

   757      * channel from the given buffer, starting at the given file position. The

   758      * method returns a {@code Future} representing the pending result of the

   759      * write operation. The {@code Future}'s {@link Future#get() get} method

   760      * returns the number of bytes written.

   761      *

   762      * <p> This method works in the same manner as the {@link

   763      * AsynchronousByteChannel#write(ByteBuffer)} method, except that bytes are

   764      * written starting at the given file position. If the given position is

   765      * greater than the file's size, at the time that the write is attempted,

   766      * then the file will be grown to accommodate the new bytes; the values of

   767      * any bytes between the previous end-of-file and the newly-written bytes

   768      * are unspecified.

   769      *

   770      * @param   src

   771      *          The buffer from which bytes are to be transferred

   772      * @param   position

   773      *          The file position at which the transfer is to begin;

   774      *          must be non-negative

   775      *

   776      * @return  A {@code Future} object representing the pending result

   777      *

   778      * @throws  IllegalArgumentException

   779      *          If the position is negative

   780      * @throws  NonWritableChannelException

   781      *          If this channel was not opened for writing

   782      */

   783     public abstract Future<Integer> write(ByteBuffer src, long position);

   784 }