1 //
2 // ========================================================================
3 // Copyright (c) 1995-2013 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 work is performed by the two {@link FrameHandler} implementations for incoming and outgoing frame handling.
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 * Used to indicate that the extension works as a decoder of TEXT Data Frames.
71 * <p>
72 * This is used to adjust validation during parsing/generating, as per spec TEXT Data Frames can only contain UTF8 encoded String data.
73 * <p>
74 * Example: a compression extension will process a compressed set of text data, the parser/generator should no longer be concerned about the validity of the
75 * TEXT Data Frames as this is now the responsibility of the extension.
76 *
77 * @return true if extension will process TEXT Data Frames, false if extension makes no modifications of TEXT Data Frames. If false, the parser/generator is
78 * now free to validate the conformance to spec of TEXT Data Frames.
79 */
80 public abstract boolean isTextDataDecoder();
81
82 /**
83 * Set the next {@link IncomingFrames} to call in the chain.
84 *
85 * @param nextIncoming
86 * the next incoming extension
87 */
88 public void setNextIncomingFrames(IncomingFrames nextIncoming);
89
90 /**
91 * Set the next {@link OutgoingFrames} to call in the chain.
92 *
93 * @param nextOutgoing
94 * the next outgoing extension
95 */
96 public void setNextOutgoingFrames(OutgoingFrames nextOutgoing);
97 }