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

<dependency>
    <groupId>jakarta.websocket</groupId>
    <artifactId>jakarta.websocket-api</artifactId>
    <version>2.0.0</version>
</dependency>

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

public class DocClient {
    private static 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>2.0.5</version>
</dependency>

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

public void runServer() {
    Server server = new Server("localhost", 8025, "/websockets", null, 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 jakarta.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 jakarta.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("jakarta.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 jakarta.websocket.server.ServerEndpoint. Similarly, client endpoint classes are POJOs annotated with jakarta.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 jakarta.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 jakarta.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 jakarta.websocket.MessageHandler.Whole interface. Partial messages are processed by handlers that implement jakarta.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 jakarta.websocket.server.ServerEndpointConfig is used when deploying the endpoint either via implementing the jakarta.websocket.server.ServerApplicationConfig, or via registering the programmatic endpoint at the jakarta.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 the 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 jakarta.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 jakarta.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 jakarta.websocket.server.ServerEndpointConfig and jakarta.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 jakarta.websocket.Endpoint, or by class annotated with either jakarta.websocket.server.ServerEndpoint or jakarta.websocket.ClientEndpoint. Unless otherwise defined by developer provided configurator (defined in instance of jakarta.websocket.server.ServerEndpointConfig or jakarta.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 jakarta.websocket.Session instance. This interaction starts by mandatory open notification, continues by 0 - n websocket messages and is finished by mandatory closing notification.

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

The jakarta.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 jakarta.websocket.Session. In the following example the developer wants to send a message in the method annotated with jakarta.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 jakarta.websocket.OnOpen. Once the annotated method gets called, Tyrus passes in the correct instance of jakarta.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 jakarta.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 jakarta.websocket.RemoteEndpoint instance via the jakarta.websocket.Session instance. See the following example:

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

The interface jakarta.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 - jakarta.websocket.RemoteEndpoint$Basic and jakarta.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);
}

The following example presents how to inject a bean to the jakarta.websocket.server.ServerEndpoint annotated class using jakarta.inject.Inject. Class InjectedSimpleBean gets injected into class SimpleEndpoint on line 15.

public class InjectedSimpleBean {

    private static final String TEXT = " (from your server)";

    public String getText() {
        return TEXT;
    }
}

@ServerEndpoint(value = "/simple")
public class SimpleEndpoint {

    private boolean postConstructCalled = false;

    @Inject
    InjectedSimpleBean bean;

    @OnMessage
    public String echo(String message) {
        return String.format("%s%s", message, bean.getText());
    }
}

The following sample presents how to turn jakarta.websocket.server.ServerEndpoint annotated class into jakarta.ejb.Singleton and use interceptor on it.

@ServerEndpoint(value = "/singleton")
@Singleton
@Interceptors(LoggingInterceptor.class)
public class SingletonEndpoint {

    int counter = 0;
    public static boolean interceptorCalled = false;

    @OnMessage
    public String echo(String message) {
        return interceptorCalled ? String.format("%s%s", message, counter++) : "LoggingInterceptor not called.";
    }
}

public class LoggingInterceptor {

    @AroundInvoke
    public Object manageTransaction(InvocationContext ctx) throws Exception {
        SingletonEndpoint.interceptorCalled = true;
        Logger.getLogger(getClass().getName()).info("LOGGING.");
        return ctx.proceed();
    }
}

When accessing "wss" URLs, Tyrus client will pick up whatever keystore and truststore is actually set for current JVM instance, but that might not be always convenient. WebSocket API does not have this feature (yet, see WEBSOCKET_SPEC-210), so Tyrus exposed two SSL configuration classes SSLEngineConfigurator and SslEngineConfigurator , which can be used for specifying all SSL parameters to be used with current client instance. The former configuration class belongs to Grizzly configuration API and therefore works only with Grizzly client. The latter configuration class works with both Grizzly and JDK client and offers some extensions over the Grizzly SSLEngineConfigurator allowing more control of host verification during the SSL handshake. For more details please refer to the following subsection dealing with host verification. Additionally, WebSocket API does not have anything like a client, only WebSocketContainer and it does not have any properties, so you need to use Tyrus specific class - ClientManager.

final ClientManager client = ClientManager.createClient();

System.getProperties().put("javax.net.debug", "all");
System.getProperties().put(SSLContextConfigurator.KEY_STORE_FILE, "...");
System.getProperties().put(SSLContextConfigurator.TRUST_STORE_FILE, "...");
System.getProperties().put(SSLContextConfigurator.KEY_STORE_PASSWORD, "...");
System.getProperties().put(SSLContextConfigurator.TRUST_STORE_PASSWORD, "...");
final SSLContextConfigurator defaultConfig = new SSLContextConfigurator();

defaultConfig.retrieve(System.getProperties());
    // or setup SSLContextConfigurator using its API.

SSLEngineConfigurator sslEngineConfigurator =
    new SSLEngineConfigurator(defaultConfig, true, false, false);
client.getProperties().put(ClientProperties.SSL_ENGINE_CONFIGURATOR,
    sslEngineConfigurator);
client.connectToServer(... , ClientEndpointConfig.Builder.create().build(),
    new URI("wss://localhost:8181/sample-echo/echo"));
}

If there seems to be a problem with Tyrus SSL connection, it is strongly recommended to use -Djavax.net.debug=all system property as it provides invaluable information for troubleshooting.

client.connectToServer(... , new URI("wss://target-server:8181/application/endpoint"));
                

SslEngineConfigurator sslEngineConfigurator = new SslEngineConfigurator(new SslContextConfigurator());
sslEngineConfigurator.setHostVerificationEnabled(false)
client.getProperties().put(ClientProperties.SSL_ENGINE_CONFIGURATOR, sslEngineConfigurator);
                

SslEngineConfigurator sslEngineConfigurator = new SslEngineConfigurator(new SslContextConfigurator());
sslEngineConfigurator.setHostnameVerifier(new HostnameVerifier() {
    @Override
    public boolean verify(String host, SSLSession sslSession) {
        Certificate certificate = sslSession.getPeerCertificates()[0];
        // validate the host in the certificate
    }
});
client.getProperties().put(ClientProperties.SSL_ENGINE_CONFIGURATOR, sslEngineConfigurator);
                

WebSocketContainer.connectToServer(...) methods are by definition blocking - declared exceptions needs to be thrown after connection attempt is made and it returns Session instance, which needs to be ready for sending messages and invoking other methods, which require already established connection.

Existing connectToServer methods are fine for lots of uses, but it might cause issue when you are designing application with highly responsible user interface. Tyrus introduces asynchronous variants to each connectToServer method (prefixed with "async"), which returns Future<Session>. These methods do only simple check for provided URL and the rest is executed in separate thread. All exceptions thrown during this phase are reported as cause of ExecutionException thrown when calling Future<Session>.get().

Asynchronous connect methods are declared on Tyrus implementation of WebSocketContainer called ClientManager.

ClientManager client = ClientManager.createClient();
  final Future<Session> future = client.asyncConnectToServer(ClientEndpoint.class, URI.create("..."));
  try {
    future.get();
  } catch (...) {
}

ClientManager contains async alternative to each connectToServer method.

One of the typical usecases we've seen so far for WebSocket server-side endpoints is broadcasting messages to all connected clients, something like:

@OnMessage
public void onMessage(Session session, String message) throws IOException {
  for (Session s : session.getOpenSessions()) {
    s.getBasicRemote().sendText(message);
  }
}

Executing this code might cause serious load increase on your application server. Tyrus provides optimized broadcast implementation, which takes advantage of the fact, that we are sending exactly same message to all clients, so dataframe can be created and serialized only once. Furthermore, Tyrus can iterate over set of opened connections faster than Session.getOpenSession().

@OnMessage
public void onMessage(Session session, String message) {
  ((TyrusSession) session).broadcast(message);
}

Unfortunately, WebSocket API forbids anything else than Session in @OnMessage annotated method parameter, so you cannot use TyrusSession there directly and you might need to perform instanceof check.

Sevlet container buffers incoming WebSocket frames and there must be a size limit to precede OutOfMemory Exception and potentially DDoS attacks.

Configuration property is named "org.glassfish.tyrus.servlet.incoming-buffer-size" and you can set it in web.xml (this particular snipped sets the buffer size to 17000000 bytes (~16M payload):

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <context-param>
    <param-name>org.glassfish.tyrus.servlet.incoming-buffer-size</param-name>
    <param-value>17000000</param-value>
  </context-param>
</web-app>

Default value is 4194315, which correspond to 4M plus few bytes to frame headers, so you should be able to receive up to 4M long message without the need to care about this property.

Same issue is present on client side. There you can set this property via ClientManager:

ClientManager client = ClientManager.createClient();
client.getProperties().put("org.glassfish.tyrus.incomingBufferSize", 6000000); // sets the incoming buffer size to 6000000 bytes.
client.connectToServer( ... )

By default, WebSocket client implementation in Tyrus re-creates client runtime whenever WebSocketContainer#connectToServer is invoked. This approach gives us some perks like out-of-the-box isolation and relatively low thread count (currently we have 1 selector thread and 2 worker threads). Also it gives you the ability to stop the client runtime – one Session instance is tied to exactly one client runtime, so we can stop it when Session is closed. This seems as a good solution for most of WebSocket client use cases – you usually use java client from application which uses it for communicating with server side and you typically don’t need more than 10 instances (my personal estimate is that more than 90% applications won’t use more than 1 connection). There are several reasons for it – of it is just a client, it needs to preserve server resources – one WebSocket connection means one TCP connection and we don’t really want clients to consume more than needed. Previous statement may be invalidated by WebSocket multiplexing extension, but for now, it is still valid.

On the other hand, WebSocket client implementations in some other containers took another (also correct) approach – they share client runtime for creating all client connections. That means they might not have this strict one session one runtime policy, they cannot really give user way how he to control system resources, but surely it has another advantage – it can handle much more opened connections. Thread pools are share among client sessions which may or may not have some unforeseen consequences, but if its implemented correctly, it should outperform Tyrus solution mentioned in previous paragraph in some use cases, like the one mentioned in TYRUS-275 - performance tests. Reporter created simple program which used WebSocket API to create clients and connect to remote endpoint and he measured how many clients can he create (or in other words: how many parallel client connections can be created; I guess that original test case is to measure possible number of concurrent clients on server side, but that does not really matter for this post). Tyrus implementation loose compared to some other and it was exactly because it did not have shared client runtime capability.

How can you use this feature?

ClientManager client = ClientManager.createClient();

client.getProperties().put(ClientProperties.SHARED_CONTAINER, true);

You might also want to specify container idle timeout:

client.getProperties().put(ClientProperties.SHARED_CONTAINER_IDLE_TIMEOUT, 5);

Last but not least, you might want to specify thread pool sizes used by shared container (please use this feature only when you do know what are you doing. Grizzly by default does not limit max number of used threads, so if you do that, please make sure thread pool size fits your purpose). Even though the default unlimited thread pool size is sufficient for the vast majority of client usages, it is also important ot note that if the max. thread pool size is not specified and the clients which share the thread pool receive a large number of messages at the same moment, a new thread can be created for each of the received messages which might demand large amount of system resources and might even lead to a program failure if the required resources are not available. Therefore for particularly busy clients setting the max thread pool size can be only recommended. The following example shows how to set the maximal thread poll size.

client.getProperties().put(GrizzlyClientProperties.SELECTOR_THREAD_POOL_CONFIG, ThreadPoolConfig.defaultConfig().setMaxPoolSize(3));
client.getProperties().put(GrizzlyClientProperties.WORKER_THREAD_POOL_CONFIG, ThreadPoolConfig.defaultConfig().setMaxPoolSize(10));

ClientManager client = ClientManager.createClient();
client.getProperties().put(ClientProperties.MASKING_KEY_GENERATOR, new MaskingKeyGenerator() {

    private final Random random = new Random();

    @Override
    public int nextInt() {
        return random.nextInt();
    }
});

Please note that Extensions support is considered to be experimental and any API can be changed anytime. Also, you should ask yourself at least twice whether you don't want to achieve your goal by other means - WebSocket Extension is very powerful and can easily break your application when not used with care or enough expertise.

WebSocket frame used in ExtendedExtension:

public class Frame {

    public boolean isFin() { .. }
    public boolean isRsv1() { .. }
    public boolean isRsv2() { .. }
    public boolean isRsv3() { .. }
    public boolean isMask() { .. }
    public byte getOpcode() { .. }
    public long getPayloadLength() { .. }
    public int getMaskingKey() { .. }
    public byte[] getPayloadData() { .. }
    public boolean isControlFrame() { .. }

    public static Builder builder() { .. }
    public static Builder builder(Frame frame) { .. }

    public final static class Builder {

    public Builder() { .. }
    public Builder(Frame frame) { .. }
    public Frame build() { .. }
    public Builder fin(boolean fin) { .. }
    public Builder rsv1(boolean rsv1) { .. }
    public Builder rsv2(boolean rsv2) { .. }
    public Builder rsv3(boolean rsv3) { .. }
    public Builder mask(boolean mask) { .. }
    public Builder opcode(byte opcode) { .. }
    public Builder payloadLength(long payloadLength) { .. }
    public Builder maskingKey(int maskingKey) { .. }
    public Builder payloadData(byte[] payloadData) { .. }
}

Frame is immutable, so if you want to create new one, you need to create new builder, modify what you want and build it:

Frame newFrame = Frame.builder(originalFrame).rsv1(true).build();

Note that there is only one convenience method: isControlFrame. Other information about frame type etc needs to be evaluated directly from opcode, simply because there might not be enough information to get the correct outcome or the information itself would not be very useful. For example: opcode 0×00 means continuation frame, but you don’t have any chance to get the information about actual type (text or binary) without intercepting data from previous frames. Consider Frame class as raw representation as possible. isControlFrame() can be also gathered from opcode, but it is at least always deterministic and it will be used by most of extension implementations. It is not usual to modify control frames as it might end with half closed connections or unanswered ping messages.

ExtendedExtension representation needs to be able to handle extension parameter negotiation and actual processing of incoming and outgoing frames. It also should be compatible with existing jakarta.websocket.Extension class, since we want to re-use existing registration API and be able to return new extension instance included in response from List<Extension> Session.getNegotiatedExtensions() call. Consider following:

public interface ExtendedExtension extends Extension {

    Frame processIncoming(ExtensionContext context, Frame frame);
    Frame processOutgoing(ExtensionContext context, Frame frame);

    List onExtensionNegotiation(ExtensionContext context, List requestedParameters);
    void onHandshakeResponse(ExtensionContext context, List responseParameters);

    void destroy(ExtensionContext context);

    interface ExtensionContext {

        Map<String, Object> getProperties();
    }
}

ExtendedExtension is capable of processing frames and influence parameter values during the handshake. Extension is used on both client and server side and since the negotiation is only place where this fact applies, we needed to somehow differentiate these sides. On server side, only onExtensionNegotiation(..) method is invoked and on client side onHandshakeResponse(..). Server side method is a must, client side could be somehow solved by implementing ClientEndpointConfig.Configurator#afterResponse(..) or calling Session.getNegotiatedExtenions(), but it won’t be as easy to get this information back to extension instance and even if it was, it won’t be very elegant. Also, you might suggest replacing processIncoming and processOutgoing methods by just oneprocess(Frame) method. That is also possible, but then you might have to assume current direction from frame instance or somehow from ExtensionContext, which is generally not a bad idea, but it resulted it slightly less readable code.

ExtensionContext and related lifecycle method is there because original jakarta.websocket.Extension is singleton and ExtendedExtension must obey this fact. But it does not meet some requirements we stated previously, like per connection parameter negotiation and of course processing itself will most likely have some connection state. Lifecycle of ExtensionContext is defined as follows: ExtensionContext instance is created right before onExtensionNegotiation (server side) or onHandshakeResponse (client side) and destroyed after destroy method invocation. Obviously, processIncoming or processOutgoing cannot be called before ExtensionContext is created or after is destroyed. You can think of handshake related methods as @OnOpenand destroy as @OnClose.

For those more familiar with WebSocket protocol: process*(ExtensionContext, Frame) is always invoked with unmasked frame, you don’t need to care about it. On the other side, payload is as it was received from the wire, before any validation (UTF-8 check for text messages). This fact is particularly important when you are modifying text message content, you need to make sure it is properly encoded in relation to other messages, because encoding/decoding process is stateful – remainder after UTF-8 coding is used as input to coding process for next message. If you want just test this feature and save yourself some headaches, don’t modify text message content or try binary messages instead.

public class CryptoExtension implements ExtendedExtension {

    @Override
    public Frame processIncoming(ExtensionContext context, Frame frame) {
         return lameCrypt(context, frame);
    }

    @Override
    public Frame processOutgoing(ExtensionContext context, Frame frame) {
        return lameCrypt(context, frame);
    }

    private Frame lameCrypt(ExtensionContext context, Frame frame) {
        if(!frame.isControlFrame() && (frame.getOpcode() == 0x02)) {
            final byte[] payloadData = frame.getPayloadData();
            payloadData[0] ^= (Byte)(context.getProperties().get("key"));

            return Frame.builder(frame).payloadData(payloadData).build();
        } else {
            return frame;
        }
    }

    @Override
    public List onExtensionNegotiation(ExtensionContext context,
                                       List requestedParameters) {
        init(context);
        // no params.
        return null;
    }

    @Override
    public void onHandshakeResponse(ExtensionContext context,
    List responseParameters) {
        init(context);
    }

    private void init(ExtensionContext context) {
        context.getProperties().put("key", (byte)0x55);
    }

    @Override
    public void destroy(ExtensionContext context) {
        context.getProperties().clear();
    }

    @Override
    public String getName() {
        return "lame-crypto-extension";
    }

    @Override
    public List getParameters() {
        // no params.
        return null;
    }
}

ArrayList extensions = new ArrayList();
extensions.add(new CryptoExtension());

final ClientEndpointConfig clientConfiguration =
    ClientEndpointConfig.Builder.create()
    .extensions(extensions).build();

WebSocketContainer client = ContainerProvider.getWebSocketContainer();
final Session session = client.connectToServer(new Endpoint() {
    @Override
    public void onOpen(Session session, EndpointConfig config) {
        // ...
    }
}, clientConfiguration, URI.create(/* ... */));

public class CryptoExtensionApplicationConfig implements ServerApplicationConfig {

    @Override
    public Set getEndpointConfigs(Set<Class<? extends Endpoint>> endpointClasses) {
        Set endpointConfigs = new HashSet();
        endpointConfigs.add(
            ServerEndpointConfig.Builder.create(EchoEndpoint.class, "/echo")
            .extensions(Arrays.asList(new CryptoExtension())).build()
        );
        return endpointConfigs;
    }

    @Override
    public Set<Class<?>> getAnnotatedEndpointClasses(Set<Class<?>> scanned) {
        // all scanned endpoints will be used.
        return scanned;
    }
}

public class EchoEndpoint extends Endpoint {
    @Override
    public void onOpen(Session session, EndpointConfig config) {
        // ...
    }
}

If you need semi-persistent client connection, you can always implement some reconnect logic by yourself, but Tyrus Client offers useful feature which should be much easier to use. See short sample code:

ClientManager client = ClientManager.createClient();
ClientManager.ReconnectHandler reconnectHandler = new ClientManager.ReconnectHandler() {

  private int counter = 0;

  @Override
  public boolean onDisconnect(CloseReason closeReason) {
    counter++;
    if (counter <= 3) {
      System.out.println("### Reconnecting... (reconnect count: " + counter + ")");
      return true;
    } else {
      return false;
    }
  }

  @Override
  public boolean onConnectFailure(Exception exception) {
    counter++;
    if (counter <= 3) {
      System.out.println("### Reconnecting... (reconnect count: " + counter + ") " + exception.getMessage());

      // Thread.sleep(...) or something other "sleep-like" expression can be put here - you might want
      // to do it here to avoid potential DDoS when you don't limit number of reconnects.
      return true;
    } else {
      return false;
    }
  }

  @Override
  public long getDelay() {
    return 1;
  }
};

client.getProperties().put(ClientProperties.RECONNECT_HANDLER, reconnectHandler);

client.connectToServer(...)

ReconnectHandler contains three methods, onDisconnect, onConnectFailure and getDelay. First will be executed whenever @OnClose annotated method (or Endpoint.onClose(..)) is executed on client side - this should happen when established connection is lost for any reason. You can find the reason in methods parameter. Other one, called onConnectFailure is invoked when client fails to connect to remote endpoint, for example due to temporary network issue or current high server load. Method getDelay is called after any of previous methods returns true and the returned value will be used to determine delay before next connection attempt. Default value is 5 seconds.

Tyrus client supports traversing proxies, but it is Tyrus specific feature and its configuration is shown in the following code sample:

ClientManager client = ClientManager.createClient();
client.getProperties().put(ClientProperties.PROXY_URI, "http://my.proxy.com:80");
            

Value is expected to be proxy URI. Protocol part is currently ignored, but must be present.

As has been said in previous chapters both Tyrus client and server were implemented on top of Grizzly NIO framework. This still remains true, but an alternative Tyrus Websocket client implementation based on Java 7 Asynchronous Channel API has been available since version 1.6. There are two options how to switch between client implementations. If you do not mind using Tyrus specific API, the most straightforward way is to use:

final ClientManager client = ClientManager.createClient(JdkClientContainer.class.getName());
            

You just have to make sure that the dependency on JDK client is included in your project:

<dependency>
  <groupId>org.glassfish.tyrus</groupId>
  <artifactId>tyrus-container-jdk-client</artifactId>
  <version>2.0.5</version>
</dependency>
            

Grizzly client is the default option, so creating a client without any parameters will result in Grizzly client being used.

There is also an option how to use JDK client with the standard Websocket API.

final WebSocketContainer client = ContainerProvider.getWebSocketContainer();
            

The code listed above will scan class path for Websocket client implementations. A slight problem with this approach is that if there is more than one client on the classpath, the first one discovered will be used. Therefore if you intend to use JDK client with the standard API, you have to make sure that there is not a Grizzly client on the classpath as it might be used instead.

The main reason why JDK client has been implemented is that it does not have any extra dependencies except JDK 7 and of course some other Tyrus modules, which makes it considerable more lightweight compared to Tyrus Grizzly client, which requires 1.4 MB of dependencies.

It is also important to note that the JDK client has been implemented in a way similar to Grizzly client shared container option, which means that there is one thread pool shared among all clients.

Proxy configuration for JDK client is the same as for Grizzly client shown above.

SslContextConfigurator sslContextConfigurator = new SslContextConfigurator();
sslContextConfigurator.setTrustStoreFile("...");
sslContextConfigurator.setTrustStorePassword("...");
sslContextConfigurator.setTrustStoreType("...");
sslContextConfigurator.setKeyStoreFile("...");
sslContextConfigurator.setKeyStorePassword("...");
sslContextConfigurator.setKeyStoreType("...");
SslEngineConfigurator sslEngineConfigurator = new SslEngineConfigurator(sslContextConfigurator, true, false, false);

client.getProperties().put(ClientProperties.SSL_ENGINE_CONFIGURATOR, sslEngineConfigurator);
                

Apart from logging, Tyrus supports another useful means for debugging and diagnosing a deployed application which will be referred to as tracing on the following lines. Tracing consists of including vital information about handshake handling into a handshake response. The provided information includes among other things an insight into how Tyrus matches handshake request URI against the URI of the deployed endpoints and how the best matching endpoint is selected. The tracing information is included in a handshake response as a content of HTTP headers with X-Tyrus-Tracing- as the header names prefix. All the tracing information will also be available in the server log if the appropriate logging level is set. If it is still unclear, how Tyrus tracing works, please refer to the subsection with title Tracing Examples.

                            serverProperties.put(TyrusWebSocketEngine.TRACING_TYPE, ON_DEMAND);
                            serverProperties.put(TyrusWebSocketEngine.TRACING_THRESHOLD, SUMMARY);
                        

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <context-param>
        <param-name>org.glassfish.tyrus.server.tracingType</param-name>
        <param-value>ALL</param-value>
    </context-param>
</web-app>

  1 GET /endpoint/b HTTP/1.1
  2 Connection: Upgrade
  3 Host: localhost:8025
  4 Origin: localhost:8025
  5 Sec-WebSocket-Key: YrFldD8nhRW+6hJ2K/TMqw==
  6 Sec-WebSocket-Version: 13
  7 Upgrade: websocket
  8 X-Tyrus-Tracing-Accept: Whatever
  9 X-Tyrus-Tracing-Threshold: SUMMARY

  1 HTTP/1.1 404 Not found
  2 x-tyrus-tracing-00 : [0 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/{a}/b
  3 x-tyrus-tracing-01 : [0 ms] URIs /samples-debug/endpoint/b and /samples-debug/endpoint/{a}/b have different length
  4 x-tyrus-tracing-02 : [0 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/{a}/{b}
  5 x-tyrus-tracing-03 : [0 ms] URIs /samples-debug/endpoint/b and /samples-debug/endpoint/{a}/{b} have different length
  6 x-tyrus-tracing-04 : [0 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/a/b
  7 x-tyrus-tracing-05 : [1 ms] URIs /samples-debug/endpoint/b and /samples-debug/endpoint/a/b have different length
  8 x-tyrus-tracing-06 : [1 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/a/a
  9 x-tyrus-tracing-07 : [1 ms] URIs /samples-debug/endpoint/b and /samples-debug/endpoint/a/a have different length
 10 x-tyrus-tracing-08 : [1 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/a
 11 x-tyrus-tracing-09 : [1 ms] Segment "a" does not match
 12 x-tyrus-tracing-10 : [1 ms] Matching request URI /samples-debug/endpoint/b against /samples-debug/endpoint/a/{b}
 13 x-tyrus-tracing-11 : [1 ms] URIs /samples-debug/endpoint/b and /samples-debug/endpoint/a/{b} have different length
 14 x-tyrus-tracing-12 : [3 ms] Endpoints matched to the request URI: []

  1 HTTP/1.1 101
  2 connection: Upgrade
  3 sec-websocket-accept: C8/QbF4Mx9sX31sihUcnI19yqto=
  4 upgrade: websocket
  5 x-tyrus-tracing-00 : [0 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/{a}/b
  6 x-tyrus-tracing-01 : [0 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/{a}/{b}
  7 x-tyrus-tracing-02 : [0 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/a/b
  8 x-tyrus-tracing-03 : [1 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/a/a
  9 x-tyrus-tracing-04 : [1 ms] Segment "a" does not match
 10 x-tyrus-tracing-05 : [1 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/a
 11 x-tyrus-tracing-06 : [1 ms] URIs /samples-debug/endpoint/a/b and /samples-debug/endpoint/a have different length
 12 x-tyrus-tracing-07 : [1 ms] Matching request URI /samples-debug/endpoint/a/b against /samples-debug/endpoint/a/{b}
 13 x-tyrus-tracing-08 : [3 ms] Choosing better match from /samples-debug/endpoint/{a}/b and /samples-debug/endpoint/a/b
 14 x-tyrus-tracing-09 : [3 ms] /samples-debug/endpoint/a/b is an exact match
 15 x-tyrus-tracing-10 : [3 ms] Choosing better match from /samples-debug/endpoint/a/{b} and /samples-debug/endpoint/{a}/b
 16 x-tyrus-tracing-11 : [3 ms] /samples-debug/endpoint/a/{b} is a  better match, because it has longer exact path
 17 x-tyrus-tracing-12 : [3 ms] Choosing better match from /samples-debug/endpoint/a/{b} and /samples-debug/endpoint/{a}/b
 18 x-tyrus-tracing-13 : [3 ms] /samples-debug/endpoint/a/{b} is a  better match, because it has longer exact path
 19 x-tyrus-tracing-14 : [3 ms] Choosing better match from /samples-debug/endpoint/a/{b} and /samples-debug/endpoint/a/b
 20 x-tyrus-tracing-15 : [3 ms] /samples-debug/endpoint/a/b is an exact match
 21 x-tyrus-tracing-16 : [3 ms] Choosing better match from /samples-debug/endpoint/{a}/{b} and /samples-debug/endpoint/a/{b}
 22 x-tyrus-tracing-17 : [4 ms] /samples-debug/endpoint/a/{b} is a  better match, because it has longer exact path
 23 x-tyrus-tracing-18 : [4 ms] Choosing better match from /samples-debug/endpoint/{a}/{b} and /samples-debug/endpoint/{a}/b
 24 x-tyrus-tracing-19 : [4 ms] /samples-debug/endpoint/{a}/b is a  better match, because /samples-debug/endpoint/{a}/{b} has more variables
 25 x-tyrus-tracing-20 : [4 ms] Endpoints matched to the request URI: [/samples-debug/endpoint/a/b, /samples-debug/endpoint/a/{b}, /samples-debug/endpoint/{a}/b, /samples-debug/endpoint/{a}/{b}]
 26 x-tyrus-tracing-21 : [4 ms] Endpoint selected as a match to the handshake URI: /samples-debug/endpoint/a/b 

Tyrus client offers a possibility, how to enable printing of handshake requests and responses to standard output without having to configure Java logging, which is essential when debugging a misbehaving websocket application. This feature is particularly useful with tracing enabled. The following sample shows, how the handshake logging can be enabled:

                ClientManager client = ClientManager.createClient();
                client.getProperties().put(ClientProperties.LOG_HTTP_UPGRADE, true);
            

Tyrus allows monitoring and accessing some runtime properties and metrics at the server side using JMX (Java management extension technology). The monitoring API has been available since version 1.6 and the following properties are available at runtime through MXBeans. Number of open sessions, maximal number of open session since the start of monitoring and list of deployed endpoint class names and paths are available for each application. Endpoint class name and path the endpoint is registered on, number of open session and maximal number of open sessions are available for each endpoint. Apart from that message as well as error statistics are collected both per application and per individual endpoint.

The following message statistics are monitored for both sent and received messages:

Moreover all of them are collected separately for text, binary and control messages and apart from the statistics being available for the three separate categories, total numbers summing up statistics from the three types of messages are also available.

As has been already mentioned above, Tyrus also monitors errors on both application and endpoint level. An error is identified by the Throwable class name that has been thrown. Statistics are collected about number of times each Throwable has been thrown, so a list of errors together with a number of times each error occurred is available on both application and endpoint level. The monitored errors correspond to invocation of @OnError method on an annotated endpoint or its equivalent on a programmatic endpoint (The invocation of @OnError method is just an analogy and an error will be monitored even if no @OnError method is provided on the endpoint). Errors that occur in @OnOpen, @OnClose methods and methods handling incoming messages are monitored. Errors that occurred during handshake will not be among the monitored errors.

The collected metrics as well as the endpoint properties mentioned above are accessible at runtime through Tyrus MXBeans. As has been already mention the information is available on both application and endpoint level with each application or endpoint being represented with four MXBeans. One of those MXBeans contains total message statistics for both sent and received messages as well as any properties specific for applications or endpoints such as endpoint path in the case of an endpoint. The other three MXBeans contain information about sent and received text, binary and control messages.

When a user connects to a tyrus application MBean server using an JMX client such as JConsole, they will see the following structure:

In fact the monitoring structure described above was a little bit simplistic, because there is an additional monitoring level available, which causes message metrics being also available per session. The monitoring structure is very similar to the one described above, with a small difference that there are four MXBeans registered for each session, which contain text, binary, control and total message statistics. In order to distinguish the two monitoring levels, they will be referred to as endpoint-level monitoring and session-level monitoring.

serverProperties.put(ApplicationEventListener.APPLICATION_EVENT_LISTENER, new SessionlessApplicationMonitor());
                

serverProperties.put(ApplicationEventListener.APPLICATION_EVENT_LISTENER, new SessionAwareApplicationMonitor());
                

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <context-param>
        <param-name>org.glassfish.tyrus.core.monitoring.ApplicationEventListener</param-name>
        <param-value>org.glassfish.tyrus.ext.monitoring.jmx.SessionlessApplicationMonitor</param-value>
    </context-param>
</web-app>
                

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <context-param>
        <param-name>org.glassfish.tyrus.core.monitoring.ApplicationEventListener</param-name>
        <param-value>org.glassfish.tyrus.ext.monitoring.jmx.SessionAwareApplicationMonitor</param-value>
    </context-param>
</web-app>
                

Tyrus offers a few ways to limit the number of open sessions, which can be used to save limited resources on a server hosting system. The limits can be configured in several scopes:

If the number of simultaneously opened sessions exceeds any of these limits, Tyrus will close the session with close code 1013 - Try Again Later.

Limits mentioned above can be combined together. For example, let's say we have an application with two endpoints. Overall limit per application will be 1000 open sessions and the first one, non-critical endpoint, will be limited to 75 open sessions at maximum. So we know that the second endpoint can handle 925-1000 opened sessions, depends on how many open sessions are connected to the first endpoint (0-75).

<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <context-param>
        <param-name>org.glassfish.tyrus.maxSessionsPerApp</param-name>
        <param-value>500</param-value>
    </context-param>
</web-app>

            

                
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    <context-param>
        <param-name>org.glassfish.tyrus.maxSessionsPerRemoteAddr</param-name>
        <param-value>5</param-value>
    </context-param>
</web-app>

            

import jakarta.websocket.OnOpen;
import jakarta.websocket.Session;
import jakarta.websocket.server.ServerEndpoint;

import org.glassfish.tyrus.core.MaxSessions;

/**
 * Annotated endpoint.
 */
@MaxSessions(100)
@ServerEndpoint(value = "/limited-sessions-endpoint")
public static class LimitedSessionsEndpoint {
    @OnOpen
    public void onOpen(Session s) {
        ...
    }
    ...
}
                

TyrusServerEndpointConfig.Builder.create(LimitedSessionsEndpoint.class,
  "/limited-sessions-endpoint").maxSessions(100).build();
                

For server endpoints which is protected by HTTP authentication, Tyrus provides a mechanism to authenticate client. When client receives HTTP response status code401 - Unauthorized, then Tyrus extracts required scheme from WWW-Authenticate challenge. Then it chooses an authenticator from a map of registered authenticators and uses configuredcredentials. If no proper authenticator is found or credentials are missing, then AuthenticationException is thrown before the handshake can be done. There are implementations of the two most used authentication schemes in Tyrus: BASIC and DIGEST, but it is also possible to implement your own authenticator and register it with a configuration builder org.glassfish.tyrus.client.auth.AuthConfig.Builder or even to override default BASIC or DIGEST auth implementations. If no org.glassfish.tyrus.client.auth.AuthConfig client property is set, then default configuration is used. It is constructed as you can see bellow: BASIC and DIGEST internal implementations are enabled by default.

Please note that Basic Authentication scheme should be used over HTTPS connection only.

                    
  client.getProperties().put(ClientProperties.CREDENTIALS, new Credentials("ws_user", "password".getBytes(AuthConfig.CHARACTER_SET));
                    
                

                    
  AuthConfig authConfig = AuthConfig.Builder.create().build();
  ClientManager client = ClientManager.createClient();
  client.getProperties().put(ClientProperties.AUTH_CONFIG, authConfig);
                    
                

                
package org.glassfish.tyrus.client;

import java.net.URI;

/**
 * Http Authentication provider.
 * Class generates authorization token as a input for {@code Authorization} HTTP request header.
 *
 * @author Ondrej Kosatka (ondrej.kosatka at oracle.com)
 */
public abstract class Authenticator {

    /**
     * Generates authorization tokens as a input for {@code Authorization} HTTP request header.
     * @param uri URI is needed for generating authorization tokens for some authentication scheme (DIGEST: {@link DigestAuthenticator})
     * @param wwwAuthenticateHeader a value of header {@code WWW-Authenticate} from HTTP response.
     * @param credentials credentials.
     * @return generated {@link String} value of {@code Authorization}.
     * @throws AuthenticationException if is not possible to create auth token.
     */
    public abstract String generateAuthorizationHeader(final URI uri, final String wwwAuthenticateHeader, final Credentials credentials) throws AuthenticationException;

}
                
            

                    
  client.getProperties().put(ClientProperties.CREDENTIALS, new Credentials("ws_user", "password");
                    
                

                    
  AuthConfig authConfig = AuthConfig.Builder.create().
                               disableBasicAuth().
                               build();
  Credentials credentials = new Credentials("ws_user", "password");
  client.getProperties().put(ClientProperties.AUTH_CONFIG, authConfig);
  client.getProperties().put(ClientProperties.CREDENTIALS, credentials);
                    
                

                    
  AuthConfig authConfig = AuthConfig.Builder.create().
                               putAuthProvider("Digest", new MyOwnDigestAuthenticator()).
                               build();
  Credentials credentials = new Credentials("ws_user", "password");
  client.getProperties().put(ClientProperties.AUTH_CONFIG, authConfig);
  client.getProperties().put(ClientProperties.CREDENTIALS, credentials);
                
                

                    
  AuthConfig authConfig = AuthConfig.Builder.create().
                               disableBasicAuth().
                               putAuthProvider("NTLM", new MyOwnNTLMAuthenticator()).
                               build();
  Credentials credentials = new Credentials("ws_user", "password");
  client.getProperties().put(ClientProperties.AUTH_CONFIG, authConfig);
  client.getProperties().put(ClientProperties.CREDENTIALS, credentials);
                
                

Another Tyrus feature is HTTP redirect. If client received 3xx HTTP Redirect response code during a handshake and HTTP Redirect is allowed (by ClientProperty.REDIRECT_ENABLED property) then client engine transparently follows the URI contained in received HTTP response header Location and sends upgrade request to the new URI. Redirects can be chained up to limit set in ClientProperty.REDIRECT_THRESHOLD, whilst default value is 5. If HTTP redirect failed by any reason, RedirectException is thrown.

                    client.getProperties().put(ClientProperties.REDIRECT_ENABLED, true);
                

                    client.getProperties().put(ClientProperties.REDIRECT_THRESHOLD, 3);
                

Tyrus offers automatic handling of HTTP status code 503 - Service Unavailable, which can be returned from server when temporarily overloaded or down for maintenance. When Retry-After header is included in the response, client will parse the value and schedule another reconnect attempt.

This feature is disabled by default.

The implementation limits connection attempts to 5, each with reconnect delay not bigger than 300 seconds. Other values or conditions can be handled by custom ReconnectHandler (see RetryAfterException).

                    
            final ClientManager client = ClientManager.createClient();
            client.getProperties().put(ClientProperties.RETRY_AFTER_SERVICE_UNAVAILABLE, true);