#Netty-socketio Overview

This project is an open-source Java implementation of Socket.IO server. Based on Netty server framework.

Checkout Demo project

Licensed under the Apache License 2.0.

Features

• Supports 0.7...0.9.16 (netty-socketio 1.6.6) and 1.0+ (netty-socketio latest version) version of Socket.IO-client
• Supports xhr-polling transport
• Supports websocket transport
• Supports namespaces and rooms
• Supports ack (acknowledgment of received data)
• Supports SSL
• Supports client store (Memory, Redisson, Hazelcast)
• Supports distributed broadcast across netty-socketio nodes (Redisson, Hazelcast)
• Supports OSGi
• Supports Spring
• Lock-free and thread-safe implementation
• Declarative handler configuration via annotations

Performance

Customer feedback in 2012:
CentOS, 1 CPU, 4GB RAM runned on VM: CPU 10%, Memory 15%
6000 xhr-long polling sessions or 15000 websockets sessions
4000 messages per second

Customer feedback in 2014:
"To stress test the solution we run 30 000 simultaneous websocket clients and managed to peak at total of about 140 000 messages per second with less than 1 second average delay." (c) Viktor Endersz - Kambi Sports Solutions

Projects using netty-socketio

AVOS Cloud: avoscloud.com
Bingo Crack: bingocrack.com
Kambi Sports Solutions: kambi.com
ARSnova: arsnova.eu
Zipwhip: zipwhip.com

Recent Releases

####Please Note: trunk is current development branch.

####26-Mar-2015 - version 1.6.7 released
Improvement - useStrictOrdering param added for websocket packets strict ordering
Improvement - FAIL_ON_EMPTY_BEANS = false option setted in json decoder

####18-Feb-2015 - version 1.7.7 released
Improvement - no need to add jackson lib if you use own JsonSupport impl
Fixed - SocketIO client 1.3.x support
Fixed - Charset encoding handling (thanks to alim-akbashev)

####17-Jan-2015 - version 1.7.6 released
Improvement - SocketIONamespace.getName() added
Fixed - WebSocket frames aggregation
Fixed - WebSocket buffer release
Fixed - Unexpected end-of-input in VALUE_STRING error
Fixed - Access-Control-Allow-Credentials is TRUE for requests with origin header

####05-Dec-2014 - version 1.7.5 released
Feature - Configuration.sslProtocol param added
Fixed - BinaryEvent ack handling
Fixed - BinaryEvent non b64 encoding/decoding
Fixed - buffer leak during packet encoding

####15-Nov-2014 - version 1.7.4 released
Fixed - packet encoding
Fixed - BinaryEvent encoding/decoding
Fixed - unchallenged connections handling

####29-Sep-2014 - version 1.6.6 released
Feature - origin setting added
Feature - crossDomainPolicy setting added
Feature - SocketIOServer.startAsync method added

####24-Sep-2014 - version 1.7.3 released
Feature - Epoll support
Improvement - BinaryEvent support
Fixed - SocketIOClient disconnect handling
Fixed - broadcast callback
Fixed - NPE then no transport defined during auth
Fixed - ping timeout for polling transport
Fixed - buffer leak in PacketEncoder

####22-Aug-2014 - version 1.7.2 released
Fixed - wrong outgoing message encoding using websocket transport
Fixed - NPE in websocket transport
Fixed - multiple packet decoding in polling transport
Fixed - buffer leak

####07-Jul-2014 - version 1.7.1 released
Feature - ability to set custom Access-Control-Allow-Origin via Configuration.origin
Fixed - connection via CLI socket.io-client

####28-Jun-2014 - version 1.7.0 released Feature - Socket.IO 1.0 protocol support. Thanks to the new protocol decoding/encoding has speedup
Dropped - SocketIOClient.sendMessage, SocketIOClient.sendJsonObject methods and corresponding listeners
Dropped - Flashsocket transport support
Dropped - protocol version 0.7 ... 0.9.16

####13-May-2014 - version 1.6.5 released Improvement - single packet encoding optimized, used mostly in WebSocket transport. Encoding time reduced up to 40% (thanks to Viktor Endersz)
Improvement - rooms handling optimized
Improvement - ExceptionListener.exceptionCaught method added
Breaking api change - Configuration.autoAck replaced with ackMode
Feature - trustStore setting added
Feature - maxFramePayloadLength setting added
Feature - getAllClients and getClient methods added to SocketIONamespace
Fixed - SocketIOServer.getAllClients returns wrong clients amount

####25-Mar-2014 - version 1.6.4 released Fixed - message release problem
Fixed - problem with exception listener configuration redefinition
Breaking api change - DataListener.onData now throws Exception
Improvement - data parameter added to exception listener
Improvement - ability to setup socket configuration
Improvement - Configuration.autoAck parameter added

####06-Mar-2014 - version 1.6.3 released Fixed - AckCallback handling during client disconnect
Fixed - unauthorized handshake HTTP code changed to 401
Breaking api change - Configuration.heartbeatThreadPoolSize setting removed
Feature - annotated Spring beans support via SpringAnnotationScanner
Feature - common exception listener
Improvement - ScheduledExecutorService replaced with HashedWheelTimer

####08-Feb-2014 - version 1.6.2 released Fixed - wrong namespace client disconnect handling
Fixed - exception in onConnect/onDisconnect/isAuthorized methods leads to server hang
Breaking api change - SocketIOClient.sendEvent methods signature changed
Improvement - multi type events support via MultiTypeEventListener and OnEvent annotation
Improvement - multi type events ack support via MultiTypeAckCallback
Improvement - SocketIOClient.getHandshakeData method added
Improvement - Jedis replaced with Redisson

