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.IOException;
22 
23 /* ------------------------------------------------------------ */
24 /** Abstract Connection used by Jetty Connectors.
25  * <p>
26  * Jetty will call the handle method of a connection when there is work
27  * to be done on the connection.  For blocking connections, this is soon
28  * as the connection is open and handle will keep being called until the
29  * connection is closed.   For non-blocking connections, handle will only
30  * be called if there are bytes to be read or the connection becomes writable
31  * after being write blocked.
32  *
33  * @see org.eclipse.jetty.io.nio.SelectorManager
34  */
35 public interface Connection
36 {
37     /* ------------------------------------------------------------ */
38     /**
39      * Handle the connection.
40      * @return The Connection to use for the next handling of the connection.
41      * This allows protocol upgrades and support for CONNECT.
42      * @throws IOException if the handling of I/O operations fail
43      */
handle()44     Connection handle() throws IOException;
45 
46     /**
47      * @return the timestamp at which the connection was created
48      */
getTimeStamp()49     long getTimeStamp();
50 
51     /**
52      * @return whether this connection is idle, that is not parsing and not generating
53      * @see #onIdleExpired(long)
54      */
isIdle()55     boolean isIdle();
56 
57     /**
58      * <p>The semantic of this method is to return true to indicate interest in further reads,
59      * or false otherwise, but it is misnamed and should be really called <code>isReadInterested()</code>.</p>
60      *
61      * @return true to indicate interest in further reads, false otherwise
62      */
63     // TODO: rename to isReadInterested() in the next release
isSuspended()64     boolean isSuspended();
65 
66     /**
67      * Called after the connection is closed
68      */
onClose()69     void onClose();
70 
71     /**
72      * Called when the connection idle timeout expires
73      * @param idleForMs how long the connection has been idle
74      * @see #isIdle()
75      */
onIdleExpired(long idleForMs)76     void onIdleExpired(long idleForMs);
77 }
78