View Javadoc

1   //
2   //  ========================================================================
3   //  Copyright (c) 1995-2014 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 }