/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.tomcat.websocket;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.util.List;
import jakarta.websocket.Extension;
/**
* The internal representation of the transformation that a WebSocket extension performs on a message.
*/
public interface Transformation {
/**
* Sets the next transformation in the pipeline.
*
* @param t The next transformation
*/
void setNext(Transformation t);
/**
* Validate that the RSV bit(s) required by this transformation are not being used by another extension. The
* implementation is expected to set any bits it requires before passing the set of in-use bits to the next
* transformation.
*
* @param i The RSV bits marked as in use so far as an int in the range zero to seven with RSV1 as the MSB and RSV3
* as the LSB
*
* @return <code>true</code> if the combination of RSV bits used by the transformations in the pipeline do not
* conflict otherwise <code>false</code>
*/
boolean validateRsvBits(int i);
/**
* Obtain the extension that describes the information to be returned to the client.
*
* @return The extension information that describes the parameters that have been agreed for this transformation
*/
Extension getExtensionResponse();
/**
* Obtain more input data.
*
* @param opCode The opcode for the frame currently being processed
* @param fin Is this the final frame in this WebSocket message?
* @param rsv The reserved bits for the frame currently being processed
* @param dest The buffer in which the data is to be written
*
* @return The result of trying to read more data from the transform
*
* @throws IOException If an I/O error occurs while reading data from the transform
*/
TransformationResult getMoreData(byte opCode, boolean fin, int rsv, ByteBuffer dest) throws IOException;
/**
* Validates the RSV and opcode combination (assumed to have been extracted from a WebSocket Frame) for this
* extension. The implementation is expected to unset any RSV bits it has validated before passing the remaining RSV
* bits to the next transformation in the pipeline.
*
* @param rsv The RSV bits received as an int in the range zero to seven with RSV1 as the MSB and RSV3 as the LSB
* @param opCode The opCode received
*
* @return <code>true</code> if the RSV is valid otherwise <code>false</code>
*/
boolean validateRsv(int rsv, byte opCode);
/**
* Takes the provided list of messages, transforms them, passes the transformed list on to the next transformation
* (if any) and then returns the resulting list of message parts after all of the transformations have been applied.
*
* @param messageParts The list of messages to be transformed
*
* @return The list of messages after this and any subsequent transformations have been applied. The size of the
* returned list may be bigger or smaller than the size of the input list
*
* @throws IOException If an error occurs during the transformation of the message parts
*/
List<MessagePart> sendMessagePart(List<MessagePart> messageParts) throws IOException;
/**
* Clean-up any resources that were used by the transformation.
*/
void close();
}