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