Chapter 4. WebSocket API Endpoints, Sessions and MessageHandlers

Denotes a relative URI path at which the server endpoint will be deployed. In the example "jakarta.websocket.server.ServerEndpoint with all fields specified", the Java class will be hosted at the URI path /sample. The field value must begin with a '/' and may or may not end in a '/', it makes no difference. Thus request URLs that end or do not end in a '/' will both be matched. WebSocket API for JAVA supports level 1 URI templates.

URI path templates are URIs with variables embedded within the URI syntax. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI. Variables are denoted by curly braces. For example, look at the following @ServerEndpoint annotation:

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

In this type of example, a user will be prompted to enter their name, and then a Tyrus web service configured to respond to requests to this URI path template will respond. For example, if the user entered their username as "Galileo", the web service will respond to the following URL: http://example.com/users/Galileo

To obtain the value of the username variable the jakarta.websocket.server.PathParam may be used on method parameter of methods annotated with one of @OnOpen, @OnMessage, @OnError, @OnClose.

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

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

Contains list of classes that will be used to decode incoming messages for the endpoint. By decoding we mean transforming from text / binary websocket message to some user defined type. Each decoder needs to implement the Decoder interface.

SampleDecoder in the following example decodes String message and produces SampleType message - see decode method on line 4.

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.
    }
}

Contains list of classes that will be used to encode outgoing messages. By encoding we mean transforming message from user defined type to text or binary type. Each encoder needs to implement the Encoder interface.

SampleEncoder in the following example decodes String message and produces SampleType message - see decode method on line 4.

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.
    }
}

List of names (Strings) of supported sub-protocols. The first protocol in this list that matches with sub-protocols provided by the client side is used.

Users may provide their own implementation of ServerEndpointConfiguration.Configurator. It allows them to control some algorithms used by Tyrus in the connection initialization phase:

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
    }
}

Contains list of classes that will be used decode incoming messages for the endpoint. By decoding we mean transforming from text / binary websocket message to some user defined type. Each decoder needs to implement the Decoder interface.

Contains list of classes that will be used to encode outgoing messages. By encoding we mean transforming message from user defined type to text or binary type. Each encoder needs to implement the Encoder interface.

List of names (Strings) of supported sub-protocols.

Users may provide their own implementation of ClientEndpointConfiguration.Configurator. It allows them to control some algorithms used by Tyrus in the connection initialization phase. Method beforeRequest allows the user to change the request headers constructed by Tyrus. Method afterResponse allows the user to process the handshake response.

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
    }
}