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