{"id":19358,"date":"2013-12-03T19:00:44","date_gmt":"2013-12-03T17:00:44","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=19358"},"modified":"2013-12-02T22:58:20","modified_gmt":"2013-12-02T20:58:20","slug":"java-websockets-jsr-356-on-jetty-9-1","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2013\/12\/java-websockets-jsr-356-on-jetty-9-1.html","title":{"rendered":"Java WebSockets (JSR-356) on Jetty 9.1"},"content":{"rendered":"

Jetty 9.1<\/a> is finally released, bringing Java WebSockets (JSR-356)<\/a> to non-EE environments. It’s awesome news and today’s post will be about using this great new API along with Spring Framework<\/a>.<\/p>\n

JSR-356<\/a> defines concise, annotation-based model to allow modern Java web applications easily create bidirectional communication channels using WebSockets API<\/a>. It covers not only server-side, but client-side as well, making this API really simple to use everywhere.<\/p>\n

Let’s get started! Our goal would be to build a WebSockets<\/a> server which accepts messages from the clients and broadcasts them to all other clients currently connected. To begin with, let’s define the message format, which server and client will be exchanging, as this simple Message<\/b> class. We can limit ourselves to something like a String<\/b>, but I would like to introduce to you the power of another new API – Java API for JSON Processing (JSR-353)<\/a>.<\/p>\n

package com.example.services;\r\n\r\npublic class Message {\r\n    private String username;\r\n    private String message;\r\n\r\n    public Message() {\r\n    }\r\n\r\n    public Message( final String username, final String message ) {\r\n        this.username = username;\r\n        this.message = message;\r\n    }\r\n\r\n    public String getMessage() {\r\n        return message;\r\n    }\r\n\r\n    public String getUsername() {\r\n        return username;\r\n    }\r\n\r\n    public void setMessage( final String message ) {\r\n        this.message = message;\r\n    }\r\n\r\n    public void setUsername( final String username ) {\r\n        this.username = username;\r\n    }\r\n}<\/pre>\n
To separate the declarations related to the server and the client, JSR-356<\/a> defines two basic annotations: @ServerEndpoint<\/b> and @ClientEndpoit<\/b> respectively. Our client endpoint, let’s call it BroadcastClientEndpoint<\/b>, will simply listen for messages server sends:<\/p>\n
package com.example.services;\r\n\r\nimport java.io.IOException;\r\nimport java.util.logging.Logger;\r\n\r\nimport javax.websocket.ClientEndpoint;\r\nimport javax.websocket.EncodeException;\r\nimport javax.websocket.OnMessage;\r\nimport javax.websocket.OnOpen;\r\nimport javax.websocket.Session;\r\n\r\n@ClientEndpoint\r\npublic class BroadcastClientEndpoint {\r\n    private static final Logger log = Logger.getLogger( \r\n        BroadcastClientEndpoint.class.getName() );\r\n\r\n    @OnOpen\r\n    public void onOpen( final Session session ) throws IOException, EncodeException  {\r\n        session.getBasicRemote().sendObject( new Message( \"Client\", \"Hello!\" ) );\r\n    }\r\n\r\n    @OnMessage\r\n    public void onMessage( final Message message ) {\r\n        log.info( String.format( \"Received message '%s' from '%s'\",\r\n            message.getMessage(), message.getUsername() ) );\r\n    }\r\n}<\/pre>\n
That’s literally it! Very clean, self-explanatory piece of code: @OnOpen<\/b> is being called when client got connected to the server and @OnMessage<\/b> is being called every time server sends a message to the client. Yes, it’s very simple but there is a caveat: JSR-356<\/a> implementation can handle any simple objects but not the complex ones like Message<\/b> is. To manage that, JSR-356<\/a> introduces concept of encoders<\/b> and decoders<\/b>.<\/p>\n
We all love JSON<\/a>, so why don’t we define our own JSON<\/a> encoder and decoder? It’s an easy task which Java API for JSON Processing (JSR-353)<\/a> can handle for us. To create an encoder, you only need to implement Encoder.Text< Message ><\/b> and basically serialize your object to some string, in our case to JSON<\/a> string, using JsonObjectBuilder<\/a>.<\/p>\n
package com.example.services;\r\n\r\nimport javax.json.Json;\r\nimport javax.json.JsonReaderFactory;\r\nimport javax.websocket.EncodeException;\r\nimport javax.websocket.Encoder;\r\nimport javax.websocket.EndpointConfig;\r\n\r\npublic class Message {\r\n    public static class MessageEncoder implements Encoder.Text< Message > {\r\n        @Override\r\n        public void init( final EndpointConfig config ) {\r\n        }\r\n\r\n        @Override\r\n        public String encode( final Message message ) throws EncodeException {\r\n            return Json.createObjectBuilder()\r\n                .add( \"username\", message.getUsername() )\r\n                .add( \"message\", message.getMessage() )\r\n                .build()\r\n                .toString();\r\n        }\r\n\r\n        @Override\r\n        public void destroy() {\r\n        }\r\n    }\r\n}<\/pre>\n
For decoder part, everything looks very similar, we have to implement Decoder.Text< Message ><\/b> and deserialize our object from string, this time using JsonReader<\/a>.<\/p>\n
package com.example.services;\r\n\r\nimport javax.json.JsonObject;\r\nimport javax.json.JsonReader;\r\nimport javax.json.JsonReaderFactory;\r\nimport javax.websocket.DecodeException;\r\nimport javax.websocket.Decoder;\r\n\r\npublic class Message {\r\n    public static class MessageDecoder implements Decoder.Text< Message > {\r\n        private JsonReaderFactory factory = Json.createReaderFactory( Collections.< String, Object >emptyMap() );\r\n\r\n        @Override\r\n        public void init( final EndpointConfig config ) {\r\n        }\r\n\r\n        @Override\r\n        public Message decode( final String str ) throws DecodeException {\r\n            final Message message = new Message();\r\n\r\n            try( final JsonReader reader = factory.createReader( new StringReader( str ) ) ) {\r\n                final JsonObject json = reader.readObject();\r\n                message.setUsername( json.getString( \"username\" ) );\r\n                message.setMessage( json.getString( \"message\" ) );\r\n            }\r\n\r\n            return message;\r\n        }\r\n\r\n        @Override\r\n        public boolean willDecode( final String str ) {\r\n            return true;\r\n        }\r\n\r\n        @Override\r\n        public void destroy() {\r\n        }\r\n    }\r\n}<\/pre>\n
And as a final step, we need to tell the client (and the server, they share same decoders and encoders) that we have encoder and decoder for our messages. The easiest thing to do that is just by declaring them as part of @ServerEndpoint<\/b> and @ClientEndpoit<\/b> annotations.
 
<\/div> <\/div><\/p>\n
import com.example.services.Message.MessageDecoder;\r\nimport com.example.services.Message.MessageEncoder;\r\n\r\n@ClientEndpoint( encoders = { MessageEncoder.class }, decoders = { MessageDecoder.class } )\r\npublic class BroadcastClientEndpoint {\r\n}<\/pre>\n
To make client’s example complete, we need some way to connect to the server using BroadcastClientEndpoint<\/b> and basically exchange messages. The ClientStarter<\/b> class finalizes the picture:<\/p>\n
package com.example.ws;\r\n\r\nimport java.net.URI;\r\nimport java.util.UUID;\r\n\r\nimport javax.websocket.ContainerProvider;\r\nimport javax.websocket.Session;\r\nimport javax.websocket.WebSocketContainer;\r\n\r\nimport org.eclipse.jetty.websocket.jsr356.ClientContainer;\r\n\r\nimport com.example.services.BroadcastClientEndpoint;\r\nimport com.example.services.Message;\r\n\r\npublic class ClientStarter {\r\n    public static void main( final String[] args ) throws Exception {\r\n        final String client = UUID.randomUUID().toString().substring( 0, 8 );\r\n\r\n        final WebSocketContainer container = ContainerProvider.getWebSocketContainer();    \r\n        final String uri = \"ws:\/\/localhost:8080\/broadcast\";  \r\n\r\n        try( Session session = container.connectToServer( BroadcastClientEndpoint.class, URI.create( uri ) ) ) {\r\n            for( int i = 1; i <= 10; ++i ) {\r\n                session.getBasicRemote().sendObject( new Message( client, \"Message #\" + i ) );\r\n                Thread.sleep( 1000 );\r\n            }\r\n        }\r\n\r\n        \/\/ Application doesn't exit if container's threads are still running\r\n        ( ( ClientContainer )container ).stop();\r\n    }\r\n}<\/pre>\n
Just couple of comments what this code does: we are connecting to WebSockets<\/a> endpoint at ws:\/\/localhost:8080\/broadcast<\/b>, randomly picking some client<\/b> name (from UUID) and generating 10 messages, every with 1 second delay (just to be sure we have time to receive them all back).<\/p>\n
Server part doesn’t look very different and at this point could be understood without any additional comments (except may be the fact that server just broadcasts every message it receives to all connected clients). Important to mention here: new instance of the server endpoint is created every time new client connects to it (that’s why peers<\/b> collection is static), it’s a default behavior and could be easily changed.<\/p>\n
package com.example.services;\r\n\r\nimport java.io.IOException;\r\nimport java.util.Collections;\r\nimport java.util.HashSet;\r\nimport java.util.Set;\r\n\r\nimport javax.websocket.EncodeException;\r\nimport javax.websocket.OnClose;\r\nimport javax.websocket.OnMessage;\r\nimport javax.websocket.OnOpen;\r\nimport javax.websocket.Session;\r\nimport javax.websocket.server.ServerEndpoint;\r\n\r\nimport com.example.services.Message.MessageDecoder;\r\nimport com.example.services.Message.MessageEncoder;\r\n\r\n@ServerEndpoint( \r\n    value = \"\/broadcast\", \r\n    encoders = { MessageEncoder.class }, \r\n    decoders = { MessageDecoder.class } \r\n) \r\npublic class BroadcastServerEndpoint {\r\n    private static final Set< Session > sessions = \r\n        Collections.synchronizedSet( new HashSet< Session >() ); \r\n\r\n    @OnOpen\r\n    public void onOpen( final Session session ) {\r\n        sessions.add( session );\r\n    }\r\n\r\n    @OnClose\r\n    public void onClose( final Session session ) {\r\n        sessions.remove( session );\r\n    }\r\n\r\n    @OnMessage\r\n    public void onMessage( final Message message, final Session client ) \r\n            throws IOException, EncodeException {\r\n        for( final Session session: sessions ) {\r\n            session.getBasicRemote().sendObject( message );\r\n        }\r\n    }\r\n}<\/pre>\n
In order this endpoint to be available for connection, we should start the WebSockets<\/a> container and register this endpoint inside it. As always, Jetty 9.1<\/a> is runnable in embedded mode effortlessly:<\/p>\n
package com.example.ws;\r\n\r\nimport org.eclipse.jetty.server.Server;\r\nimport org.eclipse.jetty.servlet.DefaultServlet;\r\nimport org.eclipse.jetty.servlet.ServletContextHandler;\r\nimport org.eclipse.jetty.servlet.ServletHolder;\r\nimport org.eclipse.jetty.websocket.jsr356.server.deploy.WebSocketServerContainerInitializer;\r\nimport org.springframework.web.context.ContextLoaderListener;\r\nimport org.springframework.web.context.support.AnnotationConfigWebApplicationContext;\r\n\r\nimport com.example.config.AppConfig;\r\n\r\npublic class ServerStarter  {\r\n    public static void main( String[] args ) throws Exception {\r\n        Server server = new Server( 8080 );\r\n\r\n        \/\/ Create the 'root' Spring application context\r\n        final ServletHolder servletHolder = new ServletHolder( new DefaultServlet() );\r\n        final ServletContextHandler context = new ServletContextHandler();\r\n\r\n        context.setContextPath( \"\/\" );\r\n        context.addServlet( servletHolder, \"\/*\" );\r\n        context.addEventListener( new ContextLoaderListener() );   \r\n        context.setInitParameter( \"contextClass\", AnnotationConfigWebApplicationContext.class.getName() );\r\n        context.setInitParameter( \"contextConfigLocation\", AppConfig.class.getName() );\r\n\r\n        server.setHandler( context );\r\n        WebSocketServerContainerInitializer.configureContext( context );        \r\n\r\n        server.start();\r\n        server.join(); \r\n    }\r\n}<\/pre>\n
The most important part of the snippet above is WebSocketServerContainerInitializer.configureContext<\/b>: it’s actually creates the instance of WebSockets<\/a> container. Because we haven’t added any endpoints yet, the container basically sits here and does nothing. Spring Framework<\/a> and AppConfig<\/b> configuration class will do this last wiring for us.<\/p>\n
package com.example.config;\r\n\r\nimport javax.annotation.PostConstruct;\r\nimport javax.inject.Inject;\r\nimport javax.websocket.DeploymentException;\r\nimport javax.websocket.server.ServerContainer;\r\nimport javax.websocket.server.ServerEndpoint;\r\nimport javax.websocket.server.ServerEndpointConfig;\r\n\r\nimport org.eclipse.jetty.websocket.jsr356.server.AnnotatedServerEndpointConfig;\r\nimport org.springframework.context.annotation.Bean;\r\nimport org.springframework.context.annotation.Configuration;\r\nimport org.springframework.web.context.WebApplicationContext;\r\n\r\nimport com.example.services.BroadcastServerEndpoint;\r\n\r\n@Configuration\r\npublic class AppConfig  {\r\n    @Inject private WebApplicationContext context;\r\n    private ServerContainer container;\r\n\r\n    public class SpringServerEndpointConfigurator extends ServerEndpointConfig.Configurator {\r\n        @Override\r\n        public < T > T getEndpointInstance( Class< T > endpointClass ) \r\n                throws InstantiationException {\r\n            return context.getAutowireCapableBeanFactory().createBean( endpointClass );   \r\n        }\r\n    }\r\n\r\n    @Bean\r\n    public ServerEndpointConfig.Configurator configurator() {\r\n        return new SpringServerEndpointConfigurator();\r\n    }\r\n\r\n    @PostConstruct\r\n    public void init() throws DeploymentException {\r\n        container = ( ServerContainer )context.getServletContext().\r\n            getAttribute( javax.websocket.server.ServerContainer.class.getName() );\r\n\r\n        container.addEndpoint( \r\n            new AnnotatedServerEndpointConfig( \r\n                BroadcastServerEndpoint.class, \r\n                BroadcastServerEndpoint.class.getAnnotation( ServerEndpoint.class )  \r\n            ) {\r\n                @Override\r\n                public Configurator getConfigurator() {\r\n                    return configurator();\r\n                }\r\n            }\r\n        );\r\n    }  \r\n}<\/pre>\n
As we mentioned earlier, by default container will create new instance of server endpoint every time new client connects, and it does so by calling constructor, in our case BroadcastServerEndpoint.class.newInstance()<\/b>. It might be a desired behavior but because we are using Spring Framework<\/a> and dependency injection, such new objects are basically unmanaged beans. Thanks to very well-thought (in my opinion) design of JSR-356<\/a>, it’s actually quite easy to provide your own way of creating endpoint instances by implementing ServerEndpointConfig.Configurator<\/b>. The SpringServerEndpointConfigurator<\/b> is an example of such implementation: it’s creates new managed bean every time new endpoint instance is being asked (if you want single instance, you can create singleton of the endpoint as a bean in AppConfig<\/b> and return it all the time).<\/p>\n
The way we retrieve the WebSockets<\/a> container is Jetty<\/a>-specific: from the attribute of the context with name “javax.websocket.server.ServerContainer”<\/b> (it probably might change in the future). Once container is there, we are just adding new (managed!) endpoint by providing our own ServerEndpointConfig<\/b> (based on AnnotatedServerEndpointConfig<\/b> which Jetty<\/a> kindly provides already).<\/p>\n
To build and run our server and clients, we need just do that:<\/p>\n
mvn clean package\r\njava -jar target\\jetty-web-sockets-jsr356-0.0.1-SNAPSHOT-server.jar \/\/ run server\r\njava -jar target\/jetty-web-sockets-jsr356-0.0.1-SNAPSHOT-client.jar \/\/ run yet another client<\/pre>\n
As an example, by running server and couple of clients (I run 4 of them, ‘392f68ef<\/b>‘, ‘8e3a869d<\/b>‘, ‘ca3a06d0<\/b>‘, ‘6cb82119<\/b>‘) you might see by the output in the console that each client receives all the messages from all other clients (including its own messages):<\/p>\n
Nov 29, 2013 9:21:29 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Hello!' from 'Client'\r\nNov 29, 2013 9:21:29 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #1' from '392f68ef'\r\nNov 29, 2013 9:21:29 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #2' from '8e3a869d'\r\nNov 29, 2013 9:21:29 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #7' from 'ca3a06d0'\r\nNov 29, 2013 9:21:30 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #4' from '6cb82119'\r\nNov 29, 2013 9:21:30 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #2' from '392f68ef'\r\nNov 29, 2013 9:21:30 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #3' from '8e3a869d'\r\nNov 29, 2013 9:21:30 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #8' from 'ca3a06d0'\r\nNov 29, 2013 9:21:31 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #5' from '6cb82119'\r\nNov 29, 2013 9:21:31 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #3' from '392f68ef'\r\nNov 29, 2013 9:21:31 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #4' from '8e3a869d'\r\nNov 29, 2013 9:21:31 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #9' from 'ca3a06d0'\r\nNov 29, 2013 9:21:32 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #6' from '6cb82119'\r\nNov 29, 2013 9:21:32 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #4' from '392f68ef'\r\nNov 29, 2013 9:21:32 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #5' from '8e3a869d'\r\nNov 29, 2013 9:21:32 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #10' from 'ca3a06d0'\r\nNov 29, 2013 9:21:33 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #7' from '6cb82119'\r\nNov 29, 2013 9:21:33 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #5' from '392f68ef'\r\nNov 29, 2013 9:21:33 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #6' from '8e3a869d'\r\nNov 29, 2013 9:21:34 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #8' from '6cb82119'\r\nNov 29, 2013 9:21:34 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #6' from '392f68ef'\r\nNov 29, 2013 9:21:34 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #7' from '8e3a869d'\r\nNov 29, 2013 9:21:35 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #9' from '6cb82119'\r\nNov 29, 2013 9:21:35 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #7' from '392f68ef'\r\nNov 29, 2013 9:21:35 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #8' from '8e3a869d'\r\nNov 29, 2013 9:21:36 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #10' from '6cb82119'\r\nNov 29, 2013 9:21:36 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #8' from '392f68ef'\r\nNov 29, 2013 9:21:36 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #9' from '8e3a869d'\r\nNov 29, 2013 9:21:37 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #9' from '392f68ef'\r\nNov 29, 2013 9:21:37 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #10' from '8e3a869d'\r\nNov 29, 2013 9:21:38 PM com.example.services.BroadcastClientEndpoint onMessage\r\nINFO: Received message 'Message #10' from '392f68ef'\r\n2013-11-29 21:21:39.260:INFO:oejwc.WebSocketClient:main: Stopped org.eclipse.jetty.websocket.client.WebSocketClient@3af5f6dc<\/pre>\n
Awesome! I hope this introductory blog post shows how easy it became to use modern web communication protocols in Java, thanks to Java WebSockets (JSR-356)<\/a>, Java API for JSON Processing (JSR-353)<\/a> and great projects such as Jetty 9.1<\/a>!<\/p>\n