Chapter 5. Configurations

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();