xref: /unit/src/java/nginx/unit/websocket/Transformation.java (revision 1157:7ae152bda303)
1*1157Smax.romanov@nginx.com /*
2*1157Smax.romanov@nginx.com  *  Licensed to the Apache Software Foundation (ASF) under one or more
3*1157Smax.romanov@nginx.com  *  contributor license agreements.  See the NOTICE file distributed with
4*1157Smax.romanov@nginx.com  *  this work for additional information regarding copyright ownership.
5*1157Smax.romanov@nginx.com  *  The ASF licenses this file to You under the Apache License, Version 2.0
6*1157Smax.romanov@nginx.com  *  (the "License"); you may not use this file except in compliance with
7*1157Smax.romanov@nginx.com  *  the License.  You may obtain a copy of the License at
8*1157Smax.romanov@nginx.com  *
9*1157Smax.romanov@nginx.com  *      http://www.apache.org/licenses/LICENSE-2.0
10*1157Smax.romanov@nginx.com  *
11*1157Smax.romanov@nginx.com  *  Unless required by applicable law or agreed to in writing, software
12*1157Smax.romanov@nginx.com  *  distributed under the License is distributed on an "AS IS" BASIS,
13*1157Smax.romanov@nginx.com  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14*1157Smax.romanov@nginx.com  *  See the License for the specific language governing permissions and
15*1157Smax.romanov@nginx.com  *  limitations under the License.
16*1157Smax.romanov@nginx.com  */
17*1157Smax.romanov@nginx.com package nginx.unit.websocket;
18*1157Smax.romanov@nginx.com 
19*1157Smax.romanov@nginx.com import java.io.IOException;
20*1157Smax.romanov@nginx.com import java.nio.ByteBuffer;
21*1157Smax.romanov@nginx.com import java.util.List;
22*1157Smax.romanov@nginx.com 
23*1157Smax.romanov@nginx.com import javax.websocket.Extension;
24*1157Smax.romanov@nginx.com 
25*1157Smax.romanov@nginx.com /**
26*1157Smax.romanov@nginx.com  * The internal representation of the transformation that a WebSocket extension
27*1157Smax.romanov@nginx.com  * performs on a message.
28*1157Smax.romanov@nginx.com  */
29*1157Smax.romanov@nginx.com public interface Transformation {
30*1157Smax.romanov@nginx.com 
31*1157Smax.romanov@nginx.com     /**
32*1157Smax.romanov@nginx.com      * Sets the next transformation in the pipeline.
33*1157Smax.romanov@nginx.com      * @param t The next transformation
34*1157Smax.romanov@nginx.com      */
setNext(Transformation t)35*1157Smax.romanov@nginx.com     void setNext(Transformation t);
36*1157Smax.romanov@nginx.com 
37*1157Smax.romanov@nginx.com     /**
38*1157Smax.romanov@nginx.com      * Validate that the RSV bit(s) required by this transformation are not
39*1157Smax.romanov@nginx.com      * being used by another extension. The implementation is expected to set
40*1157Smax.romanov@nginx.com      * any bits it requires before passing the set of in-use bits to the next
41*1157Smax.romanov@nginx.com      * transformation.
42*1157Smax.romanov@nginx.com      *
43*1157Smax.romanov@nginx.com      * @param i         The RSV bits marked as in use so far as an int in the
44*1157Smax.romanov@nginx.com      *                  range zero to seven with RSV1 as the MSB and RSV3 as the
45*1157Smax.romanov@nginx.com      *                  LSB
46*1157Smax.romanov@nginx.com      *
47*1157Smax.romanov@nginx.com      * @return <code>true</code> if the combination of RSV bits used by the
48*1157Smax.romanov@nginx.com      *         transformations in the pipeline do not conflict otherwise
49*1157Smax.romanov@nginx.com      *         <code>false</code>
50*1157Smax.romanov@nginx.com      */
validateRsvBits(int i)51*1157Smax.romanov@nginx.com     boolean validateRsvBits(int i);
52*1157Smax.romanov@nginx.com 
53*1157Smax.romanov@nginx.com     /**
54*1157Smax.romanov@nginx.com      * Obtain the extension that describes the information to be returned to the
55*1157Smax.romanov@nginx.com      * client.
56*1157Smax.romanov@nginx.com      *
57*1157Smax.romanov@nginx.com      * @return The extension information that describes the parameters that have
58*1157Smax.romanov@nginx.com      *         been agreed for this transformation
59*1157Smax.romanov@nginx.com      */
getExtensionResponse()60*1157Smax.romanov@nginx.com     Extension getExtensionResponse();
61*1157Smax.romanov@nginx.com 
62*1157Smax.romanov@nginx.com     /**
63*1157Smax.romanov@nginx.com      * Obtain more input data.
64*1157Smax.romanov@nginx.com      *
65*1157Smax.romanov@nginx.com      * @param opCode    The opcode for the frame currently being processed
66*1157Smax.romanov@nginx.com      * @param fin       Is this the final frame in this WebSocket message?
67*1157Smax.romanov@nginx.com      * @param rsv       The reserved bits for the frame currently being
68*1157Smax.romanov@nginx.com      *                      processed
69*1157Smax.romanov@nginx.com      * @param dest      The buffer in which the data is to be written
70*1157Smax.romanov@nginx.com      *
71*1157Smax.romanov@nginx.com      * @return The result of trying to read more data from the transform
72*1157Smax.romanov@nginx.com      *
73*1157Smax.romanov@nginx.com      * @throws IOException If an I/O error occurs while reading data from the
74*1157Smax.romanov@nginx.com      *         transform
75*1157Smax.romanov@nginx.com      */
getMoreData(byte opCode, boolean fin, int rsv, ByteBuffer dest)76*1157Smax.romanov@nginx.com     TransformationResult getMoreData(byte opCode, boolean fin, int rsv, ByteBuffer dest) throws IOException;
77*1157Smax.romanov@nginx.com 
78*1157Smax.romanov@nginx.com     /**
79*1157Smax.romanov@nginx.com      * Validates the RSV and opcode combination (assumed to have been extracted
80*1157Smax.romanov@nginx.com      * from a WebSocket Frame) for this extension. The implementation is
81*1157Smax.romanov@nginx.com      * expected to unset any RSV bits it has validated before passing the
82*1157Smax.romanov@nginx.com      * remaining RSV bits to the next transformation in the pipeline.
83*1157Smax.romanov@nginx.com      *
84*1157Smax.romanov@nginx.com      * @param rsv       The RSV bits received as an int in the range zero to
85*1157Smax.romanov@nginx.com      *                  seven with RSV1 as the MSB and RSV3 as the LSB
86*1157Smax.romanov@nginx.com      * @param opCode    The opCode received
87*1157Smax.romanov@nginx.com      *
88*1157Smax.romanov@nginx.com      * @return <code>true</code> if the RSV is valid otherwise
89*1157Smax.romanov@nginx.com      *         <code>false</code>
90*1157Smax.romanov@nginx.com      */
validateRsv(int rsv, byte opCode)91*1157Smax.romanov@nginx.com     boolean validateRsv(int rsv, byte opCode);
92*1157Smax.romanov@nginx.com 
93*1157Smax.romanov@nginx.com     /**
94*1157Smax.romanov@nginx.com      * Takes the provided list of messages, transforms them, passes the
95*1157Smax.romanov@nginx.com      * transformed list on to the next transformation (if any) and then returns
96*1157Smax.romanov@nginx.com      * the resulting list of message parts after all of the transformations have
97*1157Smax.romanov@nginx.com      * been applied.
98*1157Smax.romanov@nginx.com      *
99*1157Smax.romanov@nginx.com      * @param messageParts  The list of messages to be transformed
100*1157Smax.romanov@nginx.com      *
101*1157Smax.romanov@nginx.com      * @return  The list of messages after this any any subsequent
102*1157Smax.romanov@nginx.com      *          transformations have been applied. The size of the returned list
103*1157Smax.romanov@nginx.com      *          may be bigger or smaller than the size of the input list
104*1157Smax.romanov@nginx.com      */
sendMessagePart(List<MessagePart> messageParts)105*1157Smax.romanov@nginx.com     List<MessagePart> sendMessagePart(List<MessagePart> messageParts);
106*1157Smax.romanov@nginx.com 
107*1157Smax.romanov@nginx.com     /**
108*1157Smax.romanov@nginx.com      * Clean-up any resources that were used by the transformation.
109*1157Smax.romanov@nginx.com      */
close()110*1157Smax.romanov@nginx.com     void close();
111*1157Smax.romanov@nginx.com }
112