1 /* 2 * Copyright (c) 2007, 2013, 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.ByteBuffer; 29 import java.util.concurrent.Future; 30 31 /** 32 * An asynchronous channel that can read and write bytes. 33 * 34 * <p> Some channels may not allow more than one read or write to be outstanding 35 * at any given time. If a thread invokes a read method before a previous read 36 * operation has completed then a {@link ReadPendingException} will be thrown. 37 * Similarly, if a write method is invoked before a previous write has completed 38 * then {@link WritePendingException} is thrown. Whether or not other kinds of 39 * I/O operations may proceed concurrently with a read operation depends upon 40 * the type of the channel. 41 * 42 * <p> Note that {@link java.nio.ByteBuffer ByteBuffers} are not safe for use by 43 * multiple concurrent threads. When a read or write operation is initiated then 44 * care must be taken to ensure that the buffer is not accessed until the 45 * operation completes. 46 * 47 * @see Channels#newInputStream(AsynchronousByteChannel) 48 * @see Channels#newOutputStream(AsynchronousByteChannel) 49 * 50 * @since 1.7 51 */ 52 53 public interface AsynchronousByteChannel 54 extends AsynchronousChannel 55 { 56 /** 57 * Reads a sequence of bytes from this channel into the given buffer. 58 * 59 * <p> This method initiates an asynchronous read operation to read a 60 * sequence of bytes from this channel into the given buffer. The {@code 61 * handler} parameter is a completion handler that is invoked when the read 62 * operation completes (or fails). The result passed to the completion 63 * handler is the number of bytes read or {@code -1} if no bytes could be 64 * read because the channel has reached end-of-stream. 65 * 66 * <p> The read operation may read up to <i>r</i> bytes from the channel, 67 * where <i>r</i> is the number of bytes remaining in the buffer, that is, 68 * {@code dst.remaining()} at the time that the read is attempted. Where 69 * <i>r</i> is 0, the read operation completes immediately with a result of 70 * {@code 0} without initiating an I/O operation. 71 * 72 * <p> Suppose that a byte sequence of length <i>n</i> is read, where 73 * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. 74 * This byte sequence will be transferred into the buffer so that the first 75 * byte in the sequence is at index <i>p</i> and the last byte is at index 76 * <i>p</i> <tt>+</tt> <i>n</i> <tt>-</tt> <tt>1</tt>, 77 * where <i>p</i> is the buffer's position at the moment the read is 78 * performed. Upon completion the buffer's position will be equal to 79 * <i>p</i> <tt>+</tt> <i>n</i>; its limit will not have changed. 80 * 81 * <p> Buffers are not safe for use by multiple concurrent threads so care 82 * should be taken to not access the buffer until the operation has 83 * completed. 84 * 85 * <p> This method may be invoked at any time. Some channel types may not 86 * allow more than one read to be outstanding at any given time. If a thread 87 * initiates a read operation before a previous read operation has 88 * completed then a {@link ReadPendingException} will be thrown. 89 * 90 * @param <A> 91 * The type of the attachment 92 * @param dst 93 * The buffer into which bytes are to be transferred 94 * @param attachment 95 * The object to attach to the I/O operation; can be {@code null} 96 * @param handler 97 * The completion handler 98 * 99 * @throws IllegalArgumentException 100 * If the buffer is read-only 101 * @throws ReadPendingException 102 * If the channel does not allow more than one read to be outstanding 103 * and a previous read has not completed 104 * @throws ShutdownChannelGroupException 105 * If the channel is associated with a {@link AsynchronousChannelGroup 106 * group} that has terminated 107 */ read(ByteBuffer dst, A attachment, CompletionHandler<Integer,? super A> handler)108 <A> void read(ByteBuffer dst, 109 A attachment, 110 CompletionHandler<Integer,? super A> handler); 111 112 /** 113 * Reads a sequence of bytes from this channel into the given buffer. 114 * 115 * <p> This method initiates an asynchronous read operation to read a 116 * sequence of bytes from this channel into the given buffer. The method 117 * behaves in exactly the same manner as the {@link 118 * #read(ByteBuffer,Object,CompletionHandler) 119 * read(ByteBuffer,Object,CompletionHandler)} method except that instead 120 * of specifying a completion handler, this method returns a {@code Future} 121 * representing the pending result. The {@code Future}'s {@link Future#get() 122 * get} method returns the number of bytes read or {@code -1} if no bytes 123 * could be read because the channel has reached end-of-stream. 124 * 125 * @param dst 126 * The buffer into which bytes are to be transferred 127 * 128 * @return A Future representing the result of the operation 129 * 130 * @throws IllegalArgumentException 131 * If the buffer is read-only 132 * @throws ReadPendingException 133 * If the channel does not allow more than one read to be outstanding 134 * and a previous read has not completed 135 */ read(ByteBuffer dst)136 Future<Integer> read(ByteBuffer dst); 137 138 /** 139 * Writes a sequence of bytes to this channel from the given buffer. 140 * 141 * <p> This method initiates an asynchronous write operation to write a 142 * sequence of bytes to this channel from the given buffer. The {@code 143 * handler} parameter is a completion handler that is invoked when the write 144 * operation completes (or fails). The result passed to the completion 145 * handler is the number of bytes written. 146 * 147 * <p> The write operation may write up to <i>r</i> bytes to the channel, 148 * where <i>r</i> is the number of bytes remaining in the buffer, that is, 149 * {@code src.remaining()} at the time that the write is attempted. Where 150 * <i>r</i> is 0, the write operation completes immediately with a result of 151 * {@code 0} without initiating an I/O operation. 152 * 153 * <p> Suppose that a byte sequence of length <i>n</i> is written, where 154 * <tt>0</tt> <tt><</tt> <i>n</i> <tt><=</tt> <i>r</i>. 155 * This byte sequence will be transferred from the buffer starting at index 156 * <i>p</i>, where <i>p</i> is the buffer's position at the moment the 157 * write is performed; the index of the last byte written will be 158 * <i>p</i> <tt>+</tt> <i>n</i> <tt>-</tt> <tt>1</tt>. 159 * Upon completion the buffer's position will be equal to 160 * <i>p</i> <tt>+</tt> <i>n</i>; its limit will not have changed. 161 * 162 * <p> Buffers are not safe for use by multiple concurrent threads so care 163 * should be taken to not access the buffer until the operation has 164 * completed. 165 * 166 * <p> This method may be invoked at any time. Some channel types may not 167 * allow more than one write to be outstanding at any given time. If a thread 168 * initiates a write operation before a previous write operation has 169 * completed then a {@link WritePendingException} will be thrown. 170 * 171 * @param <A> 172 * The type of the attachment 173 * @param src 174 * The buffer from which bytes are to be retrieved 175 * @param attachment 176 * The object to attach to the I/O operation; can be {@code null} 177 * @param handler 178 * The completion handler object 179 * 180 * @throws WritePendingException 181 * If the channel does not allow more than one write to be outstanding 182 * and a previous write has not completed 183 * @throws ShutdownChannelGroupException 184 * If the channel is associated with a {@link AsynchronousChannelGroup 185 * group} that has terminated 186 */ write(ByteBuffer src, A attachment, CompletionHandler<Integer,? super A> handler)187 <A> void write(ByteBuffer src, 188 A attachment, 189 CompletionHandler<Integer,? super A> handler); 190 191 /** 192 * Writes a sequence of bytes to this channel from the given buffer. 193 * 194 * <p> This method initiates an asynchronous write operation to write a 195 * sequence of bytes to this channel from the given buffer. The method 196 * behaves in exactly the same manner as the {@link 197 * #write(ByteBuffer,Object,CompletionHandler) 198 * write(ByteBuffer,Object,CompletionHandler)} method except that instead 199 * of specifying a completion handler, this method returns a {@code Future} 200 * representing the pending result. The {@code Future}'s {@link Future#get() 201 * get} method returns the number of bytes written. 202 * 203 * @param src 204 * The buffer from which bytes are to be retrieved 205 * 206 * @return A Future representing the result of the operation 207 * 208 * @throws WritePendingException 209 * If the channel does not allow more than one write to be outstanding 210 * and a previous write has not completed 211 */ write(ByteBuffer src)212 Future<Integer> write(ByteBuffer src); 213 } 214