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