All Downloads are FREE. Search and download functionalities are using the official Maven repository.

okhttp3.WebSocket Maven / Gradle / Ivy

/*
 * Copyright (C) 2016 Square, Inc.
 *
 * Licensed 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 okhttp3;

import javax.annotation.Nullable;
import okio.ByteString;

/**
 * A non-blocking interface to a web socket. Use the {@linkplain WebSocket.Factory factory} to
 * create instances; usually this is {@link OkHttpClient}.
 *
 * 

Web Socket Lifecycle

* * Upon normal operation each web socket progresses through a sequence of states: * *
    *
  • Connecting: the initial state of each web socket. Messages may be enqueued * but they won't be transmitted until the web socket is open. *
  • Open: the web socket has been accepted by the remote peer and is fully * operational. Messages in either direction are enqueued for immediate transmission. *
  • Closing: one of the peers on the web socket has initiated a graceful * shutdown. The web socket will continue to transmit already-enqueued messages but will * refuse to enqueue new ones. *
  • Closed: the web socket has transmitted all of its messages and has * received all messages from the peer. *
* * Web sockets may fail due to HTTP upgrade problems, connectivity problems, or if either peer * chooses to short-circuit the graceful shutdown process: * *
    *
  • Canceled: the web socket connection failed. Messages that were * successfully enqueued by either peer may not have been transmitted to the other. *
* * Note that the state progression is independent for each peer. Arriving at a gracefully-closed * state indicates that a peer has sent all of its outgoing messages and received all of its * incoming messages. But it does not guarantee that the other peer will successfully receive all of * its incoming messages. */ public interface WebSocket { /** Returns the original request that initiated this web socket. */ Request request(); /** * Returns the size in bytes of all messages enqueued to be transmitted to the server. This * doesn't include framing overhead. It also doesn't include any bytes buffered by the operating * system or network intermediaries. This method returns 0 if no messages are waiting * in the queue. If may return a nonzero value after the web socket has been canceled; this * indicates that enqueued messages were not transmitted. */ long queueSize(); /** * Attempts to enqueue {@code text} to be UTF-8 encoded and sent as a the data of a text (type * {@code 0x1}) message. * *

This method returns true if the message was enqueued. Messages that would overflow the * outgoing message buffer will be rejected and trigger a {@linkplain #close graceful shutdown} of * this web socket. This method returns false in that case, and in any other case where this * web socket is closing, closed, or canceled. * *

This method returns immediately. */ boolean send(String text); /** * Attempts to enqueue {@code bytes} to be sent as a the data of a binary (type {@code 0x2}) * message. * *

This method returns true if the message was enqueued. Messages that would overflow the * outgoing message buffer (16 MiB) will be rejected and trigger a * {@linkplain #close graceful shutdown} of this web socket. This method returns false in that * case, and in any other case where this web socket is closing, closed, or canceled. * *

This method returns immediately. */ boolean send(ByteString bytes); /** * Attempts to initiate a graceful shutdown of this web socket. Any already-enqueued messages will * be transmitted before the close message is sent but subsequent calls to {@link #send} will * return false and their messages will not be enqueued. * *

This returns true if a graceful shutdown was initiated by this call. It returns false and if * a graceful shutdown was already underway or if the web socket is already closed or canceled. * * @param code Status code as defined by Section 7.4 of RFC 6455. * @param reason Reason for shutting down or {@code null}. * @throws IllegalArgumentException if code is invalid. */ boolean close(int code, @Nullable String reason); /** * Immediately and violently release resources held by this web socket, discarding any enqueued * messages. This does nothing if the web socket has already been closed or canceled. */ void cancel(); interface Factory { /** * Creates a new web socket and immediately returns it. Creating a web socket initiates an * asynchronous process to connect the socket. Once that succeeds or fails, {@code listener} * will be notified. The caller must either close or cancel the returned web socket when it is * no longer in use. */ WebSocket newWebSocket(Request request, WebSocketListener listener); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy