Class WebSocket
Create WebSocketFactory
WebSocketFactory
is a factory class that creates
WebSocket
instances. The first step is to create a
WebSocketFactory
instance.
// Create a WebSocketFactory instance. WebSocketFactory factory = newWebSocketFactory()
;
By default, WebSocketFactory
uses SocketFactory
.
getDefault()
for
non-secure WebSocket connections (ws:
) and SSLSocketFactory
.
getDefault()
for secure WebSocket connections (
wss:
). You can change this default behavior by using
WebSocketFactory.
setSocketFactory
method, WebSocketFactory.
setSSLSocketFactory
method and WebSocketFactory.
setSSLContext
method. Note that you don't have to call a
setSSL*
method at all if you use the default SSL configuration.
Also note that calling setSSLSocketFactory
method has no
meaning if you have called setSSLContext
method. See the
description of WebSocketFactory.
createSocket(URI)
method for
details.
The following is an example to set a custom SSL context to a
WebSocketFactory
instance. (Again, you don't have to call a
setSSL*
method if you use the default SSL configuration.)
// Create a custom SSL context. SSLContext context = NaiveSSLContext.getInstance("TLS"); // Set the custom SSL context. factory.setSSLContext
(context); // Disable manual hostname verification for NaiveSSLContext. // // Manual hostname verification has been enabled since the // version 2.1. Because the verification is executed manually // after Socket.connect(SocketAddress, int) succeeds, the // hostname verification is always executed even if you has // passed an SSLContext which naively accepts any server // certificate. However, this behavior is not desirable in // some cases and you may want to disable the hostname // verification. You can disable the hostname verification // by calling WebSocketFactory.setVerifyHostname(false). factory.setVerifyHostname
(false);
NaiveSSLContext used in the above example is a factory class to
create an SSLContext
which naively
accepts all certificates without verification. It's enough for testing
purposes. When you see an error message
"unable to find valid certificate path to requested target" while
testing, try NaiveSSLContext
.
HTTP Proxy
If a WebSocket endpoint needs to be accessed via an HTTP proxy,
information about the proxy server has to be set to a
WebSocketFactory
instance before creating a WebSocket
instance. Proxy settings are represented by ProxySettings
class. A WebSocketFactory
instance has an associated
ProxySettings
instance and it can be obtained by calling
WebSocketFactory.
getProxySettings()
method.
// Get the associated ProxySettings instance.ProxySettings
settings = factory.getProxySettings()
;
ProxySettings
class has methods to set information about
a proxy server such as setHost
method and setPort
method. The
following is an example to set a secure (https
) proxy
server.
// Set a proxy server. settings.setServer
("https://proxy.example.com");
If credentials are required for authentication at a proxy server,
setId
method and setPassword
method, or
setCredentials
method can be used to set the credentials. Note that, however,
the current implementation supports only Basic Authentication.
// Set credentials for authentication at a proxy server. settings.setCredentials
(id, password);
Create WebSocket
WebSocket
class represents a WebSocket. Its instances are
created by calling one of createSocket
methods of a WebSocketFactory
instance. Below is the simplest example to create
a WebSocket
instance.
// Create a WebSocket. The scheme part can be one of the following: // 'ws', 'wss', 'http' and 'https' (case-insensitive). The user info // part, if any, is interpreted as expected. If a raw socket failed // to be created, an IOException is thrown. WebSocket ws = newWebSocketFactory()
.createWebSocket
("ws://localhost/endpoint");
There are two ways to set a timeout value for socket connection. The
first way is to call setConnectionTimeout(int timeout)
method of WebSocketFactory
.
// Create a WebSocket factory and set 5000 milliseconds as a timeout // value for socket connection. WebSocketFactory factory = new WebSocketFactory().setConnectionTimeout
(5000); // Create a WebSocket. The timeout value set above is used. WebSocket ws = factory.createWebSocket
("ws://localhost/endpoint");
The other way is to give a timeout value to a createSocket
method.
// Create a WebSocket factory. The timeout value remains 0. WebSocketFactory factory = new WebSocketFactory(); // Create a WebSocket with a socket connection timeout value. WebSocket ws = factory.createWebSocket
("ws://localhost/endpoint", 5000);
The timeout value is passed to connect
(
SocketAddress
, int)
method of Socket
.
Register Listener
After creating a WebSocket
instance, you should call addListener(WebSocketListener)
method to register a WebSocketListener
that receives WebSocket events. WebSocketAdapter
is an empty implementation of WebSocketListener
interface.
// Register a listener to receive WebSocket events. ws.addListener
(newWebSocketAdapter()
{@
Override public voidonTextMessage
(WebSocket websocket, String message) throws Exception { // Received a text message. ...... } });
The table below is the list of callback methods defined in WebSocketListener
interface.
WebSocketListener
methodsMethod Description handleCallbackError
Called when an onXxx()
method threw aThrowable
.onBinaryFrame
Called when a binary frame was received. onBinaryMessage
Called when a binary message was received. onCloseFrame
Called when a close frame was received. onConnected
Called after the opening handshake succeeded. onConnectError
Called when connectAsynchronously()
failed.onContinuationFrame
Called when a continuation frame was received. onDisconnected
Called after a WebSocket connection was closed. onError
Called when an error occurred. onFrame
Called when a frame was received. onFrameError
Called when a frame failed to be read. onFrameSent
Called when a frame was sent. onFrameUnsent
Called when a frame was not sent. onMessageDecompressionError
Called when a message failed to be decompressed. onMessageError
Called when a message failed to be constructed. onPingFrame
Called when a ping frame was received. onPongFrame
Called when a pong frame was received. onSendError
Called when an error occurred on sending a frame. onSendingFrame
Called before a frame is sent. onSendingHandshake
Called before an opening handshake is sent. onStateChanged
Called when the state of WebSocket changed. onTextFrame
Called when a text frame was received. onTextMessage
Called when a text message was received. onTextMessageError
Called when a text message failed to be constructed. onThreadCreated
Called after a thread was created. onThreadStarted
Called at the beginning of a thread's run()
method.onThreadStopping
Called at the end of a thread's run()
method.onUnexpectedError
Called when an uncaught throwable was detected.
Configure WebSocket
Before starting a WebSocket opening handshake with the server, you can configure the
WebSocket
instance by using the following methods.
Methods for Configuration METHOD DESCRIPTION addProtocol
Adds an element to Sec-WebSocket-Protocol
addExtension
Adds an element to Sec-WebSocket-Extensions
addHeader
Adds an arbitrary HTTP header. setUserInfo
Adds Authorization
header for Basic Authentication.getSocket
Gets the underlying Socket
instance to configure it. Note that this may returnnull
since version 2.9. Consider usinggetConnectedSocket()
as necessary.getConnectedSocket
Establishes and gets the underlying Socket instance to configure it. Available since version 2.9. setExtended
Disables validity checks on RSV1/RSV2/RSV3 and opcode. setFrameQueueSize
Set the size of the frame queue for congestion control. setMaxPayloadSize
Set the maximum payload size. setMissingCloseFrameAllowed
Set whether to allow the server to close the connection without sending a close frame.
Connect To Server
By calling connect()
method, connection to the server is
established and a WebSocket opening handshake is performed
synchronously. If an error occurred during the handshake,
a WebSocketException
would be thrown. Instead, when the
handshake succeeds, the connect()
implementation creates
threads and starts them to read and write WebSocket frames
asynchronously.
try { // Connect to the server and perform an opening handshake. // This method blocks until the opening handshake is finished. ws.connect()
; } catch (OpeningHandshakeException
e) { // A violation against the WebSocket protocol was detected // during the opening handshake. } catch (HostnameUnverifiedException
e) { // The certificate of the peer does not match the expected hostname. } catch (WebSocketException
e) { // Failed to establish a WebSocket connection. }
In some cases, connect()
method throws OpeningHandshakeException
which is a subclass of WebSocketException
(since version 1.19).
OpeningHandshakeException
provides additional methods such as
getStatusLine()
,
getHeaders()
and
getBody()
to access the
response from a server. The following snippet is an example to print
information that the exception holds.
catch (OpeningHandshakeException
e) { // Status line.StatusLine
sl = e.getStatusLine()
; System.out.println("=== Status Line ==="); System.out.format("HTTP Version = %s\n", sl.getHttpVersion()
); System.out.format("Status Code = %d\n", sl.getStatusCode()
); System.out.format("Reason Phrase = %s\n", sl.getReasonPhrase()
); // HTTP headers. Map<String, List<String>> headers = e.getHeaders()
; System.out.println("=== HTTP Headers ==="); for (Map.Entry<String, List<String>> entry : headers.entrySet()) { // Header name. String name = entry.getKey(); // Values of the header. List<String> values = entry.getValue(); if (values == null || values.size() == 0) { // Print the name only. System.out.println(name); continue; } for (String value : values) { // Print the name and the value. System.out.format("%s: %s\n", name, value); } } }
Also, connect()
method throws HostnameUnverifiedException
which is a subclass of WebSocketException
(since version 2.1) when
the certificate of the peer does not match the expected hostname.
Connect To Server Asynchronously
The simplest way to call connect()
method asynchronously is to
use connectAsynchronously()
method. The implementation of the
method creates a thread and calls connect()
method in the thread.
When the connect()
call failed, onConnectError()
of WebSocketListener
would be called. Note that
onConnectError()
is called only when connectAsynchronously()
was used and the connect()
call executed in the background thread
failed. Neither direct synchronous connect()
nor
connect(ExecutorService)
(described below) will trigger the callback method.
// Connect to the server asynchronously. ws.connectAsynchronously()
;
Another way to call connect()
method asynchronously is to use
connect(ExecutorService)
method. The method performs a WebSocket
opening handshake asynchronously using the given ExecutorService
.
// Prepare an ExecutorService.ExecutorService
es =Executors
.newSingleThreadExecutor()
; // Connect to the server asynchronously.Future
<WebSocket>
future = ws.connect
(es); try { // Wait for the opening handshake to complete. future.get(); } catch (ExecutionException
e) { if (e.getCause() instanceofWebSocketException
) { ...... } }
The implementation of connect(ExecutorService)
method creates
a Callable
<WebSocket>
instance by calling connectable()
method and passes the
instance to submit(Callable)
method of the given ExecutorService
. What the implementation
of call()
method of the Callable
instance does is just to call the synchronous connect()
.
Send Frames
WebSocket frames can be sent by sendFrame(WebSocketFrame)
method. Other sendXxx
methods such as sendText(String)
are aliases of sendFrame
method. All of
the sendXxx
methods work asynchronously.
However, under some conditions, sendXxx
methods
may block. See Congestion Control
for details.
Below
are some examples of sendXxx
methods. Note that
in normal cases, you don't have to call sendClose()
method
and sendPong()
(or their variants) explicitly because they
are called automatically when appropriate.
// Send a text frame. ws.sendText
("Hello."); // Send a binary frame. byte[] binary = ......; ws.sendBinary
(binary); // Send a ping frame. ws.sendPing
("Are you there?");
If you want to send fragmented frames, you have to know the details
of the specification (5.4. Fragmentation). Below is an example to send a text message
("How are you?"
) which consists of 3 fragmented frames.
// The first frame must be either a text frame or a binary frame. // And its FIN bit must be cleared. WebSocketFrame firstFrame = WebSocketFrame .createTextFrame
("How ") .setFin
(false); // Subsequent frames must be continuation frames. The FIN bit of // all continuation frames except the last one must be cleared. // Note that the FIN bit of frames returned from // WebSocketFrame.createContinuationFrame methods is cleared, so // the example below does not clear the FIN bit explicitly. WebSocketFrame secondFrame = WebSocketFrame .createContinuationFrame
("are "); // The last frame must be a continuation frame with the FIN bit set. // Note that the FIN bit of frames returned from // WebSocketFrame.createContinuationFrame methods is cleared, so // the FIN bit of the last frame must be set explicitly. WebSocketFrame lastFrame = WebSocketFrame .createContinuationFrame
("you?") .setFin
(true); // Send a text message which consists of 3 frames. ws.sendFrame
(firstFrame) .sendFrame
(secondFrame) .sendFrame
(lastFrame);
Alternatively, the same as above can be done like this.
// Send a text message which consists of 3 frames. ws.sendText
("How ", false) .sendContinuation
("are ") .sendContinuation
("you?", true);
Send Ping/Pong Frames Periodically
You can send ping frames periodically by calling setPingInterval
method with an interval in milliseconds between ping frames.
This method can be called both before and after connect()
method.
Passing zero stops the periodical sending.
// Send a ping per 60 seconds. ws.setPingInterval
(60 * 1000); // Stop the periodical sending. ws.setPingInterval
(0);
Likewise, you can send pong frames periodically by calling setPongInterval
method. "A Pong frame MAY be sent
unsolicited." (RFC 6455, 5.5.3. Pong)
You can customize payload of ping/pong frames that are sent automatically by using
setPingPayloadGenerator(PayloadGenerator)
and
setPongPayloadGenerator(PayloadGenerator)
methods. Both methods take an
instance of PayloadGenerator
interface. The following is an example to
use the string representation of the current date as payload of ping frames.
ws.setPingPayloadGenerator
(newPayloadGenerator
() {@
Override public byte[] generate() { // The string representation of the current date. return new Date().toString().getBytes(); } });
Note that the maximum payload length of control frames (e.g. ping frames) is 125.
Therefore, the length of a byte array returned from generate()
method must not exceed 125.
You can change the names of the Timer
s that send ping/pong
frames periodically by using setPingSenderName(String)
and
setPongSenderName(String)
methods.
// Change the Timers' names. ws.setPingSenderName
("PING_SENDER"); ws.setPongSenderName
("PONG_SENDER");
Auto Flush
By default, a frame is automatically flushed to the server immediately after
sendFrame
method is executed. This automatic
flush can be disabled by calling setAutoFlush
(false)
.
// Disable auto-flush. ws.setAutoFlush
(false);
To flush frames manually, call flush()
method. Note that this method
works asynchronously.
// Flush frames to the server manually. ws.flush()
;
Congestion Control
sendXxx
methods queue a WebSocketFrame
instance to the
internal queue. By default, no upper limit is imposed on the queue size, so
sendXxx
methods do not block. However, this behavior may cause
a problem if your WebSocket client application sends too many WebSocket frames in
a short time for the WebSocket server to process. In such a case, you may want
sendXxx
methods to block when many frames are queued.
You can set an upper limit on the internal queue by calling setFrameQueueSize(int)
method. As a result, if the number of frames in the queue has reached the upper limit
when a sendXxx
method is called, the method blocks until the
queue gets spaces. The code snippet below is an example to set 5 as the upper limit
of the internal frame queue.
// Set 5 as the frame queue size. ws.setFrameQueueSize
(5);
Note that under some conditions, even if the queue is full, sendXxx
methods do not block. For example, in the case where the thread to send frames
(WritingThread
) is going to stop or has already stopped. In addition,
method calls to send a control frame (e.g. sendClose()
and sendPing()
) do not block.
Maximum Payload Size
You can set an upper limit on the payload size of WebSocket frames by calling
setMaxPayloadSize(int)
method with a positive value. Text, binary and
continuation frames whose payload size is bigger than the maximum payload size
you have set will be split into multiple frames.
// Set 1024 as the maximum payload size. ws.setMaxPayloadSize
(1024);
Control frames (close, ping and pong frames) are never split as per the specification.
If permessage-deflate extension is enabled and if the payload size of a WebSocket frame after compression does not exceed the maximum payload size, the WebSocket frame is not split even if the payload size before compression execeeds the maximum payload size.
Compression
The permessage-deflate extension (RFC 7692) has been supported
since the version 1.17. To enable the extension, call addExtension
method with "permessage-deflate"
.
// Enable "permessage-deflate" extension (RFC 7692). ws.addExtension
(WebSocketExtension.PERMESSAGE_DEFLATE
);
Missing Close Frame
Some server implementations close a WebSocket connection without sending a
close frame to
a client in some cases. Strictly speaking, this is a violation against the
specification (RFC 6455). However, this
library has allowed the behavior by default since the version 1.29. Even if the
end of the input stream of a WebSocket connection were reached without a close
frame being received, it would trigger neither onError()
method nor
onFrameError()
method of WebSocketListener
. If you want to make a
WebSocket
instance report an error in the case, pass false
to
setMissingCloseFrameAllowed(boolean)
method.
// Make this library report an error when the end of the input stream // of the WebSocket connection is reached before a close frame is read. ws.setMissingCloseFrameAllowed
(false);
Direct Text Message
When a text message was received, onTextMessage(WebSocket, String)
is called. The implementation internally converts
the byte array of the text message into a String
object before calling the
listener method. If you want to receive the byte array directly without the string
conversion, call setDirectTextMessage(boolean)
with true
, and
onTextMessage(WebSocket, byte[])
will be called instead.
// Receive text messages without string conversion. ws.setDirectTextMessage
(true);
Disconnect WebSocket
Before a WebSocket is closed, a closing handshake is performed. A closing handshake
is started (1) when the server sends a close frame to the client or (2) when the
client sends a close frame to the server. You can start a closing handshake by calling
disconnect()
method (or by sending a close frame manually).
// Close the WebSocket connection. ws.disconnect()
;
disconnect()
method has some variants. If you want to change the close code
and the reason phrase of the close frame that this client will send to the server,
use a variant method such as disconnect(int, String)
. disconnect()
method itself is an alias of disconnect(
WebSocketCloseCode
.NORMAL, null)
.
Reconnection
connect()
method can be called at most only once regardless of whether the
method succeeded or failed. If you want to re-connect to the WebSocket endpoint,
you have to create a new WebSocket
instance again by calling one of
createSocket
methods of a WebSocketFactory
. You may find recreate()
method useful if you want to create a new WebSocket
instance that has the
same settings as the original instance. Note that, however, settings you made on
the raw socket of the original WebSocket
instance are not copied.
// Create a new WebSocket instance and connect to the same endpoint. ws = ws.recreate()
.connect()
;
There is a variant of recreate()
method that takes a timeout value for
socket connection. If you want to use a timeout value that is different from the
one used when the existing WebSocket
instance was created, use recreate(int timeout)
method.
Note that you should not trigger reconnection in onError()
method
because onError()
may be called multiple times due to one error. Instead,
onDisconnected()
is the right place to trigger reconnection.
Also note that the reason I use an expression of "to trigger reconnection"
instead of "to call recreate().connect()
" is that I myself
won't do it synchronously in WebSocketListener
callback
methods but will just schedule reconnection or will just go to the top of a kind
of application loop that repeats to establish a WebSocket connection until
it succeeds.
Error Handling
WebSocketListener
has some onXxxError()
methods such as onFrameError()
and onSendError()
. Among such methods, onError()
is a special
one. It is always called before any other onXxxError()
is called. For
example, in the implementation of run()
method of ReadingThread
,
Throwable
is caught and onError()
and onUnexpectedError()
are called in this order. The following is the implementation.
@
Override public void run() { try { main(); } catch (Throwable t) { // An uncaught throwable was detected in the reading thread.WebSocketException
cause = new WebSocketException(WebSocketError
.UNEXPECTED_ERROR_IN_READING_THREAD
, "An uncaught throwable was detected in the reading thread", t); // Notify the listeners. ListenerManager manager = mWebSocket.getListenerManager(); manager.callOnError(cause); manager.callOnUnexpectedError(cause); } }
So, you can handle all error cases in onError()
method. However, note
that onError()
may be called multiple times for one error cause, so don't
try to trigger reconnection in onError()
. Instead, onDiconnected()
is the right place to trigger reconnection.
All onXxxError()
methods receive a WebSocketException
instance
as the second argument (the first argument is a WebSocket
instance). The
exception class provides getError()
method
which returns a WebSocketError
enum entry. Entries in WebSocketError
enum are possible causes of errors that may occur in the implementation of this
library. The error causes are so granular that they can make it easy for you to
find the root cause when an error occurs.
Throwable
s thrown by implementations of onXXX()
callback methods
are passed to handleCallbackError()
of WebSocketListener
.
@
Override public voidhandleCallbackError
(WebSocket websocket, Throwable cause) throws Exception { // Throwables thrown by onXxx() callback methods come here. }
Thread Callbacks
Some threads are created internally in the implementation of WebSocket
.
Known threads are as follows.
Internal Threads THREAD TYPE DESCRIPTION READING_THREAD
A thread which reads WebSocket frames from the server. WRITING_THREAD
A thread which sends WebSocket frames to the server. CONNECT_THREAD
A thread which calls connect()
asynchronously.FINISH_THREAD
A thread which does finalization of a WebSocket
instance.
The following callback methods of WebSocketListener
are called according
to the life cycle of the threads.
Thread Callbacks METHOD DESCRIPTION onThreadCreated()
Called after a thread was created. onThreadStarted()
Called at the beginning of the thread's run()
method.onThreadStopping()
Called at the end of the thread's run()
method.
For example, if you want to change the name of the reading thread,
implement onThreadCreated()
method like below.
@
Override public voidonThreadCreated
(WebSocket websocket,ThreadType
type, Thread thread) { if (type == ThreadType.READING_THREAD) { thread.setName("READING_THREAD"); } }
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final long
private List
<WebSocketExtension> private String
private boolean
private WebSocketFrame
private boolean
private boolean
private int
private HandshakeBuilder
private WebSocketInputStream
private final ListenerManager
private int
private boolean
private boolean
private Object
private WebSocketOutputStream
private PerMessageCompressionExtension
private final PingSender
private final PongSender
private ReadingThread
private boolean
private boolean
private WebSocketFrame
private final SocketConnector
private final StateManager
private final Object
private final WebSocketFactory
private WritingThread
private boolean
private boolean
-
Constructor Summary
ConstructorsConstructorDescriptionWebSocket
(WebSocketFactory factory, boolean secure, String userInfo, String host, String path, SocketConnector connector) -
Method Summary
Modifier and TypeMethodDescriptionaddExtension
(WebSocketExtension extension) Add a value forSec-WebSocket-Extension
.addExtension
(String extension) Add a value forSec-WebSocket-Extension
.Add a pair of extra HTTP header.addListener
(WebSocketListener listener) Add a listener to receive events on this WebSocket.addListeners
(List<WebSocketListener> listeners) Add listeners.addProtocol
(String protocol) Add a value forSec-WebSocket-Protocol
.private void
CallWebSocketListener.onConnected(WebSocket, Map)
method of the registered listeners if it has not been called yet.private void
Remove all extensions fromSec-WebSocket-Extension
.Clear all extra HTTP headers.Remove all the listeners from this WebSocket.Remove all protocols fromSec-WebSocket-Protocol
.Clear the credentials to connect to the WebSocket endpoint.connect()
Connect to the server, send an opening handshake to the server, receive the response and then start threads to communicate with the server.connect
(ExecutorService executorService) Executeconnect()
asynchronously using the givenExecutorService
.Executeconnect()
asynchronously by creating a new thread and callingconnect()
in the thread.Disconnect the WebSocket.disconnect
(int closeCode) Disconnect the WebSocket.disconnect
(int closeCode, String reason) Disconnect the WebSocket.disconnect
(int closeCode, String reason, long closeDelay) Disconnect the WebSocket.disconnect
(String reason) Disconnect the WebSocket.protected void
finalize()
private PerMessageCompressionExtension
Find a per-message compression extension from among the agreed extensions.(package private) void
finish()
private void
Callfinish()
from within a separate thread.flush()
Flush frames to the server.private static String
Generate a value for Sec-WebSocket-Key.Get the agreed extensions.Get the agreed protocol.Get the raw socket which this WebSocket uses internally.int
Get the size of the frame queue.(package private) HandshakeBuilder
Get the handshake builder.(package private) WebSocketInputStream
getInput()
Get the input stream of the WebSocket connection.(package private) ListenerManager
Get the manager that manages registered listeners.int
Get the maximum payload size.(package private) WebSocketOutputStream
Get the output stream of the WebSocket connection.(package private) PerMessageCompressionExtension
Get the PerMessageCompressionExtension in the agreed extensions.long
Get the interval of periodical ping frames.Get the generator of payload of ping frames that are sent automatically.Get the name of theTimer
that sends ping frames periodically.long
Get the interval of periodical pong frames.Get the generator of payload of pong frames that are sent automatically.Get the name of theTimer
that sends pong frames periodically.Get the raw socket which this WebSocket uses internally if it has been established, yet.getState()
Get the current state of this WebSocket.(package private) StateManager
Get the manager that manages the state of thisWebSocket
instance.getURI()
Get the URI of the WebSocket endpoint.boolean
Check if flush is performed automatically aftersendFrame(WebSocketFrame)
is done.boolean
Check if text messages are passed to listeners without string conversion.boolean
Check if extended use of WebSocket frames are allowed.private boolean
isInState
(WebSocketState state) Check if the current state is equal to the specified state.boolean
Check if this instance allows the server to close the WebSocket connection without sending a close frame to this client.boolean
isOpen()
Check if the current state of this WebSocket isOPEN
.(package private) void
onReadingThreadFinished
(WebSocketFrame closeFrame) Called by the reading thread as its last step.(package private) void
Called by the reading thread as its first step.private void
Called when both the reading thread and the writing thread have finished.private void
Called when both the reading thread and the writing thread have started.(package private) void
onWritingThreadFinished
(WebSocketFrame closeFrame) Called by the writing thread as its last step.(package private) void
Called by the writing thread as its first step.private WebSocketInputStream
openInputStream
(Socket socket) Open the input stream of the WebSocket connection.private WebSocketOutputStream
openOutputStream
(Socket socket) Open the output stream of the WebSocket connection.readHandshake
(WebSocketInputStream input, String key) Receive an opening handshake response from the WebSocket server.recreate()
Create a newWebSocket
instance that has the same settings as this instance.recreate
(int timeout) Create a newWebSocket
instance that has the same settings as this instance.removeExtension
(WebSocketExtension extension) Remove an extension fromSec-WebSocket-Extension
.removeExtensions
(String name) Remove extensions fromSec-WebSocket-Extension
by an extension name.removeHeaders
(String name) Remove pairs of extra HTTP headers.removeListener
(WebSocketListener listener) Remove a listener from this WebSocket.removeListeners
(List<WebSocketListener> listeners) Remove listeners.removeProtocol
(String protocol) Remove a protocol fromSec-WebSocket-Protocol
.sendBinary
(byte[] message) Send a binary message to the server.sendBinary
(byte[] payload, boolean fin) Send a binary frame to the server.Send a close frame to the server.sendClose
(int closeCode) Send a close frame to the server.Send a close frame to the server.Send a continuation frame to the server.sendContinuation
(boolean fin) Send a continuation frame to the server.sendContinuation
(byte[] payload) Send a continuation frame to the server.sendContinuation
(byte[] payload, boolean fin) Send a continuation frame to the server.sendContinuation
(String payload) Send a continuation frame to the server.sendContinuation
(String payload, boolean fin) Send a continuation frame to the server.sendFrame
(WebSocketFrame frame) Send a WebSocket frame to the server.sendPing()
Send a ping frame to the server.sendPing
(byte[] payload) Send a ping frame to the server.Send a ping frame to the server.sendPong()
Send a pong frame to the server.sendPong
(byte[] payload) Send a pong frame to the server.Send a pong frame to the server.Send a text message to the server.Send a text frame to the server.(package private) void
setAgreedExtensions
(List<WebSocketExtension> extensions) Set the agreed extensions.(package private) void
setAgreedProtocol
(String protocol) Set the agreed protocol.setAutoFlush
(boolean auto) Enable or disable auto-flush of sent frames.setDirectTextMessage
(boolean direct) Set whether to receive text messages directly as byte arrays without string conversion.setExtended
(boolean extended) Allow or disallow extended use of WebSocket frames.setFrameQueueSize
(int size) Set the size of the frame queue.setMaxPayloadSize
(int size) Set the maximum payload size.setMissingCloseFrameAllowed
(boolean allowed) Set whether to allow the server to close the WebSocket connection without sending a close frame to this client.setPingInterval
(long interval) Set the interval of periodical ping frames.setPingPayloadGenerator
(PayloadGenerator generator) Set the generator of payload of ping frames that are sent automatically.setPingSenderName
(String name) Set the name of theTimer
that sends ping frames periodically.setPongInterval
(long interval) Set the interval of periodical pong frames.setPongPayloadGenerator
(PayloadGenerator generator) Set the generator of payload of pong frames that are sent automatically.setPongSenderName
(String name) Set the name of theTimer
that sends pong frames periodically.setUserInfo
(String userInfo) Set the credentials to connect to the WebSocket endpoint.setUserInfo
(String id, String password) Set the credentials to connect to the WebSocket endpoint.shakeHands
(Socket socket) Perform the opening handshake.private List
<WebSocketFrame> splitIfNecessary
(WebSocketFrame frame) private void
Start both the reading thread and the writing thread.private void
stopThreads
(long closeDelay) Stop both the reading thread and the writing thread.private void
writeHandshake
(WebSocketOutputStream output, String key) Send an opening handshake request to the WebSocket server.
-
Field Details
-
DEFAULT_CLOSE_DELAY
private static final long DEFAULT_CLOSE_DELAY- See Also:
-
mWebSocketFactory
-
mSocketConnector
-
mStateManager
-
mHandshakeBuilder
-
mListenerManager
-
mPingSender
-
mPongSender
-
mThreadsLock
-
mInput
-
mOutput
-
mReadingThread
-
mWritingThread
-
mServerHeaders
-
mAgreedExtensions
-
mAgreedProtocol
-
mExtended
private boolean mExtended -
mAutoFlush
private boolean mAutoFlush -
mMissingCloseFrameAllowed
private boolean mMissingCloseFrameAllowed -
mDirectTextMessage
private boolean mDirectTextMessage -
mFrameQueueSize
private int mFrameQueueSize -
mMaxPayloadSize
private int mMaxPayloadSize -
mOnConnectedCalled
private boolean mOnConnectedCalled -
mOnConnectedCalledLock
-
mReadingThreadStarted
private boolean mReadingThreadStarted -
mWritingThreadStarted
private boolean mWritingThreadStarted -
mReadingThreadFinished
private boolean mReadingThreadFinished -
mWritingThreadFinished
private boolean mWritingThreadFinished -
mServerCloseFrame
-
mClientCloseFrame
-
mPerMessageCompressionExtension
-
-
Constructor Details
-
WebSocket
WebSocket(WebSocketFactory factory, boolean secure, String userInfo, String host, String path, SocketConnector connector)
-
-
Method Details
-
recreate
Create a newWebSocket
instance that has the same settings as this instance. Note that, however, settings you made on the raw socket are not copied.The
WebSocketFactory
instance that you used to create thisWebSocket
instance is used again.This method calls
recreate(int)
with the timeout value that was used when this instance was created. If you want to create a socket connection with a different timeout value, userecreate(int)
method instead.- Returns:
- A new
WebSocket
instance. - Throws:
IOException
-WebSocketFactory.createSocket(URI)
threw an exception.- Since:
- 1.6
-
recreate
Create a newWebSocket
instance that has the same settings as this instance. Note that, however, settings you made on the raw socket are not copied.The
WebSocketFactory
instance that you used to create thisWebSocket
instance is used again.- Parameters:
timeout
- The timeout value in milliseconds for socket timeout. A timeout of zero is interpreted as an infinite timeout.- Returns:
- A new
WebSocket
instance. - Throws:
IllegalArgumentException
- The given timeout value is negative.IOException
-WebSocketFactory.createSocket(URI)
threw an exception.- Since:
- 1.10
-
finalize
-
getState
Get the current state of this WebSocket.The initial state is
CREATED
. Whenconnect()
is called, the state is changed toCONNECTING
, and then toOPEN
after a successful opening handshake. The state is changed toCLOSING
when a closing handshake is started, and then toCLOSED
when the closing handshake finished.See the description of
WebSocketState
for details.- Returns:
- The current state.
- See Also:
-
isOpen
public boolean isOpen()Check if the current state of this WebSocket isOPEN
.- Returns:
true
if the current state is OPEN.- Since:
- 1.1
-
isInState
Check if the current state is equal to the specified state. -
addProtocol
Add a value forSec-WebSocket-Protocol
.- Parameters:
protocol
- A protocol name.- Returns:
this
object.- Throws:
IllegalArgumentException
- The protocol name is invalid. A protocol name must be a non-empty string with characters in the range U+0021 to U+007E not including separator characters.
-
removeProtocol
Remove a protocol fromSec-WebSocket-Protocol
.- Parameters:
protocol
- A protocol name.null
is silently ignored.- Returns:
this
object.- Since:
- 1.14
-
clearProtocols
Remove all protocols fromSec-WebSocket-Protocol
.- Returns:
this
object.- Since:
- 1.14
-
addExtension
Add a value forSec-WebSocket-Extension
.- Parameters:
extension
- An extension.null
is silently ignored.- Returns:
this
object.
-
addExtension
Add a value forSec-WebSocket-Extension
. The input string should comply with the format described in 9.1. Negotiating Extensions in RFC 6455.- Parameters:
extension
- A string that represents a WebSocket extension. If it does not comply with RFC 6455, no value is added toSec-WebSocket-Extension
.- Returns:
this
object.- Since:
- 1.14
-
removeExtension
Remove an extension fromSec-WebSocket-Extension
.- Parameters:
extension
- An extension to remove.null
is silently ignored.- Returns:
this
object.- Since:
- 1.14
-
removeExtensions
Remove extensions fromSec-WebSocket-Extension
by an extension name.- Parameters:
name
- An extension name.null
is silently ignored.- Returns:
this
object.- Since:
- 1.14
-
clearExtensions
Remove all extensions fromSec-WebSocket-Extension
.- Returns:
this
object.- Since:
- 1.14
-
addHeader
Add a pair of extra HTTP header.- Parameters:
name
- An HTTP header name. Whennull
or an empty string is given, no header is added.value
- The value of the HTTP header.- Returns:
this
object.
-
removeHeaders
Remove pairs of extra HTTP headers.- Parameters:
name
- An HTTP header name.null
is silently ignored.- Returns:
this
object.- Since:
- 1.14
-
clearHeaders
Clear all extra HTTP headers.- Returns:
this
object.- Since:
- 1.14
-
setUserInfo
Set the credentials to connect to the WebSocket endpoint.- Parameters:
userInfo
- The credentials for Basic Authentication. The format should beid:password
.- Returns:
this
object.
-
setUserInfo
Set the credentials to connect to the WebSocket endpoint.- Parameters:
id
- The ID.password
- The password.- Returns:
this
object.
-
clearUserInfo
Clear the credentials to connect to the WebSocket endpoint.- Returns:
this
object.- Since:
- 1.14
-
isExtended
public boolean isExtended()Check if extended use of WebSocket frames are allowed.When extended use is allowed, values of RSV1/RSV2/RSV3 bits and opcode of frames are not checked. On the other hand, if not allowed (default), non-zero values for RSV1/RSV2/RSV3 bits and unknown opcodes cause an error. In such a case,
onFrameError
method of listeners are called and the WebSocket is eventually closed.- Returns:
true
if extended use of WebSocket frames are allowed.
-
setExtended
Allow or disallow extended use of WebSocket frames.- Parameters:
extended
-true
to allow extended use of WebSocket frames.- Returns:
this
object.
-
isAutoFlush
public boolean isAutoFlush()Check if flush is performed automatically aftersendFrame(WebSocketFrame)
is done. The default value istrue
.- Returns:
true
if flush is performed automatically.- Since:
- 1.5
-
setAutoFlush
Enable or disable auto-flush of sent frames.- Parameters:
auto
-true
to enable auto-flush.false
to disable it.- Returns:
this
object.- Since:
- 1.5
-
isMissingCloseFrameAllowed
public boolean isMissingCloseFrameAllowed()Check if this instance allows the server to close the WebSocket connection without sending a close frame to this client. The default value istrue
.- Returns:
true
if the configuration allows for the server to close the WebSocket connection without sending a close frame to this client.false
if the configuration requires that an error be reported viaonError()
method andonFrameError()
method ofWebSocketListener
.- Since:
- 1.29
-
setMissingCloseFrameAllowed
Set whether to allow the server to close the WebSocket connection without sending a close frame to this client.- Parameters:
allowed
-true
to allow the server to close the WebSocket connection without sending a close frame to this client.false
to make this instance report an error when the end of the input stream of the WebSocket connection is reached before a close frame is read.- Returns:
this
object.- Since:
- 1.29
-
isDirectTextMessage
public boolean isDirectTextMessage()Check if text messages are passed to listeners without string conversion.If this method returns
true
, when a text message is received,onTextMessage(WebSocket, byte[])
will be called instead ofonTextMessage(WebSocket, String)
. The purpose of this behavior is to skip internal string conversion which is performed in the implementation ofReadingThread
.- Returns:
true
if text messages are passed to listeners without string conversion.- Since:
- 2.6
-
setDirectTextMessage
Set whether to receive text messages directly as byte arrays without string conversion.If
true
is set to this property, when a text message is received,onTextMessage(WebSocket, byte[])
will be called instead ofonTextMessage(WebSocket, String)
. The purpose of this behavior is to skip internal string conversion which is performed in the implementation ofReadingThread
.- Parameters:
direct
-true
to receive text messages as byte arrays.- Returns:
this
object.- Since:
- 2.6
-
flush
Flush frames to the server. Flush is performed asynchronously.- Returns:
this
object.- Since:
- 1.5
-
getFrameQueueSize
public int getFrameQueueSize()Get the size of the frame queue. The default value is 0 and it means there is no limit on the queue size.- Returns:
- The size of the frame queue.
- Since:
- 1.15
-
setFrameQueueSize
Set the size of the frame queue. The default value is 0 and it means there is no limit on the queue size.sendXxx
methods queue aWebSocketFrame
instance to the internal queue. If the number of frames in the queue has reached the upper limit (which has been set by this method) when asendXxx
method is called, the method blocks until the queue gets spaces.Under some conditions, even if the queue is full,
sendXxx
methods do not block. For example, in the case where the thread to send frames (WritingThread
) is going to stop or has already stopped. In addition, method calls to send a control frame (e.g.sendClose()
andsendPing()
) do not block.- Parameters:
size
- The queue size. 0 means no limit. Negative numbers are not allowed.- Returns:
this
object.- Throws:
IllegalArgumentException
-size
is negative.- Since:
- 1.15
-
getMaxPayloadSize
public int getMaxPayloadSize()Get the maximum payload size. The default value is 0 which means that the maximum payload size is not set and as a result frames are not split.- Returns:
- The maximum payload size. 0 means that the maximum payload size is not set.
- Since:
- 1.27
-
setMaxPayloadSize
Set the maximum payload size.Text, binary and continuation frames whose payload size is bigger than the maximum payload size will be split into multiple frames. Note that control frames (close, ping and pong frames) are not split as per the specification even if their payload size exceeds the maximum payload size.
- Parameters:
size
- The maximum payload size. 0 to unset the maximum payload size.- Returns:
this
object.- Throws:
IllegalArgumentException
-size
is negative.- Since:
- 1.27
-
getPingInterval
public long getPingInterval()Get the interval of periodical ping frames.- Returns:
- The interval in milliseconds.
- Since:
- 1.2
-
setPingInterval
Set the interval of periodical ping frames.Setting a positive number starts sending ping frames periodically. Setting zero stops the periodical sending. This method can be called both before and after
connect()
method.- Parameters:
interval
- The interval in milliseconds. A negative value is regarded as zero.- Returns:
this
object.- Since:
- 1.2
-
getPongInterval
public long getPongInterval()Get the interval of periodical pong frames.- Returns:
- The interval in milliseconds.
- Since:
- 1.2
-
setPongInterval
Set the interval of periodical pong frames.Setting a positive number starts sending pong frames periodically. Setting zero stops the periodical sending. This method can be called both before and after
connect()
method.- An excerpt from RFC 6455, 5.5.3. Pong
-
A Pong frame MAY be sent unsolicited. This serves as a unidirectional heartbeat. A response to an unsolicited Pong frame is not expected.
- Parameters:
interval
- The interval in milliseconds. A negative value is regarded as zero.- Returns:
this
object.- Since:
- 1.2
-
getPingPayloadGenerator
Get the generator of payload of ping frames that are sent automatically.- Returns:
- The generator of payload ping frames that are sent automatically.
- Since:
- 1.20
-
setPingPayloadGenerator
Set the generator of payload of ping frames that are sent automatically.- Parameters:
generator
- The generator of payload ping frames that are sent automatically.- Since:
- 1.20
-
getPongPayloadGenerator
Get the generator of payload of pong frames that are sent automatically.- Returns:
- The generator of payload pong frames that are sent automatically.
- Since:
- 1.20
-
setPongPayloadGenerator
Set the generator of payload of pong frames that are sent automatically.- Parameters:
generator
- The generator of payload ppng frames that are sent automatically.- Since:
- 1.20
-
getPingSenderName
Get the name of theTimer
that sends ping frames periodically.- Returns:
- The
Timer
's name. - Since:
- 2.5
-
setPingSenderName
Set the name of theTimer
that sends ping frames periodically.- Parameters:
name
- A name for theTimer
.- Returns:
this
object.- Since:
- 2.5
-
getPongSenderName
Get the name of theTimer
that sends pong frames periodically.- Returns:
- The
Timer
's name. - Since:
- 2.5
-
setPongSenderName
Set the name of theTimer
that sends pong frames periodically.- Parameters:
name
- A name for theTimer
.- Returns:
this
object.- Since:
- 2.5
-
addListener
Add a listener to receive events on this WebSocket.- Parameters:
listener
- A listener to add.- Returns:
this
object.
-
addListeners
Add listeners.- Parameters:
listeners
- Listeners to add.null
is silently ignored.null
elements in the list are ignored, too.- Returns:
this
object.- Since:
- 1.14
-
removeListener
Remove a listener from this WebSocket.- Parameters:
listener
- A listener to remove.null
won't cause an error.- Returns:
this
object.- Since:
- 1.13
-
removeListeners
Remove listeners.- Parameters:
listeners
- Listeners to remove.null
is silently ignored.null
elements in the list are ignored, too.- Returns:
this
object.- Since:
- 1.14
-
clearListeners
Remove all the listeners from this WebSocket.- Returns:
this
object.- Since:
- 1.13
-
getSocket
Get the raw socket which this WebSocket uses internally if it has been established, yet.Version 2.9 has changed the behavior of this method, and this method may return
null
if the underlying socket has not been established yet. Consider usinggetConnectedSocket()
method as necessary.- Returns:
- The underlying
Socket
instance. This may benull
in case the underlying socket has not been established, yet. - See Also:
-
getConnectedSocket
Get the raw socket which this WebSocket uses internally. This will establish a connection to the server if not already done.- Returns:
- The underlying
Socket
instance. - Throws:
WebSocketException
- Since:
- 2.9
-
getURI
Get the URI of the WebSocket endpoint. The scheme part is either"ws"
or"wss"
. The authority part is always empty.- Returns:
- The URI of the WebSocket endpoint.
- Since:
- 1.1
-
connect
Connect to the server, send an opening handshake to the server, receive the response and then start threads to communicate with the server.As necessary,
addProtocol(String)
,addExtension(WebSocketExtension)
addHeader(String, String)
should be called before you call this method. It is because the parameters set by these methods are used in the opening handshake.Also, as necessary,
getSocket()
should be used to set up socket parameters before you call this method. For example, you can set the socket timeout like the following. Note that, however, because the version 2.9 changed the behavior ofgetSocket()
and the method may returnnull
if the underlying socket has not been established yet, you may need to usegetConnectedSocket()
method instead.WebSocket websocket = ......; websocket.
getSocket()
.setSoTimeout
(5000); // getConnectedSocket() instead of getSocket(), since version 2.9. websocket.getConnectedSocket()
.setSoTimeout
(5000);If the WebSocket endpoint requires Basic Authentication, you can set credentials by
setUserInfo(userInfo)
orsetUserInfo(id, password)
before you call this method. Note that if the URI passed toWebSocketFactory
.createSocket
method contains the user-info part, you don't have to callsetUserInfo
method.Note that this method can be called at most only once regardless of whether this method succeeded or failed. If you want to re-connect to the WebSocket endpoint, you have to create a new
WebSocket
instance again by calling one ofcreateSocket
methods of aWebSocketFactory
. You may findrecreate()
method useful if you want to create a newWebSocket
instance that has the same settings as this instance. (But settings you made on the raw socket are not copied.)- Returns:
this
object.- Throws:
WebSocketException
-- The current state of the WebSocket is not
CREATED
- Connecting the server failed.
- The opening handshake failed.
- The current state of the WebSocket is not
-
connect
Executeconnect()
asynchronously using the givenExecutorService
. This method is just an alias of the following.executorService.
submit
(connectable()
)- Parameters:
executorService
- AnExecutorService
to execute a task created byconnectable()
.- Returns:
- The value returned from
ExecutorService.submit(Callable)
. - Throws:
NullPointerException
- If the givenExecutorService
isnull
.RejectedExecutionException
- If the givenExecutorService
rejected the task created byconnectable()
.- Since:
- 1.7
- See Also:
-
connectable
-
connectAsynchronously
Executeconnect()
asynchronously by creating a new thread and callingconnect()
in the thread. Ifconnect()
failed,onConnectError()
method ofWebSocketListener
is called.- Returns:
this
object.- Since:
- 1.8
-
disconnect
Disconnect the WebSocket.This method is an alias of
disconnect
(
WebSocketCloseCode.NORMAL
, null)
.- Returns:
this
object.
-
disconnect
Disconnect the WebSocket.This method is an alias of
disconnect
(closeCode, null)
.- Parameters:
closeCode
- The close code embedded in a close frame which this WebSocket client will send to the server.- Returns:
this
object.- Since:
- 1.5
-
disconnect
Disconnect the WebSocket.This method is an alias of
disconnect
(
WebSocketCloseCode.NORMAL
, reason)
.- Parameters:
reason
- The reason embedded in a close frame which this WebSocket client will send to the server. Note that the length of the bytes which represents the given reason must not exceed 125. In other words,(reason.
getBytes
("UTF-8").length <= 125)
must be true.- Returns:
this
object.- Since:
- 1.5
-
disconnect
Disconnect the WebSocket.This method is an alias of
disconnect
(closeCode, reason, 10000L)
.- Parameters:
closeCode
- The close code embedded in a close frame which this WebSocket client will send to the server.reason
- The reason embedded in a close frame which this WebSocket client will send to the server. Note that the length of the bytes which represents the given reason must not exceed 125. In other words,(reason.
getBytes
("UTF-8").length <= 125)
must be true.- Returns:
this
object.- Since:
- 1.5
- See Also:
-
disconnect
Disconnect the WebSocket.- Parameters:
closeCode
- The close code embedded in a close frame which this WebSocket client will send to the server.reason
- The reason embedded in a close frame which this WebSocket client will send to the server. Note that the length of the bytes which represents the given reason must not exceed 125. In other words,(reason.
getBytes
("UTF-8").length <= 125)
must be true.closeDelay
- Delay in milliseconds before callingSocket.close()
forcibly. This safeguard is needed for the case where the server fails to send back a close frame. The default value is 10000 (= 10 seconds). When a negative value is given, the default value is used. If a very short time (e.g. 0) is given, it is likely to happen either (1) that this client will fail to send a close frame to the server (in this case, you will probably see an error message "Flushing frames to the server failed: Socket closed") or (2) that the WebSocket connection will be closed before this client receives a close frame from the server (in this case, the second argument ofWebSocketListener.onDisconnected
will benull
).- Returns:
this
object.- Since:
- 1.26
- See Also:
-
getAgreedExtensions
Get the agreed extensions.This method works correctly only after
connect()
succeeds (= after the opening handshake succeeds).- Returns:
- The agreed extensions.
-
getAgreedProtocol
Get the agreed protocol.This method works correctly only after
connect()
succeeds (= after the opening handshake succeeds).- Returns:
- The agreed protocol.
-
sendFrame
Send a WebSocket frame to the server.This method just queues the given frame. Actual transmission is performed asynchronously.
When the current state of this WebSocket is not
OPEN
, this method does not accept the frame.Sending a close frame changes the state to
CLOSING
(if the current state is neitherCLOSING
norCLOSED
).Note that the validity of the give frame is not checked. For example, even if the payload length of a given frame is greater than 125 and the opcode indicates that the frame is a control frame, this method accepts the given frame.
- Parameters:
frame
- A WebSocket frame to be sent to the server. Ifnull
is given, nothing is done.- Returns:
this
object.
-
splitIfNecessary
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame()
)
.Note that the FIN bit of a frame sent by this method is
false
. If you want to set the FIN bit, usesendContinuation(boolean fin)
withfin=true
.- Returns:
this
object.
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame()
.
setFin
(fin))
.- Parameters:
fin
- The FIN bit value.- Returns:
this
object.
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame
(payload))
.Note that the FIN bit of a frame sent by this method is
false
. If you want to set the FIN bit, usesendContinuation(String payload, boolean fin)
withfin=true
.- Parameters:
payload
- The payload of a continuation frame.- Returns:
this
object.
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame
(payload).
setFin
(fin))
.- Parameters:
payload
- The payload of a continuation frame.fin
- The FIN bit value.- Returns:
this
object.
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame
(payload))
.Note that the FIN bit of a frame sent by this method is
false
. If you want to set the FIN bit, usesendContinuation(byte[] payload, boolean fin)
withfin=true
.- Parameters:
payload
- The payload of a continuation frame.- Returns:
this
object.
-
sendContinuation
Send a continuation frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createContinuationFrame
(payload).
setFin
(fin))
.- Parameters:
payload
- The payload of a continuation frame.fin
- The FIN bit value.- Returns:
this
object.
-
sendText
Send a text message to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createTextFrame
(message))
.If you want to send a text frame that is to be followed by continuation frames, use
setText(String payload, boolean fin)
withfin=false
.- Parameters:
message
- A text message to be sent to the server.- Returns:
this
object.
-
sendText
Send a text frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createTextFrame
(payload).
setFin
(fin))
.- Parameters:
payload
- The payload of a text frame.fin
- The FIN bit value.- Returns:
this
object.
-
sendBinary
Send a binary message to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createBinaryFrame
(message))
.If you want to send a binary frame that is to be followed by continuation frames, use
setBinary(byte[] payload, boolean fin)
withfin=false
.- Parameters:
message
- A binary message to be sent to the server.- Returns:
this
object.
-
sendBinary
Send a binary frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createBinaryFrame
(payload).
setFin
(fin))
.- Parameters:
payload
- The payload of a binary frame.fin
- The FIN bit value.- Returns:
this
object.
-
sendClose
Send a close frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createCloseFrame()
).- Returns:
this
object.
-
sendClose
Send a close frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createCloseFrame
(closeCode))
.- Parameters:
closeCode
- The close code.- Returns:
this
object.- See Also:
-
sendClose
Send a close frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createCloseFrame
(closeCode, reason))
.- Parameters:
closeCode
- The close code.reason
- The close reason. Note that a control frame's payload length must be 125 bytes or less (RFC 6455, 5.5. Control Frames).- Returns:
this
object.- See Also:
-
sendPing
Send a ping frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPingFrame()
).- Returns:
this
object.
-
sendPing
Send a ping frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPingFrame
(payload))
.- Parameters:
payload
- The payload for a ping frame. Note that a control frame's payload length must be 125 bytes or less (RFC 6455, 5.5. Control Frames).- Returns:
this
object.
-
sendPing
Send a ping frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPingFrame
(payload))
.- Parameters:
payload
- The payload for a ping frame. Note that a control frame's payload length must be 125 bytes or less (RFC 6455, 5.5. Control Frames).- Returns:
this
object.
-
sendPong
Send a pong frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPongFrame()
).- Returns:
this
object.
-
sendPong
Send a pong frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPongFrame
(payload))
.- Parameters:
payload
- The payload for a pong frame. Note that a control frame's payload length must be 125 bytes or less (RFC 6455, 5.5. Control Frames).- Returns:
this
object.
-
sendPong
Send a pong frame to the server.This method is an alias of
sendFrame
(WebSocketFrame.
createPongFrame
(payload))
.- Parameters:
payload
- The payload for a pong frame. Note that a control frame's payload length must be 125 bytes or less (RFC 6455, 5.5. Control Frames).- Returns:
this
object.
-
changeStateOnConnect
- Throws:
WebSocketException
-
shakeHands
Perform the opening handshake.- Throws:
WebSocketException
-
openInputStream
Open the input stream of the WebSocket connection. The stream is used by the reading thread.- Throws:
WebSocketException
-
openOutputStream
Open the output stream of the WebSocket connection. The stream is used by the writing thread.- Throws:
WebSocketException
-
generateWebSocketKey
Generate a value for Sec-WebSocket-Key.The request MUST include a header field with the name Sec-WebSocket-Key. The value of this header field MUST be a nonce consisting of a randomly selected 16-byte value that has been base64-encoded (see Section 4 of RFC 4648). The nonce MUST be selected randomly for each connection.
- Returns:
- A randomly generated WebSocket key.
-
writeHandshake
Send an opening handshake request to the WebSocket server.- Throws:
WebSocketException
-
readHandshake
private Map<String,List<String>> readHandshake(WebSocketInputStream input, String key) throws WebSocketException Receive an opening handshake response from the WebSocket server.- Throws:
WebSocketException
-
startThreads
private void startThreads()Start both the reading thread and the writing thread.The reading thread will call
onReadingThreadStarted()
as its first step. Likewise, the writing thread will callonWritingThreadStarted()
as its first step. After both the threads have started,onThreadsStarted()
is called. -
stopThreads
private void stopThreads(long closeDelay) Stop both the reading thread and the writing thread.The reading thread will call
onReadingThreadFinished(WebSocketFrame)
as its last step. Likewise, the writing thread will callonWritingThreadFinished(WebSocketFrame)
as its last step. After both the threads have stopped,onThreadsFinished()
is called. -
getInput
WebSocketInputStream getInput()Get the input stream of the WebSocket connection. -
getOutput
WebSocketOutputStream getOutput()Get the output stream of the WebSocket connection. -
getStateManager
StateManager getStateManager()Get the manager that manages the state of thisWebSocket
instance. -
getListenerManager
ListenerManager getListenerManager()Get the manager that manages registered listeners. -
getHandshakeBuilder
HandshakeBuilder getHandshakeBuilder()Get the handshake builder.HandshakeReader
uses this method. -
setAgreedExtensions
Set the agreed extensions.HandshakeReader
uses this method. -
setAgreedProtocol
Set the agreed protocol.HandshakeReader
uses this method. -
onReadingThreadStarted
void onReadingThreadStarted()Called by the reading thread as its first step. -
onWritingThreadStarted
void onWritingThreadStarted()Called by the writing thread as its first step. -
callOnConnectedIfNotYet
private void callOnConnectedIfNotYet()CallWebSocketListener.onConnected(WebSocket, Map)
method of the registered listeners if it has not been called yet. Either the reading thread or the writing thread calls this method. -
onThreadsStarted
private void onThreadsStarted()Called when both the reading thread and the writing thread have started. This method is called in the context of either the reading thread or the writing thread. -
onReadingThreadFinished
Called by the reading thread as its last step. -
onWritingThreadFinished
Called by the writing thread as its last step. -
onThreadsFinished
private void onThreadsFinished()Called when both the reading thread and the writing thread have finished. This method is called in the context of either the reading thread or the writing thread. -
finish
void finish() -
finishAsynchronously
private void finishAsynchronously()Callfinish()
from within a separate thread. -
findAgreedPerMessageCompressionExtension
Find a per-message compression extension from among the agreed extensions. -
getPerMessageCompressionExtension
PerMessageCompressionExtension getPerMessageCompressionExtension()Get the PerMessageCompressionExtension in the agreed extensions. This method returns null if a per-message compression extension is not found in the agreed extensions.
-