Awesome Open Source
Awesome Open Source


Build Status Coverage Status Download

WireSpider is a simple and compact WebSocket (RFC6455) client written in Java.

  • High performance java.nio based implementation.
  • Incredibly compact binary size.
  • Android compatible. (Note that Java 7 language features must be enabled.)


Download JAR from Bintray, or write Gradle dependency as follows.

buildscript {
    repositories {

dependencies {
    compile 'net.kazyx:wirespider:1.3.1'

Build from source code

cd <root>/wirespider
./gradlew wirespider:assemble

Now you can find wirespider-x.y.z.jar at <root>/wirespider/core/build/libs



Set external Base64 conversion function at first. The following snippets are the samples for Java 8 and Android.

Java 8

Base64.setEncoder(source -> java.util.Base64.getEncoder().encodeToString(source));


Base64.setEncoder(source -> android.util.Base64.encodeToString(source, android.util.Base64.DEFAULT));

Open WebSocket connection

WebSocketFactory factory = new WebSocketFactory();
// It is recommended to use this WebSocketFactory while your process is alive.

URI uri = URI.create("ws://host:port/path"); // ws scheme
WebSocketHandler handler = new WebSocketHandler() {
    public void onTextMessage(String message) {
        // Received text message.

    public void onBinaryMessage(byte[] message) {
        // Received binary message.

    public void onClosed(int code, String reason) {
        // Connection is closed.

Blocking style

SessionRequest req = new SessionRequest.Builder(uri, handler)
        .setConnectionTimeout(5, TimeUnit.SECONDS)

WebSocket websocket =;

Async style

SessionRequest req = new SessionRequest.Builder(uri, handler)

Future<WebSocket> futureWebSocket = factory.openAsync(req);

Send messages


websocket.sendBinaryMessageAsync(new byte[]{0x01, 0x02, 0x03, 0x04});

Send partial messages

try (PartialMessageWriter writer = websocket.newPartialMessageWriter()) {
    writer.sendPartialFrameAsync("H", false);
    writer.sendPartialFrameAsync("e", false);
    writer.sendPartialFrameAsync("llo", true/*isFinal*/);
} // Don't forget to close PartialMessageWriter

Close connection

// WebSocketHandler.onClosed() will be called soon.

Release resources


WebSocket over TLS

Use URI created with wss scheme instead of ws.

URI uri = URI.create("wss://host:port/path");

TLSv1.1 and TLSv1.2 on JDK7

Use SSLContext on which the newer version of TLS is enabled, since JDK7 disables client side TLSv1.1 and TLSv1.2 by default.

SSLContext context = SSLContext.getInstance("TLSv1.1");
context.init(null, null, null);


TLSv1.1 and over on Android 4.4 and lower versions

It is recommended to use Google Play services to enable TLSv1.1 and over.

dependencies {
    compile ''


WebSocket extensions can be implemented with net.kazyx.wirespider.extension.Extension interface.

Per-Message Deflate extension


Per-Message Deflate extension (RFC7692) is provided by wirespider-pmdeflate placed under wirespider/permessage-deflate.
Download JAR or write Gradle dependency as follows.

dependencies {
    compile 'net.kazyx:wirespider-pmdeflate:1.3.1'

Set DeflateRequest into the SessionRequest.

ExtensionRequest deflate = new DeflateRequest.Builder()
List<ExtensionRequest> extensions = new ArrayList<>();

SessionRequest req = new SessionRequest.Builder(uri, handler)


No additional prevension required.


Contribution for bugfix, performance improvement, API refinement and extension implementation are welcome.

Note that JUnit test code is required for the pull request.


This software is released under the MIT License.

Alternatives To Wirespider
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Java (392,170
Websocket (13,921
Tls (4,954
Nio (822
Websocket Client (528
Deflate (517
Rfc 6455 (23