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 WS sub-protocol that this transport is supplying.
060     */
061    String getSubProtocol();
062
063    /**
064     * Called to provide the WS with the output data sink.
065     */
066    void setTransportSink(WSTransportSink outputSink);
067
068    /**
069     * Called from the WebSocket framework when new incoming String data is received.
070     *
071     * @param data
072     *      The newly received incoming data.
073     *
074     * @throws IOException if an error occurs or the socket doesn't support text data.
075     */
076    void onWebSocketText(String data) throws IOException;
077
078    /**
079     * Called from the WebSocket framework when new incoming Binary data is received.
080     *
081     * @param data
082     *      The newly received incoming data.
083     *
084     * @throws IOException if an error occurs or the socket doesn't support binary data.
085     */
086    void onWebSocketBinary(ByteBuffer data) throws IOException;
087
088    /**
089     * Called from the WebSocket framework when the socket has been closed unexpectedly.
090     *
091     * @throws IOException if an error while processing the close.
092     */
093    void onWebSocketClosed() throws IOException;
094
095}