Java WebSockets

https://github.com/TooTallNate/Java-WebSocket

Java WebSockets

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

Hybi 17

Hybi 10

Hixie 76

Hixie 75

Here some more details about protocol versions/drafts.

Build

You can build using Ant or Maven but there is nothing against just putting the source path

src/main/java

on your applications buildpath.

Ant

ant

will create the javadoc of this library at

doc/

and build the library itself:

dest/java_websocket.jar

The anttargets are:

compile

,

jar

,

doc

and

clean

Maven

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

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

Running the Examples

Note: If you're on Windows, then replace the

:

(colon) in the classpath in the commands below with a

;

(semicolon).

After you build the library you can start the chat server (a

WebSocketServer

subclass):

java -cp build/examples:dist/java_websocket.jar ChatServer

Now that the server is started, you need to connect some clients. Run the Java chat client (a

WebSocketClient

subclass):

java -cp build/examples:dist/java_websocket.jar ChatClient

The chat client is a simple Swing GUI application that allows you to send messages to all other connected clients, and receive messages from others in a text box.

In the example folder is also a simple HTML file chat client

chat.html

, which can be opened by any browser. If the browser natively supports the WebSocket API, then it's implementation will be used, otherwise it will fall back to a Flash-based WebSocket Implementation.

Writing your own WebSocket Server

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 yoursubclass to add purpose.

Writing your own WebSocket Client

The

org.java_websocket.client.WebSocketClient

abstract class can connect to valid WebSocket servers. The constructor expects a valid

ws://

URI to connect to. Importantevents

onOpen

,

onClose

,

onMessage

and

onIOError

get fired throughout the life of the WebSocketClient, and must be implemented in your subclass.

WSS Support

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 multible connections to the same wss server if the server uses a different port than the default port(443).

If you wantto 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.

Minimum Required JDK

Java-WebSocket

is known to work with:

Java 1.5 (aka SE 6)

Android 1.6 (API 4)

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

Testing in Android Emulator

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
}

Getting Support

If you are looking for help using

Java-WebSocket

you might wantto check out the #java-websocket IRC room on the FreeNode IRC network.

License

Everything found in this repo is licensed under an MIT license. See the

LICENSE

file for specifics.