####14-Jan-2014 - version 1.6.1 released Fixed - JDK 1.6+ compatibility
Feature - authorization support

####19-Dec-2013 - version 1.6.0 released Fixed - XHR-pooling transport regression
Fixed - Websocket transport regression
Fixed - namespace NPE in PacketHandler
Fixed - executors shutdown during server stop
Feature - client store (Memory, Redis, Hazelcast) support
Feature - distributed broadcast across netty-socketio nodes (Redis, Hazelcast) support
Feature - OSGi support (thanks to rdevera)
Improvement - XHR-pooling optimization
Improvement - SocketIOClient.getAllRooms method added

####07-Dec-2013 - version 1.5.4 released Fixed - flash policy "request leak" after page reload (thanks to ntrp)
Fixed - websocket swf loading (thanks to ntrp)
Fixed - wrong urls causes a potential DDoS
Fixed - Event.class package visibility changed to avoid direct usage
Improvement - Simplified Jackson modules registration

####24-Oct-2013 - version 1.5.2 released Fixed - NPE during shutdown
Improvement - isEmpty method added to Namespace

####13-Oct-2013 - version 1.5.1 released Fixed - wrong ack timeout callback invocation
Fixed - bigdecimal serialization for JSON
Fixed - infinity loop during packet handling exception
Fixed - 'client not found' handling

####27-Aug-2013 - version 1.5.0 released Improvement - encoding buffers allocation optimization.
Improvement - encoding buffers now pooled in memory to reduce GC pressure (netty 4.x feature).

####03-Aug-2013 - version 1.0.1 released Fixed - error on unknown property during deserialization.
Fixed - memory leak in long polling transport.
Improvement - logging error info with inbound data.

####07-Jun-2013 - version 1.0.0 released First stable release.

Maven

Include the following to your dependency list:

<dependency>
 <groupId>com.corundumstudio.socketio</groupId>
 <artifactId>netty-socketio</artifactId>
 <version>1.7.6</version>
</dependency>

Usage example

##Server

Base configuration. More details about Configuration object is here.

    Configuration config = new Configuration();
    config.setHostname("localhost");
    config.setPort(81);

    SocketIOServer server = new SocketIOServer(config);

Programmatic handlers binding:

    server.addMessageListener(new DataListener<String>() {
        @Override
        public void onData(SocketIOClient client, String message, AckRequest ackRequest) {
            ...
        }
    });

    server.addEventListener("someevent", SomeClass.class, new DataListener<SomeClass>() {
        @Override
        public void onData(SocketIOClient client, Object data, AckRequest ackRequest) {
            ...
        }
    });

    server.addConnectListener(new ConnectListener() {
        @Override
        public void onConnect(SocketIOClient client) {
            ...
        }
    });

    server.addDisconnectListener(new DisconnectListener() {
        @Override
        public void onDisconnect(SocketIOClient client) {
            ...
        }
    });


    // Don't forget to include type field on javascript side,
    // it named '@class' by default and should equals to full class name.
    //
    // TIP: you can customize type field name via Configuration.jsonTypeFieldName property.

    server.addJsonObjectListener(SomeClass.class, new DataListener<SomeClass>() {
        @Override
        public void onData(SocketIOClient client, SomeClass data, AckRequest ackRequest) {

            ...

            // send object to socket.io client
            SampleObject obj = new SampleObject();
            client.sendJsonObject(obj);
        }
    });

Declarative handlers binding. Handlers could be bound via annotations on any object:

    pubic class SomeBusinessService {
    
         ...
         // some stuff code
         ...

         // SocketIOClient, AckRequest and Data could be ommited
         @OnEvent('someevent')
         public void onSomeEventHandler(SocketIOClient client, SomeClass data, AckRequest ackRequest) {
             ...
         }
         
         @OnConnect
         public void onConnectHandler(SocketIOClient client) {
             ...
         }

         @OnDisconnect
         public void onDisconnectHandler(SocketIOClient client) {
             ...
         }

         // only data object is required in arguments, 
         // SocketIOClient and AckRequest could be ommited
         @OnJsonObject
         public void onSomeEventHandler(SocketIOClient client, SomeClass data, AckRequest ackRequest) {
             ...
         }

         // only data object is required in arguments, 
         // SocketIOClient and AckRequest could be ommited
         @OnMessage
         public void onSomeEventHandler(SocketIOClient client, String data, AckRequest ackRequest) {
             ...
         }

    }
    
    SomeBusinessService someService = new SomeBusinessService();
    server.addListeners(someService);


    server.start();
    
    ...
    
    server.stop();

##Client

    <script type="text/javascript" src="socket.io.js" charset="utf-8"></script>

    <script type="text/javascript">

           var socket = io.connect('http://localhost:81', {
             'reconnection delay' : 2000,
             'force new connection' : true
           });

           socket.on('message', function(data) {
                // here is your handler on messages from server
           });

       socket.on('connect', function() {
                // connection established, now we can send an objects


                // send json-object to server
                // '@class' property should be defined and should 
                // equals to full class name.
                var obj = { '@class' : 'com.sample.SomeClass',
                             ...
                          };
                socket.json.send(obj);



                // send event-object to server
                // '@class' property is NOT necessary in this case
                var event = { 
                             ...
                          };
                socket.emit('someevent', event);

       });

    </script>