Tyrus 1.0 User Guide

First, to use the Java API for WebSocket in your project you need to depend on the following artifact:

<dependency>
    <groupId>javax.websocket</groupId>
    <artifactId>javax.websocket-api</artifactId>
    <version>1.0</version>
</dependency>

@ServerEndpoint(value = "/echo")
public class EchoEndpointAnnotated {
    @OnMessage
    public String onMessage(String message, Session session) {
        return message;
    }
}

public class DocClient {
    private CountDownLatch messageLatch;
    private static final String SENT_MESSAGE = "Hello World";

    public static void main(String [] args){
        try {
            messageLatch = new CountDownLatch(1);

            final ClientEndpointConfig cec = ClientEndpointConfig.Builder.create().build();

            ClientManager client = ClientManager.createClient();
            client.connectToServer(new Endpoint() {

                @Override
                public void onOpen(Session session, EndpointConfig config) {
                    try {
                        session.addMessageHandler(new MessageHandler.Whole<String>() {

                            @Override
                            public void onMessage(String message) {
                                System.out.println("Received message: "+message);
                                messageLatch.countDown();
                            }
                        });
                        session.getBasicRemote().sendText(SENT_MESSAGE);
                    } catch (IOException e) {
                        e.printStackTrace();
                    }
                }
            }, cec, new URI("ws://localhost:8025/websockets/echo"));
            messageLatch.await(100, TimeUnit.SECONDS);
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

public class EchoEndpointProgrammatic extends Endpoint {
    @Override
    public void onOpen(final Session session, EndpointConfig config) {
        session.addMessageHandler(new MessageHandler.Whole<String>() {
            @Override
            public void onMessage(String message) {
                try {
                    session.getBasicRemote().sendText(message);
                } catch (IOException e) {
                    e.printStackTrace();
                }
            }
        });
    }
}

To see how both annotated and programmatic endpoints may be deployed please check the section Deployment. In short: you need to put the server endpoint classes into WAR, deploy on server and the endpoints will be scanned by server and deployed.

<dependency>
    <groupId>org.glassfish.tyrus</groupId>
    <artifactId>tyrus-server</artifactId>
    <version>1.0</version>
</dependency>

<dependency>
    <groupId>org.glassfish.tyrus</groupId>
    <artifactId>tyrus-client</artifactId>
    <version>1.0</version>
</dependency>

<dependency>
    <groupId>org.glassfish.tyrus</groupId>
    <artifactId>tyrus-container-grizzly</artifactId>
    <version>1.0</version>
</dependency>

public void runServer() {
    Server server = new Server("localhost", 8025, "/websocket", EchoEndpoint.class);

    try {
        server.start();
        BufferedReader reader = new BufferedReader(new InputStreamReader(System.in));
        System.out.print("Please press a key to stop the server.");
        reader.readLine();
    } catch (Exception e) {
        e.printStackTrace();
    } finally {
        server.stop();
    }
}

The classes that are scanned for in WAR are the following ones:

Let's have the following classes in the WAR:

public class MyApplicationConfigOne implements ServerApplicationConfig {
    public Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses);
        Set<Class<? extends Endpoint>> s = new HashSet<Class<? extends Endpoint>>;
        s.add(ProgrammaticEndpointOne.class);
        return s;
    }

    public Set<Class> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
       Set<Class<?>> s = new HashSet<Class<?>>;
        s.add(AnnotatedEndpointOne.class);
        return s;
    }
}

public class MyApplicationConfigTwo implements ServerApplicationConfig {
    public Set<ServerEndpointConfig> getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses);
        Set<Class<? extends Endpoint>> s = new HashSet<Class<? extends Endpoint>>;
        s.add(ProgrammaticEndpointTwo.class);
    return s;
}

public Set<Class> getAnnotatedEndpointClasses(Set<Class<?>> scanned);
    Set<Class<?>> s = new HashSet<Class<?>>;
        s.add(AnnotatedEndpointTwo.class);
        return s;
    }
}

@ServerEndpoint(value = "/annotatedone")
public class AnnotatedEndpointOne {
    ...
}

@ServerEndpoint(value = "/annotatedtwo")
    public class AnnotatedEndpointTwo {
    ...
}

@ServerEndpoint(value = "/annotatedthree")
public class AnnotatedEndpointThree {
    ...
}

public class ProgrammaticEndpointOne extends Endpoint {
    ...
}

