io.jsync.http.WebSocketBase Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jsync.io Show documentation
jsync.io is a non-blocking, event-driven networking framework for Java
There is a newer version: 1.10.13
/*
 * Copyright (c) 2011-2013 The original author or authors
 * ------------------------------------------------------
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Apache License v2.0 which accompanies this distribution.
 *
 *     The Eclipse Public License is available at
 *     http://www.eclipse.org/legal/epl-v10.html
 *
 *     The Apache License v2.0 is available at
 *     http://www.opensource.org/licenses/apache2.0.php
 *
 * You may elect to redistribute this code under either of these licenses.
 */

package io.jsync.http;

import io.jsync.Handler;
import io.jsync.buffer.Buffer;
import io.jsync.streams.ReadStream;
import io.jsync.streams.WriteStream;

import java.net.InetSocketAddress;

/**
 * Represents an HTML 5 Websocket
 * Instances of this class are created and provided to the handler of an
 * {@link HttpClient} when a successful websocket connect attempt occurs.

 * On the server side, the subclass {@link ServerWebSocket} is used instead.

 * It implements both {@link ReadStream} and {@link WriteStream} so it can be used with
 * {@link io.jsync.streams.Pump} to pump data with flow control.

 * Instances of this class are not thread-safe

 *
 * @author Tim Fox
 */
public interface WebSocketBase extends ReadStream, WriteStream {

    /**
     * When a {@code Websocket} is created it automatically registers an event handler with the eventbus, the ID of that
     * handler is given by {@code binaryHandlerID}.

     * Given this ID, a different event loop can send a binary frame to that event handler using the event bus and
     * that buffer will be received by this instance in its own event loop and written to the underlying connection. This
     * allows you to write data to other websockets which are owned by different event loops.
     */
    String binaryHandlerID();

    /**
     * When a {@code Websocket} is created it automatically registers an event handler with the eventbus, the ID of that
     * handler is given by {@code textHandlerID}.
     * Given this ID, a different event loop can send a text frame to that event handler using the event bus and
     * that buffer will be received by this instance in its own event loop and written to the underlying connection. This
     * allows you to write data to other websockets which are owned by different event loops.
     */
    String textHandlerID();

    /**
     * Write {@code data} to the websocket as a binary frame
     */
    T writeBinaryFrame(Buffer data);

    /**
     * Write {@code str} to the websocket as a text frame
     */
    T writeTextFrame(String str);

    /**
     * Set a closed handler on the connection
     */
    T closeHandler(Handler handler);

    /**
     * Set a frame handler on the connection
     */
    T frameHandler(Handler handler);

    /**
     * Close the websocket
     */
    void close();

    /**
     * Return the remote address for this socket
     */
    InetSocketAddress remoteAddress();

    /**
     * Return the local address for this socket
     */
    InetSocketAddress localAddress();

}