Skip to content

Package: Endpoint

Endpoint

nameinstructionbranchcomplexitylinemethod
Endpoint()
M: 3 C: 0
0%
M: 0 C: 0
100%
M: 1 C: 0
0%
M: 1 C: 0
0%
M: 1 C: 0
0%
onClose(Session, CloseReason)
M: 1 C: 0
0%
M: 0 C: 0
100%
M: 1 C: 0
0%
M: 1 C: 0
0%
M: 1 C: 0
0%
onError(Session, Throwable)
M: 1 C: 0
0%
M: 0 C: 0
100%
M: 1 C: 0
0%
M: 1 C: 0
0%
M: 1 C: 0
0%

Coverage

1: /*
2: * Copyright (c) 2018, 2020 Oracle and/or its affiliates and others.
3: * All rights reserved.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package jakarta.websocket;
19:
20: /**
21: * The Web Socket Endpoint represents an object that can handle websocket conversations. Developers may extend this
22: * class in order to implement a programmatic websocket endpoint. The Endpoint class holds lifecycle methods that may be
23: * overridden to intercept websocket open, error and close events. By implementing the
24: * {@link Endpoint#onOpen(jakarta.websocket.Session, jakarta.websocket.EndpointConfig) onOpen} method, the programmatic
25: * endpoint gains access to the {@link Session} object, to which the developer may add {@link MessageHandler}
26: * implementations in order to intercept incoming websocket messages. Each instance of a websocket endpoint is
27: * guaranteed not to be called by more than one thread at a time per active connection.
28: *
29: * <p>
30: * If deployed as a client endpoint, it will be instantiated once for the single connection to the server.
31: *
32: * <p>
33: * When deployed as a server endpoint, the implementation uses the
34: * {@code jakarta.websocket.server.ServerEndpointConfig.Configurator#getEndpointInstance} method to obtain the endpoint
35: * instance it will use for each new client connection. If the developer uses the default
36: * {@code jakarta.websocket.server.ServerEndpointConfig.Configurator}, there will be precisely one endpoint instance per
37: * active client connection. Consequently, in this typical case, when implementing/overriding the methods of Endpoint,
38: * the developer is guaranteed that there will be at most one thread calling each endpoint instance at a time.
39: *
40: * <p>
41: * If the developer provides a custom {@code jakarta.websocket.server.ServerEndpointConfig.Configurator} which overrides
42: * the default policy for endpoint instance creation, for example, using a single Endpoint instance for multiple client
43: * connections, the developer may need to write code that can execute concurrently.
44: *
45: * <p>
46: * Here is an example of a simple endpoint that echoes any incoming text message back to the sender.
47: *
48: * <pre>
49: * <code>
50: * public class EchoServer extends Endpoint {
51: *
52: * public void onOpen(Session session, EndpointConfig config) {
53: * final RemoteEndpoint remote = session.getBasicRemote();
54: * session.addMessageHandler(String.class, new MessageHandler.Whole<String<() {
55: * public void onMessage(String text) {
56: * try {
57: * remote.sendString("Got your message (" + text + "). Thanks !");
58: * } catch (IOException ioe) {
59: * // handle send failure here
60: * }
61: * }
62: * });
63: * }
64: *
65: * }
66: * </code>
67: * </pre>
68: *
69: * @author dannycoward
70: */
71: public abstract class Endpoint {
72:
73: /**
74: * Developers must implement this method to be notified when a new conversation has just begun.
75: * <p>
76: * Note:
77: * <ul>
78: * <li>It is permitted to send messages from this method.</li>
79: * <li>It is permitted to add {@link MessageHandler}s from this method. No messages will be
80: * mapped to the appropriate {@link MessageHandler} until this method has completed.</li>
81: * </ul>
82: *
83: * @param session the session that has just been activated.
84: * @param config the configuration used to configure this endpoint.
85: */
86: public abstract void onOpen(Session session, EndpointConfig config);
87:
88: /**
89: * This method is called immediately prior to the session with the remote peer being closed. It is called whether
90: * the session is being closed because the remote peer initiated a close and sent a close frame, or whether the
91: * local websocket container or this endpoint requests to close the session. The developer may take this last
92: * opportunity to retrieve session attributes such as the ID, or any application data it holds before it becomes
93: * unavailable after the completion of the method. Developers should not attempt to modify the session from within
94: * this method, or send new messages from this call as the underlying connection will not be able to send them at
95: * this stage.
96: *
97: * @param session the session about to be closed.
98: * @param closeReason the reason the session was closed.
99: */
100: public void onClose(Session session, CloseReason closeReason) {
101: }
102:
103: /**
104: * Developers may implement this method when the web socket session creates some kind of error that is not modeled
105: * in the web socket protocol. This may for example be a notification that an incoming message is too big to handle,
106: * or that the incoming message could not be encoded.
107: *
108: * <p>
109: * There are a number of categories of exception that this method is (currently) defined to handle:
110: * <ul>
111: * <li>connection problems, for example, a socket failure that occurs before the web socket connection can be
112: * formally closed. These are modeled as {@link SessionException}s</li>
113: * <li>runtime errors thrown by developer created message handlers calls.</li>
114: * <li>conversion errors encoding incoming messages before any message handler has been called. These are modeled as
115: * {@link DecodeException}s</li>
116: * </ul>
117: *
118: * @param session the session in use when the error occurs.
119: * @param thr the throwable representing the problem.
120: */
121: public void onError(Session session, Throwable thr) {
122: }
123: }