1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 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.spdy.api;
20
21 import java.util.EventListener;
22
23 import org.eclipse.jetty.util.log.Log;
24 import org.eclipse.jetty.util.log.Logger;
25
26 /**
27 * <p>A {@link SessionFrameListener} is the passive counterpart of a {@link Session} and receives events happening
28 * on a SPDY session.</p>
29 *
30 * @see Session
31 */
32 public interface SessionFrameListener extends EventListener
33 {
34 /**
35 * <p>Callback invoked when a request to create a stream has been received.</p>
36 * <p>Application code should implement this method and reply to the stream creation, eventually
37 * sending data:</p>
38 * <pre>
39 * public Stream.FrameListener onSyn(Stream stream, SynInfo synInfo)
40 * {
41 * // Do something with the metadata contained in synInfo
42 *
43 * if (stream.isHalfClosed()) // The other peer will not send data
44 * {
45 * stream.reply(new ReplyInfo(false));
46 * stream.data(new StringDataInfo("foo", true));
47 * return null; // Not interested in further stream events
48 * }
49 *
50 * ...
51 * }
52 * </pre>
53 * <p>Alternatively, if the stream creation requires reading data sent from the other peer:</p>
54 * <pre>
55 * public Stream.FrameListener onSyn(Stream stream, SynInfo synInfo)
56 * {
57 * // Do something with the metadata contained in synInfo
58 *
59 * if (!stream.isHalfClosed()) // The other peer will send data
60 * {
61 * stream.reply(new ReplyInfo(true));
62 * return new Stream.FrameListener.Adapter() // Interested in stream events
63 * {
64 * public void onData(Stream stream, DataInfo dataInfo)
65 * {
66 * // Do something with the incoming data in dataInfo
67 * }
68 * };
69 * }
70 *
71 * ...
72 * }
73 * </pre>
74 *
75 * @param stream the stream just created
76 * @param synInfo the metadata sent on stream creation
77 * @return a listener for stream events, or null if there is no interest in being notified of stream events
78 */
79 public StreamFrameListener onSyn(Stream stream, SynInfo synInfo);
80
81 /**
82 * <p>Callback invoked when a stream error happens.</p>
83 *
84 * @param session the session
85 * @param rstInfo the metadata of the stream error
86 */
87 public void onRst(Session session, RstInfo rstInfo);
88
89 /**
90 * <p>Callback invoked when a request to configure the SPDY connection has been received.</p>
91 *
92 * @param session the session
93 * @param settingsInfo the metadata sent to configure
94 */
95 public void onSettings(Session session, SettingsInfo settingsInfo);
96
97 /**
98 * <p>Callback invoked when a ping request has completed its round-trip.</p>
99 *
100 * @param session the session
101 * @param pingInfo the metadata received
102 */
103 public void onPing(Session session, PingInfo pingInfo);
104
105 /**
106 * <p>Callback invoked when the other peer signals that it is closing the connection.</p>
107 *
108 * @param session the session
109 * @param goAwayInfo the metadata sent
110 */
111 public void onGoAway(Session session, GoAwayInfo goAwayInfo);
112
113 /**
114 * <p>Callback invoked when an exception is thrown during the processing of an event on a
115 * SPDY session.</p>
116 * <p>Examples of such conditions are invalid frames received, corrupted headers compression state, etc.</p>
117 *
118 * @param x the exception that caused the event processing failure
119 */
120 public void onException(Throwable x);
121
122 /**
123 * <p>Empty implementation of {@link SessionFrameListener}</p>
124 */
125 public static class Adapter implements SessionFrameListener
126 {
127 private static final Logger logger = Log.getLogger(Adapter.class);
128
129 @Override
130 public StreamFrameListener onSyn(Stream stream, SynInfo synInfo)
131 {
132 return null;
133 }
134
135 @Override
136 public void onRst(Session session, RstInfo rstInfo)
137 {
138 }
139
140 @Override
141 public void onSettings(Session session, SettingsInfo settingsInfo)
142 {
143 }
144
145 @Override
146 public void onPing(Session session, PingInfo pingInfo)
147 {
148 }
149
150 @Override
151 public void onGoAway(Session session, GoAwayInfo goAwayInfo)
152 {
153 }
154
155 @Override
156 public void onException(Throwable x)
157 {
158 logger.info("", x);
159 }
160 }
161 }