Package: Endpoint

Endpoint

name	instruction	branch	complexity	line	method
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, 2022 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: * {@literal @}Override
53: * public void onOpen(Session session, EndpointConfig config) {
54: * final RemoteEndpoint.Basic remote = session.getBasicRemote();
55: * session.addMessageHandler(String.class, new MessageHandler.Whole<String>() {
56: * public void onMessage(String text) {
57: * try {
58: * remote.sendText("Got your message (" + text + "). Thanks !");
59: * } catch (IOException ioe) {
60: * // handle send failure here
61: * }
62: * }
63: * });
64: * }
65: *
66: * }
67: * </code>
68: * </pre>
69: *
70: * @author dannycoward
71: */
72: public abstract class Endpoint {
73:
74: /**
75: * Developers must implement this method to be notified when a new conversation has just begun.
76: * <p>
77: * Note:
78: * <ul>
79: * <li>It is permitted to send messages from this method.</li>
80: * <li>It is permitted to add {@link MessageHandler}s from this method. No messages will be
81: * mapped to the appropriate {@link MessageHandler} until this method has completed.</li>
82: * </ul>
83: *
84: * @param session the session that has just been activated.
85: * @param config the configuration used to configure this endpoint.
86: */
87: public abstract void onOpen(Session session, EndpointConfig config);
88:
89: /**
90: * This method is called immediately prior to the session with the remote peer being closed. It is called whether
91: * the session is being closed because the remote peer initiated a close and sent a close frame, or whether the
92: * local websocket container or this endpoint requests to close the session. The developer may take this last
93: * opportunity to retrieve session attributes such as the ID, or any application data it holds before it becomes
94: * unavailable after the completion of the method. Developers should not attempt to modify the session from within
95: * this method, or send new messages from this call as the underlying connection will not be able to send them at
96: * this stage.
97: *
98: * @param session the session about to be closed.
99: * @param closeReason the reason the session was closed.
100: */
101: public void onClose(Session session, CloseReason closeReason) {
102: }
103:
104: /**
105: * Developers may implement this method when the web socket session creates some kind of error that is not modeled
106: * in the web socket protocol. This may for example be a notification that an incoming message is too big to handle,
107: * or that the incoming message could not be encoded.
108: *
109: * <p>
110: * There are a number of categories of exception that this method is (currently) defined to handle:
111: * <ul>
112: * <li>connection problems, for example, a socket failure that occurs before the web socket connection can be
113: * formally closed. These are modeled as {@link SessionException}s</li>
114: * <li>runtime errors thrown by developer created message handlers calls.</li>
115: * <li>conversion errors encoding incoming messages before any message handler has been called. These are modeled as
116: * {@link DecodeException}s</li>
117: * </ul>
118: *
119: * @param session the session in use when the error occurs.
120: * @param thr the throwable representing the problem.
121: */
122: public void onError(Session session, Throwable thr) {
123: }
124: }