This repository contains a barebones WebSocket server and client implementation written in 100% Java. The underlying classes are implemented java.nio, which allows for a non-blocking event-driven model (similar to the WebSocket API for web browsers).

Implemented WebSocket protocol versions are:

• RFC 6455

Here some more details about protocol versions/drafts.

You can build using Ant, Maven, Gradle or Leiningen but there is nothing against just putting the source path src/main/java on your applications buildpath.

ant 

will create the javadoc of this library at doc/ and build the library itself: dist/java_websocket.jar

The ant targets are: compile, jar, doc and clean

To use maven add this dependency to your pom.xml:

<dependency>
  <groupId>org.java-websocket</groupId>
  <artifactId>Java-WebSocket</artifactId>
  <version>1.3.8</version>
</dependency>

To use Gradle add the maven central repository to your repositories list :

mavenCentral()

Then you can just add the latest version to your build.

compile "org.java-websocket:Java-WebSocket:1.3.8"

The org.java_websocket.server.WebSocketServer abstract class implements the server-side of the WebSocket Protocol. A WebSocket server by itself doesn't do anything except establish socket connections though HTTP. After that it's up to your subclass to add purpose.

An example for a WebSocketServer can be found in both the wiki and the example folder.

The org.java_websocket.client.WebSocketClient abstract class can connect to valid WebSocket servers. The constructor expects a valid ws:// URI to connect to. Important events onOpen, onClose, onMessage and onError get fired throughout the life of the WebSocketClient, and must be implemented in your subclass.

An example for a WebSocketClient can be found in both the wiki and the example folder.

You can find a lot of examples here.

This library supports wss. To see how to use wss please take a look at the examples.

If you do not have a valid certificate in place then you will have to create a self signed one. Browsers will simply refuse the connection in case of a bad certificate and will not ask the user to accept it. So the first step will be to make a browser to accept your self signed certificate. ( https://bugzilla.mozilla.org/show_bug.cgi?id=594502 ).
If the websocket server url is wss://localhost:8000 visit the url https://localhost:8000 with your browser. The browser will recognize the handshake and allow you to accept the certificate. This technique is also demonstrated in this video.

The vm option -Djavax.net.debug=all can help to find out if there is a problem with the certificate.

It is currently not possible to accept ws and wss connections at the same time via the same websocket server instance.

For some reason Firefox does not allow multiple connections to the same wss server if the server uses a different port than the default port (443).

If you want to use wss on the android platfrom you should take a look at this.

I ( @Davidiusdadi ) would be glad if you would give some feedback whether wss is working fine for you or not.

Java-WebSocket is known to work with:

• Java 1.6 and higher
• Android 4.0 and higher

Other JRE implementations may work as well, but haven't been tested.

Please note Android Emulator has issues using IPv6 addresses. Executing any socket related code (like this library) inside it will address an error

java.net.SocketException: Bad address family

You have to manually disable IPv6 by calling

java.lang.System.setProperty("java.net.preferIPv6Addresses", "false");
java.lang.System.setProperty("java.net.preferIPv4Stack", "true");

somewhere in your project, before instantiating the WebSocketClient class. You can check if you are currently testing in the Android Emulator like this

if ("google_sdk".equals( Build.PRODUCT )) {
  // ... disable IPv6
}

Everything found in this repo is licensed under an MIT license. See the LICENSE file for specifics.