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