socket.io-java-client is a simple implementation of socket.io for Java.

It uses Weberknecht as transport backend, but it's easy to write your own transport. See description below. An XHR-Transport is included, too. But it's not functional in its current state.

The API is inspired by java-socket.io.client but as the license of this project was unclear and it had some nasty bugs, I decided to write socket.io-java-client from the scratch.

Features:

• transparent reconnecting - The API cares about re-establishing the connection to the server when the transport is interrupted.
• easy to use API - implement an interface, instantiate a class - you're done.
• output buffer - send data while the transport is still connecting. No problem, socket.io-java-client handles that.
• meaningful exceptions - If something goes wrong, SocketIO tries to throw meaningful exceptions with hints for fixing.

Status: Connecting with Websocket is production ready. XHR is not usable at the moment but I'm working on it.

• with git

   git clone git://github.com/Gottox/socket.io-java-client.git
  

• with mercurial

   hg clone https://bitbucket.org/Gottox/socket.io-java-client 
  

Both repositories are synchronized and up to date.

to build a jar-file:

cd $PATH_TO_SOCKETIO_JAVA
ant jar
ls jar/socketio.jar

You'll find the socket.io-jar in jar/socketio.jar

Using socket.io-java-client is quite simple. But lets see:

	// Initialise a socket:
	SocketIO socket = new IOSocket("http://127.0.0.1:3001");
	socket.connect(new IOCallback() {
			@Override
			public void onMessage(JSONObject json, IOAcknowledge ack) {
				System.out.println("We received a message: " + json.toString(2));
			}
			
			@Override
			public void onMessage(String data, IOAcknowleged ack) {
				System.out.println("We received a message:" + data);
			}
			
			@Override
			public void onError(SocketIOException socketIOException) {
				System.out.println("Something went wrong. Lets exit");
				System.exit(0);
			}
			
			@Override
			public void onDisconnect() {
				System.out.println("Disconnected");
				System.exit(0);
			}
			
			@Override
			public void onConnect() {
				System.out.println("Connected");
			}
			
			@Override
			public void on(String event, IOAcknowledge ack, Object... args) {
				try {
					ack.ack("Roger that!");
					socket.emit("answer", new JSONObject().put("msg", "Hello again Socket.io!"));
				} catch (JSONException e) {
					e.printStackTrace();
				}
			}
		});
	
	// This will be cached until the server is connected.
	socket.emit("hello", new JSONObject().put("msg", "Hello Socket.io! :D"));

For further informations, read the Javadoc.

• Class SocketIO
• Interface IOCallback

Read this if you want to investigate in socket.io-java-client.

SocketIO is the API frontend. You can use this to connect to multiple hosts. If an IOConnection object exists for a certian host, it will be reused as the socket.io specs state.

Javadoc

This class is used to hold a connection to a socket.io server. It handles calling callback functions of the corresponding SocketIO and reconnecting if the connection is shut down ungracefully.

Javadoc

This interface describes a connection to a host. The implementation can be fairly minimal, as IOConnection does most of the work for you. Reconnecting, errorhandling, etc... is handled by IOConnection.

Javadoc

An example can be found in WebsocketTransport.java or XhrTransport.java Create a class implementing the IOTransport interface.

This constant should contain the name of the transport.

Called by IOConnector to create a new Instance of the transport. The URL is the one you should connect to. Here you can rewrite the url if needed, i.e. WebsocketTransport rewrites the incoming "http://" address to "ws://"

Called by IOConnection. Here you should set up the connection.

Called by IOConnection. This should shut down the connection. I'm currently not sure if this function is called multiple times. So make sure, it doesn't crash if it's called more than once.

Called by IOConnection. This call request you to send data to the server.

If you can send more than one message at a time, return true. If not return false.

Basicly the same as send() but for multiple messages at a time. This is only called when canSendBulk returns true.

After this call, the transport should not call any methods of IOConnection. It must not disconnect from the server. This is the case when we're forcing a reconnect. If we disconnect gracefully from the server, it will terminate our session.

Ok, now we know when our functions are called. But how do we tell socket.io-java-client to process messages we get? The provided IOConnection does the trick.

Call this method when the connection is established an the socket is ready to send and receive data.

Call this method when the connection is shot down. IOConnection will care about reconnecting, if it's feasibility.

Call this method when the connection is experiencing an error. IOConnection will take care about reconnecting or throwing an error to the callbacks. Whatever makes more sense ;)

This should be called as soon as the transport has received data. IOConnection will take care about parsing the information and calling the callbacks of the sockets.

Now IOConnection needs to instantiate the transpost look at the sourcecode of IOConnection and search for the connectTransport() method. It's part of the ConnectThread inner class.

add a new else if branch to the section. I.e.:

	...
	else if (protocols.contains(MyTransport.TRANSPORT_NAME))
		transport = MyTransport.create(url, IOConnection.this);
	...

This Library was designed with portability in mind.

• Android is fully supported.
• JRE is fully supported.
• GWT does not work at the moment, but a port would be possible.
• JavaME untested.
• ... is there anything else out there?

There comes a JUnit test suite with socket.io-java-client. Currently it's tested with Eclipse.

You need node installed in PATH.

• open the project with eclipse
• open tests/io.socket/AllTests.java
• run it as JUnit4 test.

• Socket.io needs more unit-tests.
• XhrTransport needs to pass all tests.
• If websockets are failing (due to proxy servers e.g.), use XHR automaticly instead.

This library is distributed under MIT Licence.