kazyx/wirespider

NIO based compact WebSocket (RFC6455) client library for Java and Android.

WireSpider

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

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

buildscript {
    repositories {
        jcenter()
    }
}

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

Usage

Set-up

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));

Android

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() {
    @Override
    public void onTextMessage(String message) {
        // Received text message.
    }

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

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

Blocking style

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

WebSocket websocket = factory.open(req);

Async style

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

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

Send messages

websocket.sendTextMessageAsync("Hello");

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

websocket.closeAsync();
// WebSocketHandler.onClosed() will be called soon.

Release resources

factory.destroy();

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);

WebSocketFactory.setSslContext(context);

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 'com.google.android.gms:play-services-basement:+'
}

ProviderInstaller.installIfNeeded(getApplicationContext());

Extensions

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()
        .setCompressionThreshold(100)
        .build();
List<ExtensionRequest> extensions = new ArrayList<>();
extensions.add(deflate);

SessionRequest req = new SessionRequest.Builder(uri, handler)
        .setExtensions(extensions)
        .build();

ProGuard

No additional prevension required.

Contribution

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

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

License

This software is released under the MIT License.

wirespider's Issues

wss does not work on Android 4.4 or older

Affected version: 1.2.1
Server: wss://echo.websocket.org

• NG: Nexus 4 Android 4.2.2
• NG: Xperia Z1 Android 4.4.2
• OK: Nexus 4 Android 5.0
• OK: Nexus 5x Android 6.0.1
• OK: Java SE 1.8.0_66 (Windows 10 x64)
• OK: Java SE 1.7.0_76 (Travis-CI Ubuntu 12.04LTS x64)