View Javadoc
1   /*
2    * Copyright 2013 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. 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, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  package io.netty.handler.codec.http.websocketx;
17  
18  import io.netty.channel.ChannelHandlerContext;
19  import io.netty.channel.ChannelInboundHandler;
20  import io.netty.channel.ChannelPipeline;
21  import io.netty.handler.codec.http.HttpHeaders;
22  
23  import java.net.URI;
24  import java.util.List;
25  
26  /**
27   * This handler does all the heavy lifting for you to run a websocket client.
28   *
29   * It takes care of websocket handshaking as well as processing of Ping, Pong frames. Text and Binary
30   * data frames are passed to the next handler in the pipeline (implemented by you) for processing.
31   * Also the close frame is passed to the next handler as you may want inspect it before close the connection if
32   * the {@code handleCloseFrames} is {@code false}, default is {@code true}.
33   *
34   * This implementation will establish the websocket connection once the connection to the remote server was complete.
35   *
36   * To know once a handshake was done you can intercept the
37   * {@link ChannelInboundHandler#userEventTriggered(ChannelHandlerContext, Object)} and check if the event was of type
38   * {@link ClientHandshakeStateEvent#HANDSHAKE_ISSUED} or {@link ClientHandshakeStateEvent#HANDSHAKE_COMPLETE}.
39   */
40  public class WebSocketClientProtocolHandler extends WebSocketProtocolHandler {
41  
42      private final WebSocketClientHandshaker handshaker;
43      private final boolean handleCloseFrames;
44  
45      /**
46       * Returns the used handshaker
47       */
48      public WebSocketClientHandshaker handshaker() { return handshaker; }
49  
50      /**
51       * Events that are fired to notify about handshake status
52       */
53      public enum ClientHandshakeStateEvent {
54          /**
55           * The Handshake was started but the server did not response yet to the request
56           */
57          HANDSHAKE_ISSUED,
58  
59          /**
60           * The Handshake was complete succesful and so the channel was upgraded to websockets
61           */
62          HANDSHAKE_COMPLETE
63      }
64  
65      /**
66       * Base constructor
67       *
68       * @param webSocketURL
69       *            URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be
70       *            sent to this URL.
71       * @param version
72       *            Version of web socket specification to use to connect to the server
73       * @param subprotocol
74       *            Sub protocol request sent to the server.
75       * @param customHeaders
76       *            Map of custom headers to add to the client request
77       * @param maxFramePayloadLength
78       *            Maximum length of a frame's payload
79       * @param handleCloseFrames
80       *            {@code true} if close frames should not be forwarded and just close the channel
81       */
82      public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol,
83                                                     boolean allowExtensions, HttpHeaders customHeaders,
84                                                     int maxFramePayloadLength, boolean handleCloseFrames) {
85          this(WebSocketClientHandshakerFactory.newHandshaker(webSocketURL, version, subprotocol,
86                  allowExtensions, customHeaders, maxFramePayloadLength), handleCloseFrames);
87      }
88  
89      /**
90       * Base constructor
91       *
92       * @param webSocketURL
93       *            URL for web socket communications. e.g "ws://myhost.com/mypath". Subsequent web socket frames will be
94       *            sent to this URL.
95       * @param version
96       *            Version of web socket specification to use to connect to the server
97       * @param subprotocol
98       *            Sub protocol request sent to the server.
99       * @param customHeaders
100      *            Map of custom headers to add to the client request
101      * @param maxFramePayloadLength
102      *            Maximum length of a frame's payload
103      */
104     public WebSocketClientProtocolHandler(URI webSocketURL, WebSocketVersion version, String subprotocol,
105                                           boolean allowExtensions, HttpHeaders customHeaders,
106                                           int maxFramePayloadLength) {
107         this(webSocketURL, version, subprotocol,
108                 allowExtensions, customHeaders, maxFramePayloadLength, true);
109     }
110 
111     /**
112      * Base constructor
113      *
114      * @param handshaker
115      *            The {@link WebSocketClientHandshaker} which will be used to issue the handshake once the connection
116      *            was established to the remote peer.
117      * @param handleCloseFrames
118      *            {@code true} if close frames should not be forwarded and just close the channel
119      */
120     public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker, boolean handleCloseFrames) {
121         this.handshaker = handshaker;
122         this.handleCloseFrames = handleCloseFrames;
123     }
124 
125     /**
126      * Base constructor
127      *
128      * @param handshaker
129      *            The {@link WebSocketClientHandshaker} which will be used to issue the handshake once the connection
130      *            was established to the remote peer.
131      */
132     public WebSocketClientProtocolHandler(WebSocketClientHandshaker handshaker) {
133         this(handshaker, true);
134     }
135 
136     @Override
137     protected void decode(ChannelHandlerContext ctx, WebSocketFrame frame, List<Object> out) throws Exception {
138         if (handleCloseFrames && frame instanceof CloseWebSocketFrame) {
139             ctx.close();
140             return;
141         }
142         super.decode(ctx, frame, out);
143     }
144 
145     @Override
146     public void handlerAdded(ChannelHandlerContext ctx) {
147         ChannelPipeline cp = ctx.pipeline();
148         if (cp.get(WebSocketClientProtocolHandshakeHandler.class) == null) {
149             // Add the WebSocketClientProtocolHandshakeHandler before this one.
150             ctx.pipeline().addBefore(ctx.name(), WebSocketClientProtocolHandshakeHandler.class.getName(),
151                     new WebSocketClientProtocolHandshakeHandler(handshaker));
152         }
153     }
154 }