001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.activemq.transport.ws;
018
019import java.io.IOException;
020import java.nio.ByteBuffer;
021
022import org.apache.activemq.transport.Transport;
023
024/**
025 * Interface for a WebSocket Transport which provide hooks that a servlet can
026 * use to pass along WebSocket data and events.
027 */
028public interface WSTransport extends Transport {
029
030    /**
031     * WS Transport output sink, used to give the WS Transport implementation
032     * a way to produce output back to the WS connection without coupling it
033     * to the implementation.
034     */
035    public interface WSTransportSink {
036
037        /**
038         * Called from the Transport when new outgoing String data is ready.
039         *
040         * @param data
041         *      The newly prepared outgoing string data.
042         *
043         * @throws IOException if an error occurs or the socket doesn't support text data.
044         */
045        void onSocketOutboundText(String data) throws IOException;
046
047        /**
048         * Called from the Transport when new outgoing String data is ready.
049         *
050         * @param data
051         *      The newly prepared outgoing string data.
052         *
053         * @throws IOException if an error occurs or the socket doesn't support text data.
054         */
055        void onSocketOutboundBinary(ByteBuffer data) throws IOException;
056    }
057
058    /**
059     * @return the maximum frame size allowed for this WS Transport.
060     */
061    int getMaxFrameSize();
062
063    /**
064     * @return the WS sub-protocol that this transport is supplying.
065     */
066    String getSubProtocol();
067
068    /**
069     * Called to provide the WS with the output data sink.
070     */
071    void setTransportSink(WSTransportSink outputSink);
072
073    /**
074     * Called from the WebSocket framework when new incoming String data is received.
075     *
076     * @param data
077     *      The newly received incoming data.
078     *
079     * @throws IOException if an error occurs or the socket doesn't support text data.
080     */
081    void onWebSocketText(String data) throws IOException;
082
083    /**
084     * Called from the WebSocket framework when new incoming Binary data is received.
085     *
086     * @param data
087     *      The newly received incoming data.
088     *
089     * @throws IOException if an error occurs or the socket doesn't support binary data.
090     */
091    void onWebSocketBinary(ByteBuffer data) throws IOException;
092
093    /**
094     * Called from the WebSocket framework when the socket has been closed unexpectedly.
095     *
096     * @throws IOException if an error while processing the close.
097     */
098    void onWebSocketClosed() throws IOException;
099
100}