Java Reference
In-Depth Information
Consuming Messages
A server-side class can accept messages from clients by configuring it as a WebSocket endpoint. To develop a
WebSocket endpoint, you can utilize an annotation-based approach or an interface implementation approach.
To use annotations for creating a WebSocket server endpoint, create a Java “Plain Old Java Object” POJO, and
annotate it with
@ServerEndpoint
(
javax.websocket.server.ServerEndpoint)
. The
@ServerEndpoint
annotation
accepts a String-based path attribute, which is used to indicate the URI path at which the server is available to accept
client messages. Therefore, when the server is started, the specified path would be appended to the end of the
context path and application name in which the WebSocket resides. Additionally, a path may include one or more
string-based parameters after the server endpoint to pass additional parameters to subsequent method calls.
By initiating a call to that URL, a method annotated with
@OnMessage
(
javax.websocket.OnMessage
), will be invoked
to process the message that is sent, and any additional parameters may be accepted via the inclusion of the
@PathParam
annotation within the list of parameters for that method's signature. There are two other important methods within
a WebSocket server endpoint, and those are the methods that are invoked when a connection is established and when
it is closed. The method that is to be invoked when the connection has been established should be annotated with
@OnOpen
, whereas the method that is to be invoked when the connection is closed should be annotated with
@OnClose
.
Let's dive a bit deeper into the three important methods for implementing a WebSocket endpoint. Each of the
three methods can accept a number of optional parameters. To begin, it should be noted that each of the methods
accepts zero or more strings annotated with
@PathParam
. As mentioned previously, these parameters refer to strings
that have been appended to the WebService endpoint URI.
The
@OnMessage
method can accept the following three types of parameters:
javax.websocket.Session
•
@PathParam
•
any number of strings annotated with
•
the message itself
The
@OnOpen
method can accept the following three types of parameters:
•
javax.websocket.Session
EndpointConfig
instance (Contains metadata regarding the endpoint configuration)
•
an
@PathParam
Lastly, the
@OnClose
method can accept any of the following three types of parameters:
•
javax.websocket.Session
(Not accessible after the connection is closed)
•
javax.websocket.CloseReason
(Contains the reason why connection was closed)
•
any number of strings annotated with
@PathParam
In the example below, a class named
AcmeChatEndpoint
is annotated as a WebSocket, so it is accessible to
clients as an endpoint for receiving messages, and returning a response. When initiating communication with
the WebSocket endpoint, the client must utilize the URL that contains a scheme of “ws”, rather than “http”
(e.g.,
ws://localhost:8080/AppName/ServerEndpoint
). The “ws” URI scheme was introduced by the WebSocket
protocol, and as such, indicates that the URI is used for communication with a WebSocket. In this example, a client
can send a message to the server via the
AcmeChatEndpoint
WebSocket, and the server can send a message back at
the same time, because WebSockets allow for full-duplex communication, as opposed to half-duplex communication,
which is offered by HTTP. Full-duplex communication is an HTML5 standard, accomplishing similar functionality to
Asynchronous JavaScript and XML (AJAX), which utilizes a request-response communication.
In the following example, a simple POJO class, named
org.javaee7.chapter09.AcmeChatEndpoint
, is annotated
to indicate that it should be accessible via the web as a WebSocket endpoint. The class contains a method named
messageReceiver
, which is annotated with
@OnMessage
to make it accessible to a client as a callable message consumer.
•
any number of strings annotated with