public class ProgrammaticEndpointTwo extends Endpoint {
    ...
}

public class ProgrammaticEndpointThree extends Endpoint {
    ...
}

According to the deployment algorithm classes AnnotatedEndpointOne, AnnotatedEndpointTwo, ProgrammaticEndpointOne and ProgrammaticEndpointTwo will be deployed. AnnotatedEndpointThree and ProgrammaticEndpointThree will not be deployed, as these are not returned by the respective methods of MyApplicationConfigOne nor MyApplicationConfigTwo.

Endpoints may be deployed using javax.websocket.server.ServerContainer during the application initialization phase. For websocket enabled web containers, developers may obtain a reference to the ServerContainer instance by retrieving it as an attribute named javax.websocket.server.ServerContainer on the ServletContext, see the following example for annotated endpoint:

@WebListener
@ServerEndpoint("/annotated")
public class MyServletContextListenerAnnotated implements ServletContextListener {

    @Override
    public void contextInitialized(ServletContextEvent servletContextEvent) {
        final ServerContainer serverContainer = (ServerContainer) servletContextEvent.getServletContext()
                                                    .getAttribute("javax.websocket.server.ServerContainer");

        try {
            serverContainer.addEndpoint(MyServletContextListenerAnnotated.class);
        } catch (DeploymentException e) {
            e.printStackTrace();
        }
    }

    @OnMessage
    public String onMessage(String message) {
        return message;
    }

    @Override
    public void contextDestroyed(ServletContextEvent servletContextEvent) {
    }
}

Server endpoint classes are POJOs (Plain Old Java Objects) that are annotated with javax.websocket.server.ServerEndpoint. Similarly, client endpoint classes are POJOs annotated with javax.websocket.ClientEndpoint. This section shows how to use Tyrus to annotate Java objects to create WebSocket web services.

The following code example is a simple example of a WebSocket endpoint using annotations. The example code shown here is from echo sample which ships with Tyrus.

@ServerEndpoint("/echo")
public class EchoEndpoint {

    @OnOpen
    public void onOpen(Session session) throws IOException {
        session.getBasicRemote().sendText("onOpen");
    }

    @OnMessage
    public String echo(String message) {
        return message + " (from your server)";
    }

    @OnError
    public void onError(Throwable t) {
        t.printStackTrace();
    }

    @OnClose
    public void onClose(Session session) {

    }
}

Let's explain the JAVA API for WebSocket annotations.

@ServerEndpoint(
    value = "/sample",
    decoders = ChatDecoder.class,
    encoders = DisconnectResponseEncoder.class,
    subprotocols = {"subprtotocol1", "subprotocol2"},
    configurator = Configurator.class
)
public class SampleEndpoint {

    @OnMessage
    public SampleResponse receiveMessage(SampleType message, Session session) {
        return new SampleResponse(message);
    }
}

@ServerEndpoint("/users/{username}")

@ServerEndpoint("/users/{username}")
public class UserEndpoint {

    @OnMessage
    public String getUser(String message, @PathParam("username") String userName) {
        ...
    }
}

public class SampleDecoder implements Decoder.Text<SampleType> {

    @Override
    public SampleType decode(String s) {
        return new SampleType(s);
    }

    @Override
    public boolean willDecode(String s) {
        return s.startsWith(SampleType.PREFIX);
    }

    @Override
    public void init(EndpointConfig config) {
        // do nothing.
    }

    @Override
    public void destroy() {
        // do nothing.
    }
}

public class SampleEncoder implements Encoder.Text<SampleType> {

    @Override
    public String encode(SampleType message) {
        return data.toString();
    }

    @Override
    public void init(EndpointConfig config) {
        // do nothing.
    }

    @Override
    public void destroy() {
        // do nothing.
    }
}

public class ConfiguratorTest extends ServerEndpointConfig.Configurator{

    public String getNegotiatedSubprotocol(List<String> supported, List<String> requested) {
        // Plug your own algorithm here
    }

    public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested) {
        // Plug your own algorithm here
    }

    public boolean checkOrigin(String originHeaderValue) {
        // Plug your own algorithm here
    }

    public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response) {
        // Plug your own algorithm here
    }

    public <T> T getEndpointInstance(Class<T> endpointClass) throws InstantiationException {
        // Plug your own algorithm here
    }
}

