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 }