Table of Contents
List of Tables
List of Examples
javax.websocket.server.ServerApplicationConfig
This is user guide for Tyrus 1.0. We are trying to keep it up to date as we add new features. Please use also our API documentation linked from the Tyrus and Java API for WebSocket home pages as an additional source of information about Tyrus features and API. If you would like to contribute to the guide or have questions on things not covered in our docs, please contact us at users@tyrus.java.net.
Table of Contents
This chapter provides a quick introduction on how to get started building WebSocket services using Java API for WebSocket and Tyrus. The example described here presents how to implement simple websocket service as JavaEE web application that can be deployed on any servlet container supporting Servlet 3.1 and higher. It also discusses starting Tyrus in standalone mode.
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>
In this section we will create a simple server side websocket endpoint which will echo the received message back to the sender. We will deploy this endpoint on the container.
In Java API for WebSocket and Tyrus, there are two basic approaches how to create an endpoint - either annotated endpoint,
or programmatic endpoint.
By annotated endpoint we mean endpoint constructed by using annotations (javax.websocket.server.ServerEndpoint
for server endpoint and javax.websocket.ClientEndpoint
for client endpoint), like in
"Annotated Echo Endpoint".
Example 1.1. Annotated Echo Endpoint
@ServerEndpoint(value = "/echo") public class EchoEndpointAnnotated { @OnMessage public String onMessage(String message, Session session) { return message; } }
The functionality of the EchoEndpointAnnotated
is fairly simple - to send the received message
back to the sender. To turn a POJO (Plain Old Java Object) to WebSocket server endpoint, the annotation
@ServerEndpoint(value = "/echo")
needs to be put on the POJO - see line 1. The URI path of the endpoint
is "/echo"
. The annotation @OnMessage
- line 3 on the method public String
onMessage(String message, Session session)
indicates that this method
will be called whenever text message is received. On line 5 in this method the message is sent back to
the user by returning it from the message.
The application containing only the EchoEndpointAnnotated
class can be deployed to the container.
Let's create the client part of the application. The client part may be written in JavaScript or any
other technology supporting WebSockets. We will use Java API for WebSocket and Tyrus to demonstrate how to develop
programmatic client endpoint.
The following code is used as a client part to communicate with the EchoEndpoint
deployed on server
using Tyrus and Java API for WebSocket.
The example "Client Endpoint" utilizes the concept
of the programmatic endpoint. By programmatic endpoint we mean endpoint which is created by extending
class javax.websocket.Endpoint
.
The example is standalone java application which needs to depend on some Tyrus artifacts to work
correctly, see "Tyrus Standalone Mode".
In the example first the CountDownLatch
is initialized. It is needed as a bocking data
structure - on line 31 it either waits for 100 seconds, or until it gets counted down (line 22).
On line 9 the javax.websocket.ClientEndpointConfig
is created - we will need it later
to connect the endpoint to the server. On line 11 the org.glassfish.tyrus.client.ClientManager
is created. it implements the javax.websocket.WebSocketContainer
and is used to connect
to server. This happens on next line. The client endpoint functionality is contained in the
javax.websocket.Endpoint
lazy instantiation. In the onOpen
method new MessageHandler
is registered (the received message is just printed on the console and the latch is counted down). After
the registration the message is sent to tje servere (line 25).
Example 1.2. Client Endpoint
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(); } } }
Similarly to "Client Endpoint" the server registered endpoint may also be the programmatic one:
Example 1.3. Programmatic Echo Endpoint
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(); } } }); } }
The functionality of the EchoEndpointProgrammatic
is fairly simple - to send the received message back to the sender.
The programmatic server endpoint needs to extend javax.websocket.Endpoint
- line 1.
Mehod public void onOpen(final Session session, EndpointConfig config)
gets called once new
connection to this endpoin0t is opened. In this method the MessageHandler
is registered to the
javax.websocket.Session
instance, which opened the connection. Method public void
onMessage(String message)
gets called once the message is received. On line 8 the message
is sent back to the sender.
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.
To use Tyrus in standalone mode it is necessary to depend on correct Tyrus artifacts. The following artifacts need to be added to your pom to use Tyrus:
<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>
Let's use the very same example like for Java API for WebSocket and deploy the EchoEndpointAnnotated
on the
standalone Tyrus server on the hostname "localhost", port 8025 and path "/websocket", so the endpoint
will be available at address "ws://localhost:8025/websockets/echo".
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(); } }
Tyrus is built, assembled and installed using Maven. Tyrus is deployed to maven.org maven repository at the following location: http://search.maven.org/. Jars, jar sources, jar javadoc and samples are all available on the java.net maven repository.
All Tyrus components are built using Java SE 7 compiler. It means, you will also need at least Java SE 7 to be able to compile and run your application. Developers using maven are likely to find it easier to include and manage dependencies of their applications than developers using ant or other build technologies. The following table provides an overview of all Tyrus modules and their dependencies with links to the respective binaries.
Table 2.1. Tyrus modules and dependencies
Module | Dependencies | Description |
---|---|---|
Core | ||
tyrus-server | Basic server functionality | |
tyrus-core | Core Tyrus functionality | |
tyrus-client | Basic client functionality | |
tyrus-documentation | Project documentation | |
tyrus-websocket-core | The WebSocket protocol | |
tyrus-samples | Samples of using Java API for WebSocket and Tyrus | |
tyrus-spi | SPI | |
Containers | ||
tyrus-container-glassfish-cdi | CDI support | |
tyrus-container-grizzly | Grizzly integration for Tyrus standalone server usage | |
tyrus-container-servlet | Servlet support for integration into web containers |
Table of Contents
Deploying WebSocket endpoints can be done in two ways. Either deploying via putting the endpoint in the WAR file, or using the ServerContainer methods to deploy the programmatic endpoint in the deployment phase.
The classes that are scanned for in WAR are the following ones:
Classes that implement the javax.websocket.ServerApplicationConfig
.
Classes annotated with javax.websocket.server.ServerEndpoint
.
Classes that extend javax.websocket.Endpoint
.
javax.websocket.server.ServerEndpoint
or extending javax.websocket.Endpoint
).
Let's have the following classes in the WAR:
Example 3.1. Deployment of WAR containing several classes extending javax.websocket.server.ServerApplicationConfig
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:
Example 3.2. Deployment of Annotated Endpoint Using ServerContainer
@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) { } }
Table of Contents
This chapter presents an overview of the core WebSocket API concepts - endpoints, configurations and message handlers.
The JAVA API for WebSocket specification draft can be found online here.
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.
Example 4.1. Echo sample server endpoint.
@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.
javax.websocket.server.ServerEndpoint has got one mandatory field - value and four optional fields. See the example below.
Example 4.2. javax.websocket.server.ServerEndpoint with all fields specified
@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); } }
Denotes a relative URI path at which the server endpoint will be deployed. In the example
"javax.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 javax.websocket.server.PathParam
may be used on method parameter
of methods annotated with one of @OnOpen, @OnMessage, @OnError, @OnClose.
Example 4.3. Specifying URI path parameter
@ServerEndpoint("/users/{username}") public class UserEndpoint { @OnMessage public String getUser(String message, @PathParam("username") String userName) { ... } }
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.
SampleDecoder
in the following example decodes String message and produces
SampleType message - see decode method on line 4.
Example 4.4. SampleDecoder
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.
Example 4.5. SampleEncoder
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 String getNegotiatedSubprotocol(List<String> supported, List<String> requested)
allows the user to provide their own algorithm for selection of used subprotocol.
public List<Extension> getNegotiatedExtensions(List<Extension> installed, List<Extension> requested)
allows the user to provide their own algorithm for selection of used Extensions.
public boolean checkOrigin(String originHeaderValue)
.
allows the user to specify the origin checking algorithm.
public void modifyHandshake(ServerEndpointConfig sec, HandshakeRequest request, HandshakeResponse response)
.
allows the user to modify the handshake response that will be sent back to the client.
public <T> T getEndpointInstance(Class<T> endpointClass) throws InstantiationException
.
allows the user to provide the way how the instance of an Endpoint is created
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 } }
The @ClientEndpoint class-level annotation is used to turn a POJO into WebSocket client endpoint. In the following sample the client sends text message "Hello!" and prints out each received message.
Example 4.6. SampleClientEndpoint
@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)); } }
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.
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 } }
This annotation may be used on certain methods of @ServerEndpoint or @ClientEndpoint, but only once per endpoint. It is used to decorate a method which is called once new connection is established. The connection is represented by the optional Session parameter. The other optional parameter is EndpointConfig, which represents the passed configuration object. Note that the EndpointConfig allows the user to access the user properties.
Example 4.7. @OnOpen with Session and EndpointConfig parameters.
@ServerEndpoint("/sample") public class EchoEndpoint { private Map<String, Object> properties; @OnOpen public void onOpen(Session session, EndpointConfig config) throws IOException { session.getBasicRemote().sendText("onOpen"); properties = config.getUserProperties(); } }
This annotation may be used on any method of @ServerEndpoint or @ClientEndpoint, but only once per endpoint. It is used to decorate a method which is called once the connection is being closed. The method may have one Session parameter, one CloseReason parameter and parameters annotated with @PathParam.
Example 4.8. @OnClose with Session and CloseReason parameters.
@ServerEndpoint("/sample") public class EchoEndpoint { @OnClose public void onClose(Session session, CloseReason reason) throws IOException { //prepare the endpoint for closing. } }
This annotation may be used on any method of @ServerEndpoint or @ClientEndpoint, but only once per endpoint. It is used to decorate a method which is called once Exception is being thrown by any method annotated with @OnOpen, @OnMessage and @OnClose. The method may have optional Session parameter and Throwable parameters.
Example 4.9. @OnError with Session and Throwable parameters.
@ServerEndpoint("/sample") public class EchoEndpoint { @OnError public void onError(Session session, Throwable t) { t.printStackTrace(); } }
This annotation may be used on certain methods of @ServerEndpoint or @ClientEndpoint, but only once per endpoint. It is used to decorate a method which is called once new message is received.
Example 4.10. @OnError with Session and Throwable parameters.
@ServerEndpoint("/sample") public class EchoEndpoint { @OnMessage public void onMessage(Session session, Throwable t) { t.printStackTrace(); } }
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:
Example 4.11. MessageHandler basic example
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:
java.lang.String
java.io.Reader
any developer object for which there is a corresponding javax.websocket.Decoder.Text or javax.websocket.Decoder.TextStream.
The binary messages will be processed by MessageHandlers with the following types:
java.nio.ByteBuffer
java.io.InputStream
any developer object for which there is a corresponding javax.websocket.Decoder.Binary or javax.websocket.Decoder.BinaryStream.
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.
Table of Contents
javax.websocket.server.ServerEndpointConfig
and javax.websocket.ClientEndpointConfig
objects
are used to provide the user the ability to configure websocket endpoints. Both server and client endpoints have some
part of configuration in common, namely encoders, decoders, and user properties. The user properties may developers
use to store the application specific data. For the developer's convenience the builders are provided for both
ServerEndpointConfig and ClientEndpointConfig.
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.
Example 5.1. Configuration for EchoEndpoint Deployment
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:
Example 5.2. ServerEndpointConfigu built using Builder
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 EndpointConfig
class, 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:
Example 5.3. ClientEndpointConfig built using Builder
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();
Table of Contents
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:
public void onOpen(Session session, EndpointConfig config)
public void onClose(Session session, CloseReason closeReason)
public void onError(Session session, Throwable thr)
The javax.websocket.Session
instance is passed by Tyrus to the user in the methods
annotated by following annotations for annotated endpoints:
method annotated with javax.websocket.OnOpen
method annotated with javax.websocket.OnMessage
method annotated with javax.websocket.OnClose
method annotated with javax.websocket.OnError
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
.
Example 6.1. Lifecycle echo sample
@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.
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:
Example 6.3. Sending message via RemoteEndpoint.Basic instance
@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
.
is used to send synchronous messages The point of completion of the send is defined when all the supplied
data has been written to the underlying connection. The methods for sending messages on the
javax.websocket.RemoteEndpoint$Basic
block until this point of completion is reached, except for
javax.websocket.RemoteEndpoint$Basic#getSendStream()
and
javax.websocket.RemoteEndpoint$Basic#getSendWriter()
which present traditional blocking I/O streams
to write messages. See the example
"Sending message via RemoteEndpoint.Basic instance"
to see how the whole text message is send. The following example demonstrates a method which sends the
partial text method to the peer:
Example 6.4. Method for sending partial text message
public void sendPartialTextMessage(String message, Boolean isLast, Session session){ try { session.getBasicRemote().sendText(message, isLast); } catch (IOException e) { e.printStackTrace(); } }
This representation of the peer of a web socket conversation has the ability to send messages asynchronously. The point of completion of the send is defined when all the supplied data has been written to the underlying connection. The completion handlers for the asynchronous methods are always called with a different thread from that which initiated the send.
Example 6.5. Sending mesage the async way using Future
public void sendWholeAsyncMessage(String message, Session session){ Future<Void> future = session.getAsyncRemote().sendText(message); }