init

java/org/apache/tomcat/websocket/Transformation.java

@@ -0,0 +1,114 @@
+/*
+ *  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 javax.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 any 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();
+}