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.websocket.api.extensions;
20  
21  /**
22   * Interface for WebSocket Extensions.
23   * <p>
24   * That {@link Frame}s are passed through the Extension via the {@link IncomingFrames} and {@link OutgoingFrames} interfaces
25   */
26  public interface Extension extends IncomingFrames, OutgoingFrames
27  {
28      /**
29       * The active configuration for this extension.
30       * 
31       * @return the configuration for this extension. never null.
32       */
33      public ExtensionConfig getConfig();
34  
35      /**
36       * The <code>Sec-WebSocket-Extensions</code> name for this extension.
37       * <p>
38       * Also known as the <a href="https://tools.ietf.org/html/rfc6455#section-9.1"><code>extension-token</code> per Section 9.1. Negotiating Extensions</a>.
39       */
40      public String getName();
41  
42      /**
43       * Used to indicate that the extension makes use of the RSV1 bit of the base websocket framing.
44       * <p>
45       * This is used to adjust validation during parsing, as well as a checkpoint against 2 or more extensions all simultaneously claiming ownership of RSV1.
46       * 
47       * @return true if extension uses RSV1 for its own purposes.
48       */
49      public abstract boolean isRsv1User();
50  
51      /**
52       * Used to indicate that the extension makes use of the RSV2 bit of the base websocket framing.
53       * <p>
54       * This is used to adjust validation during parsing, as well as a checkpoint against 2 or more extensions all simultaneously claiming ownership of RSV2.
55       * 
56       * @return true if extension uses RSV2 for its own purposes.
57       */
58      public abstract boolean isRsv2User();
59  
60      /**
61       * Used to indicate that the extension makes use of the RSV3 bit of the base websocket framing.
62       * <p>
63       * This is used to adjust validation during parsing, as well as a checkpoint against 2 or more extensions all simultaneously claiming ownership of RSV3.
64       * 
65       * @return true if extension uses RSV3 for its own purposes.
66       */
67      public abstract boolean isRsv3User();
68  
69      /**
70       * Set the next {@link IncomingFrames} to call in the chain.
71       * 
72       * @param nextIncoming
73       *            the next incoming extension
74       */
75      public void setNextIncomingFrames(IncomingFrames nextIncoming);
76  
77      /**
78       * Set the next {@link OutgoingFrames} to call in the chain.
79       * 
80       * @param nextOutgoing
81       *            the next outgoing extension
82       */
83      public void setNextOutgoingFrames(OutgoingFrames nextOutgoing);
84      
85      // TODO: Extension should indicate if it requires boundary of fragments to be preserved
86      
87      // TODO: Extension should indicate if it uses the Extension data field of frame for its own reasons.
88      
89  }