1 //
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.
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.nio.ByteBuffer;
23
24 /**
25 * <p>A {@link Connection} is associated to an {@link EndPoint} so that I/O events
26 * happening on the {@link EndPoint} can be processed by the {@link Connection}.</p>
27 * <p>A typical implementation of {@link Connection} overrides {@link #onOpen(ByteBuffer)} to
28 * {@link EndPoint#fillInterested(Callback) set read interest} on the {@link EndPoint},
29 * and when the {@link EndPoint} signals read readyness, this {@link Connection} can
30 * read bytes from the network and interpret them.</p>
31 */
32 public interface Connection extends Closeable
33 {
34 public void addListener(Listener listener);
35
36 public void onOpen();
37
38 /**
39 * <p>Callback method invoked when this {@link Connection} is closed.</p>
40 * <p>Creators of the connection implementation are responsible for calling this method.</p>
41 */
42 public void onClose();
43
44 /**
45 * @return the {@link EndPoint} associated with this {@link Connection}
46 */
47 public EndPoint getEndPoint();
48
49 /**
50 * <p>Performs a logical close of this connection.</p>
51 * <p>For simple connections, this may just mean to delegate the close to the associated
52 * {@link EndPoint} but, for example, SSL connections should write the SSL close message
53 * before closing the associated {@link EndPoint}.</p>
54 */
55 @Override
56 public void close();
57
58 public int getMessagesIn();
59 public int getMessagesOut();
60 public long getBytesIn();
61 public long getBytesOut();
62 public long getCreatedTimeStamp();
63
64 public interface UpgradeFrom extends Connection
65 {
66 /* ------------------------------------------------------------ */
67 /** Take the input buffer from the connection on upgrade.
68 * <p>This method is used to take any unconsumed input from
69 * a connection during an upgrade.
70 * @return A buffer of unconsumed input. The caller must return the buffer
71 * to the bufferpool when consumed and this connection must not.
72 */
73 ByteBuffer onUpgradeFrom();
74 }
75
76 public interface UpgradeTo extends Connection
77 {
78 /**
79 * <p>Callback method invoked when this {@link Connection} is upgraded.</p>
80 * <p>This must be called before {@link #onOpen()}.</p>
81 * @param prefilledBuffer An optional buffer that can contain prefilled data. Typically this
82 * results from an upgrade of one protocol to the other where the old connection has buffered
83 * data destined for the new connection. The new connection must take ownership of the buffer
84 * and is responsible for returning it to the buffer pool
85 */
86 void onUpgradeTo(ByteBuffer prefilled);
87 }
88
89 public interface Listener
90 {
91 public void onOpened(Connection connection);
92
93 public void onClosed(Connection connection);
94
95 public static class Adapter implements Listener
96 {
97 @Override
98 public void onOpened(Connection connection)
99 {
100 }
101
102 @Override
103 public void onClosed(Connection connection)
104 {
105 }
106 }
107 }
108 }