Package: WebSocketContainer

WebSocketContainer

Coverage

1: /*
2: * Copyright (c) 2018, 2021 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: import java.io.*;
21: import java.net.URI;
22: import java.util.Set;
23:
24: /**
25: * A WebSocketContainer is an implementation provided object that provides applications a view on the container running
26: * it. The WebSocketContainer container various configuration parameters that control default session and buffer
27: * properties of the endpoints it contains. It also allows the developer to deploy websocket client endpoints by
28: * initiating a web socket handshake from the provided endpoint to a supplied URI where the peer endpoint is presumed to
29: * reside.
30: *
31: * <p>
32: * A WebSocketContainer may be accessed by concurrent threads, so implementations must ensure the integrity of its
33: * mutable attributes in such circumstances.
34: *
35: * @author dannycoward
36: */
37: public interface WebSocketContainer {
38:
39: /**
40: * Return the number of milliseconds the implementation will timeout attempting to send a websocket message for all
41: * RemoteEndpoints associated with this container. A zero or negative value indicates the implementation will not
42: * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each
43: * RemoteEndpoint.
44: *
45: * @return the timeout time in milliseconds.
46: */
47: long getDefaultAsyncSendTimeout();
48:
49: /**
50: * Sets the number of milliseconds the implementation will timeout attempting to send a websocket message for all
51: * RemoteEndpoints associated with this container. A zero or negative value indicates the implementation will not
52: * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each
53: * RemoteEndpoint.
54: *
55: * @param timeoutmillis the timeout in milliseconds; use zero or negative value for no timeout
56: */
57: void setAsyncSendTimeout(long timeoutmillis);
58:
59: /**
60: * Connect the supplied annotated endpoint instance to its server. The supplied object must be a class decorated
61: * with the class level {@link jakarta.websocket.ClientEndpoint} annotation. This method blocks until the
62: * connection is established, or throws an error if either the connection could not be made or there was a problem
63: * with the supplied endpoint class. If the developer uses this method to deploy the client endpoint, services like
64: * dependency injection that are supported, for example, when the implementation is part of the Java EE platform may
65: * not be available. If the client endpoint uses dependency injection, use
66: * {@link WebSocketContainer#connectToServer(java.lang.Class, java.net.URI)} instead.
67: *
68: * @param annotatedEndpointInstance the annotated websocket client endpoint instance.
69: * @param path the complete path to the server endpoint.
70: * @return the Session created if the connection is successful.
71: * @throws DeploymentException if the annotated endpoint instance is not valid.
72: * @throws IOException if there was a network or protocol problem that prevented the client endpoint being
73: * connected to its server.
74: * @throws IllegalStateException if called during the deployment phase of the containing application.
75: */
76: Session connectToServer(Object annotatedEndpointInstance, URI path) throws DeploymentException, IOException;
77:
78: /**
79: * Connect the supplied annotated endpoint to its server. The supplied object must be a class decorated with the
80: * class level {@link jakarta.websocket.ClientEndpoint} annotation. This method blocks until the connection is
81: * established, or throws an error if either the connection could not be made or there was a problem with the
82: * supplied endpoint class.
83: *
84: * @param annotatedEndpointClass the annotated websocket client endpoint.
85: * @param path the complete path to the server endpoint.
86: * @return the Session created if the connection is successful.
87: * @throws DeploymentException if the class is not a valid annotated endpoint class.
88: * @throws IOException if there was a network or protocol problem that prevented the client endpoint being
89: * connected to its server.
90: * @throws IllegalStateException if called during the deployment phase of the containing application.
91: */
92: Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException;
93:
94: /**
95: * Connect the supplied programmatic client endpoint instance to its server with the given configuration. This
96: * method blocks until the connection is established, or throws an error if the connection could not be made. If the
97: * developer uses this method to deploy the client endpoint, services like dependency injection that are supported,
98: * for example, when the implementation is part of the Java EE platform may not be available. If the client endpoint
99: * uses dependency injection, use
100: * {@link WebSocketContainer#connectToServer(java.lang.Class, jakarta.websocket.ClientEndpointConfig, java.net.URI) }
101: * instead.
102: *
103: * @param endpointInstance the programmatic client endpoint instance {@link Endpoint}.
104: * @param path the complete path to the server endpoint.
105: * @param cec the configuration used to configure the programmatic endpoint.
106: * @return the Session created if the connection is successful.
107: * @throws DeploymentException if the configuration is not valid
108: * @throws IOException if there was a network or protocol problem that prevented the client endpoint being
109: * connected to its server
110: * @throws IllegalStateException if called during the deployment phase of the containing application.
111: */
112: Session connectToServer(Endpoint endpointInstance, ClientEndpointConfig cec, URI path)
113: throws DeploymentException, IOException;
114:
115: /**
116: * Connect the supplied programmatic endpoint to its server with the given configuration. This method blocks until
117: * the connection is established, or throws an error if the connection could not be made.
118: *
119: * @param endpointClass the programmatic client endpoint class {@link Endpoint}.
120: * @param path the complete path to the server endpoint.
121: * @param cec the configuration used to configure the programmatic endpoint.
122: * @return the Session created if the connection is successful.
123: * @throws DeploymentException if the configuration is not valid
124: * @throws IOException if there was a network or protocol problem that prevented the client endpoint being
125: * connected to its server
126: * @throws IllegalStateException if called during the deployment phase of the containing application.
127: */
128: Session connectToServer(Class<? extends Endpoint> endpointClass, ClientEndpointConfig cec, URI path)
129: throws DeploymentException, IOException;
130:
131: /**
132: * Return the default time in milliseconds after which any web socket sessions in this container will be closed if
133: * it has been inactive. A value that is zero or negative indicates the sessions will never timeout due to inactivity.
134: * The value may be overridden on a per session basis using {@link Session#setMaxIdleTimeout(long) }
135: *
136: * @return the default number of milliseconds after which an idle session in this container will be closed
137: */
138: long getDefaultMaxSessionIdleTimeout();
139:
140: /**
141: * Sets the default time in milliseconds after which any web socket sessions in this container will be closed if it
142: * has been inactive. A value that is zero or negative indicates the sessions will never timeout due to inactivity. The
143: * value may be overridden on a per session basis using {@link Session#setMaxIdleTimeout(long) }
144: *
145: * @param timeout the maximum time in milliseconds; use zero or negative value for no timeout
146: */
147: void setDefaultMaxSessionIdleTimeout(long timeout);
148:
149: /**
150: * Returns the default maximum size of incoming binary message that this container will buffer. This default may be
151: * overridden on a per session basis using {@link Session#setMaxBinaryMessageBufferSize(int) }
152: *
153: * @return the maximum size of incoming binary message in number of bytes.
154: */
155: int getDefaultMaxBinaryMessageBufferSize();
156:
157: /**
158: * Sets the default maximum size of incoming binary message that this container will buffer.
159: *
160: * @param max the maximum size of binary message in number of bytes.
161: */
162: void setDefaultMaxBinaryMessageBufferSize(int max);
163:
164: /**
165: * Returns the default maximum size of incoming text message that this container will buffer. This default may be
166: * overridden on a per session basis using {@link Session#setMaxTextMessageBufferSize(int) }
167: *
168: * @return the maximum size of incoming text message in number of bytes.
169: */
170: int getDefaultMaxTextMessageBufferSize();
171:
172: /**
173: * Sets the maximum size of incoming text message that this container will buffer.
174: *
175: * @param max the maximum size of text message in number of bytes.
176: */
177: void setDefaultMaxTextMessageBufferSize(int max);
178:
179: /**
180: * Return the set of Extensions installed in the container.
181: *
182: * @return the set of extensions.
183: */
184: Set<Extension> getInstalledExtensions();
185: }