1 /*

     2  * Copyright 2007-2009 Sun Microsystems, Inc.  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.  Sun designates this

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

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.nio.channels;

    27 

    28 import java.nio.ByteBuffer;

    29 import java.io.IOException;

    30 

    31 /**

    32  * A byte channel that maintains a current <i>position</i> and allows the

    33  * position to be changed.

    34  *

    35  * <p> A seekable byte channel is connected to an entity, typically a file,

    36  * that contains a variable-length sequence of bytes that can be read and

    37  * written. The current position can be {@link #position() <i>queried</i>} and

    38  * {@link #position(long) <i>modified</i>}. The channel also provides access to

    39  * the current <i>size</i> of the entity to which the channel is connected. The

    40  * size increases when bytes are written beyond its current size; the size

    41  * decreases when it is {@link #truncate <i>truncated</i>}.

    42  *

    43  * <p> The {@link #position(long) position} and {@link #truncate truncate} methods

    44  * which do not otherwise have a value to return are specified to return the

    45  * channel upon which they are invoked. This allows method invocations to be

    46  * chained. Implementations of this interface should specialize the return type

    47  * so that method invocations on the implementation class can be chained.

    48  *

    49  * @since 1.7

    50  * @see java.nio.file.FileRef#newByteChannel

    51  */

    52 

    53 public interface SeekableByteChannel

    54     extends ByteChannel

    55 {

    56     /**

    57      * Reads a sequence of bytes from this channel into the given buffer.

    58      *

    59      * <p> Bytes are read starting at this channel's current position, and

    60      * then the position is updated with the number of bytes actually read.

    61      * Otherwise this method behaves exactly as specified in the {@link

    62      * ReadableByteChannel} interface.

    63      */

    64     @Override

    65     int read(ByteBuffer dst) throws IOException;

    66 

    67     /**

    68      * Writes a sequence of bytes to this channel from the given buffer.

    69      *

    70      * <p> Bytes are written starting at this channel's current position, unless

    71      * the channel is connected to an entity such as a file that is opened with

    72      * the {@link java.nio.file.StandardOpenOption#APPEND APPEND} option, in

    73      * which case the position is first advanced to the end. The entity to which

    74      * the channel is connected is grown, if necessary, to accommodate the

    75      * written bytes, and then the position is updated with the number of bytes

    76      * actually written. Otherwise this method behaves exactly as specified by

    77      * the {@link WritableByteChannel} interface.

    78      */

    79     @Override

    80     int write(ByteBuffer src) throws IOException;

    81 

    82     /**

    83      * Returns this channel's position.

    84      *

    85      * @return  This channel's position,

    86      *          a non-negative integer counting the number of bytes

    87      *          from the beginning of the entity to the current position

    88      *

    89      * @throws  ClosedChannelException

    90      *          If this channel is closed

    91      * @throws  IOException

    92      *          If some other I/O error occurs

    93      */

    94     long position() throws IOException;

    95 

    96     /**

    97      * Sets this channel's position.

    98      *

    99      * <p> Setting the position to a value that is greater than the current size

   100      * is legal but does not change the size of the entity.  A later attempt to

   101      * read bytes at such a position will immediately return an end-of-file

   102      * indication.  A later attempt to write bytes at such a position will cause

   103      * the entity to grow to accommodate the new bytes; the values of any bytes

   104      * between the previous end-of-file and the newly-written bytes are

   105      * unspecified.

   106      *

   107      * <p> Setting the channel's position is not recommended when connected to

   108      * an entity, typically a file, that is opened with the {@link

   109      * java.nio.file.StandardOpenOption#APPEND APPEND} option. When opened for

   110      * append, the position is first advanced to the end before writing.

   111      *

   112      * @param  newPosition

   113      *         The new position, a non-negative integer counting

   114      *         the number of bytes from the beginning of the entity

   115      *

   116      * @return  This channel

   117      *

   118      * @throws  ClosedChannelException

   119      *          If this channel is closed

   120      * @throws  IllegalArgumentException

   121      *          If the new position is negative

   122      * @throws  IOException

   123      *          If some other I/O error occurs

   124      */

   125     SeekableByteChannel position(long newPosition) throws IOException;

   126 

   127     /**

   128      * Returns the current size of entity to which this channel is connected.

   129      *

   130      * @return  The current size, measured in bytes

   131      *

   132      * @throws  ClosedChannelException

   133      *          If this channel is closed

   134      * @throws  IOException

   135      *          If some other I/O error occurs

   136      */

   137     long size() throws IOException;

   138 

   139     /**

   140      * Truncates the entity, to which this channel is connected, to the given

   141      * size.

   142      *

   143      * <p> If the given size is less than the current size then the entity is

   144      * truncated, discarding any bytes beyond the new end. If the given size is

   145      * greater than or equal to the current size then the entity is not modified.

   146      * In either case, if the current position is greater than the given size

   147      * then it is set to that size.

   148      *

   149      * <p> An implementation of this interface may prohibit truncation when

   150      * connected to an entity, typically a file, opened with the {@link

   151      * java.nio.file.StandardOpenOption#APPEND APPEND} option.

   152      *

   153      * @param  size

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

   155      *

   156      * @return  This channel

   157      *

   158      * @throws  NonWritableChannelException

   159      *          If this channel was not opened for writing

   160      * @throws  ClosedChannelException

   161      *          If this channel is closed

   162      * @throws  IllegalArgumentException

   163      *          If the new size is negative

   164      * @throws  IOException

   165      *          If some other I/O error occurs

   166      */

   167     SeekableByteChannel truncate(long size) throws IOException;

   168 }