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