1 // 2 // ======================================================================== 3 // Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd. 4 // ------------------------------------------------------------------------ 5 // All rights reserved. This program and the accompanying materials 6 // are made available under the terms of the Eclipse Public License v1.0 7 // and Apache License v2.0 which accompanies this distribution. 8 // 9 // The Eclipse Public License is available at 10 // http://www.eclipse.org/legal/epl-v10.html 11 // 12 // The Apache License v2.0 is available at 13 // http://www.opensource.org/licenses/apache2.0.php 14 // 15 // You may elect to redistribute this code under either of these licenses. 16 // ======================================================================== 17 // 18 19 package org.eclipse.jetty.io; 20 21 import java.io.Closeable; 22 import java.io.IOException; 23 import java.net.InetSocketAddress; 24 import java.nio.ByteBuffer; 25 import java.nio.channels.ReadPendingException; 26 import java.nio.channels.WritePendingException; 27 28 import org.eclipse.jetty.util.Callback; 29 30 /** 31 * 32 * A transport EndPoint 33 * 34 * <h3>Asynchronous Methods</h3> 35 * <p>The asynchronous scheduling methods of {@link EndPoint} 36 * has been influenced by NIO.2 Futures and Completion 37 * handlers, but does not use those actual interfaces because they have 38 * some inefficiencies.</p> 39 * <p>This class will frequently be used in conjunction with some of the utility 40 * implementations of {@link Callback}, such as {@link FutureCallback} and 41 * {@link ExecutorCallback}. Examples are:</p> 42 * 43 * <h3>Blocking Read</h3> 44 * <p>A FutureCallback can be used to block until an endpoint is ready to be filled 45 * from: 46 * <blockquote><pre> 47 * FutureCallback<String> future = new FutureCallback<>(); 48 * endpoint.fillInterested("ContextObj",future); 49 * ... 50 * String context = future.get(); // This blocks 51 * int filled=endpoint.fill(mybuffer); 52 * </pre></blockquote></p> 53 * 54 * <h3>Dispatched Read</h3> 55 * <p>By using a different callback, the read can be done asynchronously in its own dispatched thread: 56 * <blockquote><pre> 57 * endpoint.fillInterested("ContextObj",new ExecutorCallback<String>(executor) 58 * { 59 * public void onCompleted(String context) 60 * { 61 * int filled=endpoint.fill(mybuffer); 62 * ... 63 * } 64 * public void onFailed(String context,Throwable cause) {...} 65 * }); 66 * </pre></blockquote></p> 67 * <p>The executor callback can also be customized to not dispatch in some circumstances when 68 * it knows it can use the callback thread and does not need to dispatch.</p> 69 * 70 * <h3>Blocking Write</h3> 71 * <p>The write contract is that the callback complete is not called until all data has been 72 * written or there is a failure. For blocking this looks like: 73 * <blockquote><pre> 74 * FutureCallback<String> future = new FutureCallback<>(); 75 * endpoint.write("ContextObj",future,headerBuffer,contentBuffer); 76 * String context = future.get(); // This blocks 77 * </pre></blockquote></p> 78 * 79 * <h3>Dispatched Write</h3> 80 * <p>Note also that multiple buffers may be passed in write so that gather writes 81 * can be done: 82 * <blockquote><pre> 83 * endpoint.write("ContextObj",new ExecutorCallback<String>(executor) 84 * { 85 * public void onCompleted(String context) 86 * { 87 * int filled=endpoint.fill(mybuffer); 88 * ... 89 * } 90 * public void onFailed(String context,Throwable cause) {...} 91 * },headerBuffer,contentBuffer); 92 * </pre></blockquote></p> 93 */ 94 public interface EndPoint extends Closeable 95 { 96 /* ------------------------------------------------------------ */ 97 /** 98 * @return The local Inet address to which this <code>EndPoint</code> is bound, or <code>null</code> 99 * if this <code>EndPoint</code> does not represent a network connection. 100 */ 101 InetSocketAddress getLocalAddress(); 102 103 /* ------------------------------------------------------------ */ 104 /** 105 * @return The remote Inet address to which this <code>EndPoint</code> is bound, or <code>null</code> 106 * if this <code>EndPoint</code> does not represent a network connection. 107 */ 108 InetSocketAddress getRemoteAddress(); 109 110 /* ------------------------------------------------------------ */ 111 boolean isOpen(); 112 113 /* ------------------------------------------------------------ */ 114 long getCreatedTimeStamp(); 115 116 /* ------------------------------------------------------------ */ 117 /** Shutdown the output. 118 * <p>This call indicates that no more data will be sent on this endpoint that 119 * that the remote end should read an EOF once all previously sent data has been 120 * consumed. Shutdown may be done either at the TCP/IP level, as a protocol exchange (Eg 121 * TLS close handshake) or both. 122 * <p> 123 * If the endpoint has {@link #isInputShutdown()} true, then this call has the same effect 124 * as {@link #close()}. 125 */ 126 void shutdownOutput(); 127 128 /* ------------------------------------------------------------ */ 129 /** Test if output is shutdown. 130 * The output is shutdown by a call to {@link #shutdownOutput()} 131 * or {@link #close()}. 132 * @return true if the output is shutdown or the endpoint is closed. 133 */ 134 boolean isOutputShutdown(); 135 136 /* ------------------------------------------------------------ */ 137 /** Test if the input is shutdown. 138 * The input is shutdown if an EOF has been read while doing 139 * a {@link #fill(ByteBuffer)}. Once the input is shutdown, all calls to 140 * {@link #fill(ByteBuffer)} will return -1, until such time as the 141 * end point is close, when they will return {@link EofException}. 142 * @return True if the input is shutdown or the endpoint is closed. 143 */ 144 boolean isInputShutdown(); 145 146 /** 147 * Close any backing stream associated with the endpoint 148 */ 149 @Override 150 void close(); 151 152 /** 153 * Fill the passed buffer with data from this endpoint. The bytes are appended to any 154 * data already in the buffer by writing from the buffers limit up to it's capacity. 155 * The limit is updated to include the filled bytes. 156 * 157 * @param buffer The buffer to fill. The position and limit are modified during the fill. After the 158 * operation, the position is unchanged and the limit is increased to reflect the new data filled. 159 * @return an <code>int</code> value indicating the number of bytes 160 * filled or -1 if EOF is read or the input is shutdown. 161 * @throws EofException If the endpoint is closed. 162 */ 163 int fill(ByteBuffer buffer) throws IOException; 164 165 166 /** 167 * Flush data from the passed header/buffer to this endpoint. As many bytes as can be consumed 168 * are taken from the header/buffer position up until the buffer limit. The header/buffers position 169 * is updated to indicate how many bytes have been consumed. 170 * @return True IFF all the buffers have been consumed and the endpoint has flushed the data to its 171 * destination (ie is not buffering any data). 172 * 173 * @throws EofException If the endpoint is closed or output is shutdown. 174 */ 175 boolean flush(ByteBuffer... buffer) throws IOException; 176 177 /* ------------------------------------------------------------ */ 178 /** 179 * @return The underlying transport object (socket, channel, etc.) 180 */ 181 Object getTransport(); 182 183 /* ------------------------------------------------------------ */ 184 /** Get the max idle time in ms. 185 * <p>The max idle time is the time the endpoint can be idle before 186 * extraordinary handling takes place. 187 * @return the max idle time in ms or if ms <= 0 implies an infinite timeout 188 */ 189 long getIdleTimeout(); 190 191 /* ------------------------------------------------------------ */ 192 /** Set the idle timeout. 193 * @param idleTimeout the idle timeout in MS. Timeout <= 0 implies an infinite timeout 194 */ 195 void setIdleTimeout(long idleTimeout); 196 197 198 /** 199 * <p>Requests callback methods to be invoked when a call to {@link #fill(ByteBuffer)} would return data or EOF.</p> 200 * 201 * @param callback the callback to call when an error occurs or we are readable. 202 * @throws ReadPendingException if another read operation is concurrent. 203 */ 204 void fillInterested(Callback callback) throws ReadPendingException; 205 206 /** 207 * <p>Writes the given buffers via {@link #flush(ByteBuffer...)} and invokes callback methods when either 208 * all the data has been flushed or an error occurs.</p> 209 * 210 * @param callback the callback to call when an error occurs or the write completed. 211 * @param buffers one or more {@link ByteBuffer}s that will be flushed. 212 * @throws WritePendingException if another write operation is concurrent. 213 */ 214 void write(Callback callback, ByteBuffer... buffers) throws WritePendingException; 215 216 /** 217 * @return the {@link Connection} associated with this {@link EndPoint} 218 * @see #setConnection(Connection) 219 */ 220 Connection getConnection(); 221 222 /** 223 * @param connection the {@link Connection} associated with this {@link EndPoint} 224 * @see #getConnection() 225 */ 226 void setConnection(Connection connection); 227 228 /** 229 * <p>Callback method invoked when this {@link EndPoint} is opened.</p> 230 * @see #onClose() 231 */ 232 void onOpen(); 233 234 /** 235 * <p>Callback method invoked when this {@link EndPoint} is close.</p> 236 * @see #onOpen() 237 */ 238 void onClose(); 239 240 241 }