2 // ========================================================================
3 // Copyright (c) 1995-2016 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.
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
19 package org.eclipse.jetty.io;
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;
28 import org.eclipse.jetty.util.Callback;
32 * A transport EndPoint
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>
43 * <h3>Blocking Read</h3>
44 * <p>A FutureCallback can be used to block until an endpoint is ready to be filled
47 * FutureCallback<String> future = new FutureCallback<>();
48 * endpoint.fillInterested("ContextObj",future);
50 * String context = future.get(); // This blocks
51 * int filled=endpoint.fill(mybuffer);
52 * </pre></blockquote></p>
54 * <h3>Dispatched Read</h3>
55 * <p>By using a different callback, the read can be done asynchronously in its own dispatched thread:
57 * endpoint.fillInterested("ContextObj",new ExecutorCallback<String>(executor)
59 * public void onCompleted(String context)
61 * int filled=endpoint.fill(mybuffer);
64 * public void onFailed(String context,Throwable cause) {...}
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>
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:
74 * FutureCallback<String> future = new FutureCallback<>();
75 * endpoint.write("ContextObj",future,headerBuffer,contentBuffer);
76 * String context = future.get(); // This blocks
77 * </pre></blockquote></p>
79 * <h3>Dispatched Write</h3>
80 * <p>Note also that multiple buffers may be passed in write so that gather writes
83 * endpoint.write("ContextObj",new ExecutorCallback<String>(executor)
85 * public void onCompleted(String context)
87 * int filled=endpoint.fill(mybuffer);
90 * public void onFailed(String context,Throwable cause) {...}
91 * },headerBuffer,contentBuffer);
92 * </pre></blockquote></p>
94 public interface EndPoint extends Closeable
96 /* ------------------------------------------------------------ */
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.
101 InetSocketAddress getLocalAddress();
103 /* ------------------------------------------------------------ */
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.
108 InetSocketAddress getRemoteAddress();
110 /* ------------------------------------------------------------ */
113 /* ------------------------------------------------------------ */
114 long getCreatedTimeStamp();
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.
123 * If the endpoint has {@link #isInputShutdown()} true, then this call has the same effect
124 * as {@link #close()}.
126 void shutdownOutput();
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.
134 boolean isOutputShutdown();
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.
144 boolean isInputShutdown();
147 * Close any backing stream associated with the endpoint
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.
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.
163 int fill(ByteBuffer buffer) throws IOException;
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).
173 * @throws EofException If the endpoint is closed or output is shutdown.
175 boolean flush(ByteBuffer... buffer) throws IOException;
177 /* ------------------------------------------------------------ */
179 * @return The underlying transport object (socket, channel, etc.)
181 Object getTransport();
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
189 long getIdleTimeout();
191 /* ------------------------------------------------------------ */
192 /** Set the idle timeout.
193 * @param idleTimeout the idle timeout in MS. Timeout <= 0 implies an infinite timeout
195 void setIdleTimeout(long idleTimeout);
199 * <p>Requests callback methods to be invoked when a call to {@link #fill(ByteBuffer)} would return data or EOF.</p>
201 * @param callback the callback to call when an error occurs or we are readable.
202 * @throws ReadPendingException if another read operation is concurrent.
204 void fillInterested(Callback callback) throws ReadPendingException;
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>
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.
214 void write(Callback callback, ByteBuffer... buffers) throws WritePendingException;
217 * @return the {@link Connection} associated with this {@link EndPoint}
218 * @see #setConnection(Connection)
220 Connection getConnection();
223 * @param connection the {@link Connection} associated with this {@link EndPoint}
224 * @see #getConnection()
225 * @see #upgrade(Connection)
227 void setConnection(Connection connection);
230 * <p>Callback method invoked when this {@link EndPoint} is opened.</p>
236 * <p>Callback method invoked when this {@link EndPoint} is close.</p>
242 /** Upgrade connections.
243 * Close the old connection, update the endpoint and open the new connection.
244 * If the oldConnection is an instance of {@link Connection.UpgradeFrom} then
245 * a prefilled buffer is requested and passed to the newConnection if it is an instance
246 * of {@link Connection.UpgradeTo}
247 * @param newConnection The connection to upgrade to
249 public void upgrade(Connection newConnection);