@ClientEndpoint(
    decoders = SampleDecoder.class,
    encoders = SampleEncoder.class,
    subprotocols = {"subprtotocol1", "subprotocol2"},
    configurator = ClientConfigurator.class)
public class SampleClientEndpoint {

    @OnOpen
    public void onOpen(Session p) {
        try {
            p.getBasicRemote().sendText("Hello!");
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    @OnMessage
    public void onMessage(String message) {
        System.out.println(String.format("%s %s", "Received message: ", message));
    }
}

public class Configurator {

    public void beforeRequest(Map<String, List<String>> headers) {
        //affect the headers before request is sent
    }

    public void afterResponse(HandshakeResponse hr) {
        //process the handshake response
    }
}

Implementing the javax.websocket.MessageHandler interface is one of the ways how to receive messages on endpoints (both server and client). It is aimed primarily on programmatic endpoints, as the annotated ones use the method level annotation javax.websocket.OnMessage to denote the method which receives messages.

The MessageHandlers get registered on the Session instance:

public class MyEndpoint extends Endpoint {

    @Override
    public void onOpen(Session session, EndpointConfig EndpointConfig) {
        session.addMessageHandler(new MessageHandler.Whole<String>() {
            @Override
            public void onMessage(String message) {
                System.out.println("Received message: "+message);
            }
        });
    }
}

There are two orthogonal criterions which classify MessageHandlers. According the WebSocket Protocol (RFC 6455) the message may be sent either complete, or in chunks. In Java API for WebSocket this fact is reflected by the interface which the handler implements. Whole messages are processed by handler which implements javax.websocket.MessageHandler.Whole interface. Partial messages are processed by handlers that implement javax.websocket.MessageHandler.Partial interface. However, if user registers just the whole message handler, it doesn't mean that the handler will process solely whole messages. If partial message is received, the parts are cached by Tyrus until the final part is received. Then the whole message is passed to the handler. Similarly, if the user registers just the partial message handler and whole message is received, it is passed directly to the handler.

The second criterion is the data type of the message. WebSocket Protocol (RFC 6455) defines four message data type - text message, According to Java API for WebSocket the text messages will be processed by MessageHandlers with the following types:

The binary messages will be processed by MessageHandlers with the following types:

The Java API for WebSocket limits the registration of MessageHandlers per Session to be one MessageHandler per native websocket message type. In other words, the developer can only register at most one MessageHandler for incoming text messages, one MessageHandler for incoming binary messages, and one MessageHandler for incoming pong messages. This rule holds for both whole and partial message handlers, i.e there may be one text MessageHandler - either whole, or partial, not both.

The javax.websocket.server.ServerEndpointConfig is used when deploying the endpoint either via implementing the javax.websocket.server.ServerApplicationConfig, or via registering the programmatic endpoint at the javax.websocket.server.ServerContainer instance. It allows the user to create the configuration programmatically.

The following example is used to deploy the EchoEndpoint programmatically. In the method getEndpointClass() the user has to specify the class of the deployed endpoint. In the example Tyrus will create an instance of EchoEndpoint and deploy it. This is the way how to tie together endpoint and it's configuration. In the method getPath() the user specifies that that the endpoint instance will be deployed at the path "/echo". In the method public List<String> getSubprotocols() the user specifies that the supported subprotocols are "echo1" and "echo2". The method getExtensions() defines the extensions the endpoint supports. Similarly the example configuration does not use any configurator. Method public List<Class<? extends Encoder>> getEncoders() defines the encoders used by teh endpoint. The decoders and user properties map are defined in similar fashion.

If the endpoint class which is about to be deployed is an annotated endpoint, note that the endpoint configuration will be taken from configuration object, not from the annotation on the endpoint class.

public class EchoEndpointConfig implements ServerEndpointConfig{

    private final Map<String, Object> userProperties = new HashMap<String, Object>();

    @Override
    public Class<?> getEndpointClass() {
        return EchoEndpoint.class;
    }

    @Override
    public String getPath() {
        return "/echo";
    }

    @Override
    public List<String> getSubprotocols() {
        return Arrays.asList("echo1","echo2");
    }

    @Override
    public List<Extension> getExtensions() {
        return null;
    }

    @Override
    public Configurator getConfigurator() {
        return null;
    }

    @Override
    public List<Class<? extends Encoder>> getEncoders() {
        return Arrays.asList(SampleEncoder.class);
    }

    @Override
    public List<Class<? extends Decoder>> getDecoders() {
        return Arrays.asList(SampleDecoder.class);
    }

    @Override
    public Map<String, Object> getUserProperties() {
        return userProperties;
    }
}

To make the development easy the javax.websocket.server.ServerEndpointConfig provides a builder to construct the configuration object:

ServerEndpointConfig config = ServerEndpointConfig.Builder.create(EchoEndpoint.class,"/echo").
    decoders(Arrays.<Class<? extends Decoder>>asList(JsonDecoder.class)).
    encoders(Arrays.<Class< extends Encoder>>asList(JsonEncoder.class)).build();

The javax.websocket.ClientEndpointConfig is used when deploying the programmatic client endpoint via registering the programmatic endpoint at the WebSocketContainer instance. Some of the configuration methods come from the EndpointConfigclass, which is extended by both javax.websocket.server.ServerEndpointConfig and javax.websocket.ClientEndpointConfig. Then there are methods for configuring the preferred subprotocols the client endpoint wants to use and supported extensions. It is also possible to use the ClientEndpointConfig.Configurator in order to be able to affect the endpoint behaviour before and after request.

Similarly to the ServerEndpointConfig, there is a Builder provided to construct the configuration easily:

ClientEndpointConfig.Builder.create().
    decoders(Arrays.<Class<? extends Decoder>>asList(JsonDecoder.class)).
    encoders(Arrays.<Class<? extends Encoder>>asList(JsonEncoder.class)).
    preferredSubprotocols(Arrays.asList("echo1", "echo2")).build();

As mentioned before, the endpoint in Java API for WebSocket is represented either by instance of javax.websocket.Endpoint, or by class annotated with either javax.websocket.server.ServerEndpoint or javax.websocket.ClientEndpoint. Unless otherwise defined by developer provided configurator (defined in instance of javax.websocket.server.ServerEndpointConfig or javax.websocket.ClientEndpointConfig, Tyrus uses one endpoint instance per VM per connected peer. Therefore one endpoint instance typically handles connections from one peer.

The sequence of interactions between an endpoint instance and remote peer is in Java API for WebSocket modelled by javax.websocket.Session instance. This interaction starts by mandatory open notification, continues by 0 - n websocket messages and is finished by mandatory closing notification.

The javax.websocket.Session instance is passed by Tyrus to the user in the following methods for programmatic endpoints:

The javax.websocket.Session instance is passed by Tyrus to the user in the methods annotated by following annotations for annotated endpoints:

In each of the methods annotated with the preceeding annotations the user may use parameter of type javax.websocket.Session. In the following example the developer wants to send a message in the method annotated with javax.websocket.OnOpen. As we will demonstrate later, the developer needs the session instance to do so. According to Java API for WebSocket Session is one of the allowed parameters in methods annotated with javax.websocket.OnOpen. Once the annotated method gets called, Tyrus passes in the correct instance of javax.websocket.Session.

@ServerEndpoint("/echo")
public class EchoEndpoint {

    @OnOpen
    public void onOpen(Session session) throws IOException {
        session.getBasicRemote().sendText("onOpen");
    }

    @OnMessage
    public String echo(String message) {
        return message;
    }

    @OnError
    public void onError(Throwable t) {
        t.printStackTrace();
    }
}

Generally there are two ways how to send message to the peer endpoint. First one is usable for annotated endpoints only. The user may send the message by returning the message content from the method annotated with javax.websocket.OnMessage. In the following example the message m is sent back to the remote endpoint.

@OnMessage
public String echo(String m) {
    return m;                                                                                                                               
}

The other option how to send a message is to obtain the javax.websocket.RemoteEndpoint instance via the javax.websocket.Session instance. See the following example:

@OnMessage
public void echo(String message, Session session) {
    session.getBasicRemote().sendText(message);
}

The interface javax.websocket.RemoteEndpoint, part of Java API for WebSocket, is designed to represent the other end of the communication (related to the endpoint), so the developer uses it to send the message. There are two basic interfaces the user may use - javax.websocket.RemoteEndpoint$Basic and javax.websocket.RemoteEndpoint$Async.

public void sendPartialTextMessage(String message, Boolean isLast, Session session){
    try {
        session.getBasicRemote().sendText(message, isLast);
    } catch (IOException e) {
        e.printStackTrace();
    }
}

public void sendWholeAsyncMessage(String message, Session session){
    Future<Void> future = session.getAsyncRemote().sendText(message);
}