Package: ClientEndpointConfig$Configurator

ClientEndpointConfig$Configurator

name	instruction	branch	complexity	line	method
ClientEndpointConfig.Configurator()	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%
afterResponse(HandshakeResponse)	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%
beforeRequest(Map)	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, 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.util.ArrayList;
21: import java.util.Collections;
22: import java.util.List;
23: import java.util.Map;
24:
25: import javax.net.ssl.SSLContext;
26:
27: /**
28: * The ClientEndpointConfig is a special kind of endpoint configuration object that contains web socket configuration
29: * information specific only to client endpoints. Developers deploying programmatic client endpoints can create
30: * instances of this configuration by using a {@link ClientEndpointConfig.Builder}. Developers can override some of the
31: * configuration operations by providing an implementation of {@link ClientEndpointConfig.Configurator}.
32: *
33: * @author dannycoward
34: */
35: public interface ClientEndpointConfig extends EndpointConfig {
36:
37: /**
38: * Return the ordered list of sub protocols a client endpoint would like to use, in order of preference, favorite
39: * first that this client would like to use for its sessions. This list is used to generate the
40: * Sec-WebSocket-Protocol header in the opening handshake for clients using this configuration. The first protocol
41: * name is the most preferred. See <a href="http://tools.ietf.org/html/rfc6455#section-4.1">Client Opening
42: * Handshake</a>.
43: *
44: * @return the list of the preferred subprotocols, the empty list if there are none
45: */
46: List<String> getPreferredSubprotocols();
47:
48: /**
49: * Return the extensions, in order of preference, favorite first, that this client would like to use for its
50: * sessions. These are the extensions that will be used to populate the Sec-WebSocket-Extensions header in the
51: * opening handshake for clients using this configuration. The first extension in the list is the most preferred
52: * extension. See <a href="http://tools.ietf.org/html/rfc6455#section-9.1">Negotiating Extensions</a>.
53: *
54: * @return the list of extensions, the empty list if there are none.
55: */
56: List<Extension> getExtensions();
57:
58: /**
59: * Return the SSLContext to be used to establish a WebSocket (wss) connection to the server. The SSLContext will
60: * have initialised. For insecure WebSocket (ws) connections, this will be {@code null}. If there is an existing
61: * connection to the server that uses the same SSLContext and that connection supports multiplexing WebSocket
62: * connections then the container may choose to re-use that connection rather than creating a new one. Containers
63: * may provide container specific configuration to control this behaviour.
64: *
65: * @return the SSLContext to use to establish a secure connection to the server or {@code null} if an insecure
66: * connection should be established
67: */
68: SSLContext getSSLContext();
69:
70: /**
71: * Return the custom configurator for this configuration. If the developer did not provide one, the platform default
72: * configurator is returned.
73: *
74: * @return the configurator in use with this configuration.
75: */
76: public ClientEndpointConfig.Configurator getConfigurator();
77:
78: /**
79: * The Configurator class may be extended by developers who want to provide custom configuration algorithms, such as
80: * intercepting the opening handshake, or providing arbitrary methods and algorithms that can be accessed from each
81: * endpoint instance configured with this configurator.
82: *
83: */
84: public class Configurator {
85:
86: /**
87: * This method is called by the implementation after it has formulated the handshake request that will be used
88: * to initiate the connection to the server, but before it has sent any part of the request. This allows the
89: * developer to inspect and modify the handshake request headers prior to the start of the handshake
90: * interaction.
91: *
92: * @param headers the mutable map of handshake request headers the implementation is about to send to start the
93: * handshake interaction.
94: */
95: public void beforeRequest(Map<String, List<String>> headers) {
96:
97: }
98:
99: /**
100: * This method is called by the implementation after it has received a handshake response from the server as a
101: * result of a handshake interaction it initiated. The developer may implement this method in order to inspect
102: * the returning handshake response.
103: *
104: * @param hr the handshake response sent by the server.
105: */
106: public void afterResponse(HandshakeResponse hr) {
107:
108: }
109: }
110:
111: /**
112: * The ClientEndpointConfig.Builder is a class used for creating {@link ClientEndpointConfig} objects for the
113: * purposes of deploying a client endpoint. Here are some examples: Building a plain configuration with no encoders,
114: * decoders, subprotocols or extensions. <code>
115: * ClientEndpointConfig cec = ClientEndpointConfig.Builder.create().build();
116: * </code>
117: *
118: * Building a configuration with no subprotocols and a custom configurator.
119: *
120: * <pre>
121: * <code>
122: * ClientEndpointConfig customCec = ClientEndpointConfig.Builder.create()
123: * .preferredSubprotocols(mySubprotocols)
124: * .configurator(new MyClientConfigurator())
125: * .build();
126: * </code>
127: * </pre>
128: *
129: *
130: * @author dannycoward
131: */
132: public final class Builder {
133: private List<String> preferredSubprotocols = Collections.emptyList();
134: private List<Extension> extensions = Collections.emptyList();
135: private List<Class<? extends Encoder>> encoders = Collections.emptyList();
136: private List<Class<? extends Decoder>> decoders = Collections.emptyList();
137: private SSLContext sslContext = null;
138: private ClientEndpointConfig.Configurator clientEndpointConfigurator = new ClientEndpointConfig.Configurator() {
139:
140: };
141:
142: // use create()
143: private Builder() {
144: }
145:
146: /**
147: * Creates a new builder object with no subprotocols, extensions, encoders, decoders and a {@code null}
148: * configurator.
149: *
150: * @return a new builder object.
151: */
152: public static ClientEndpointConfig.Builder create() {
153: return new ClientEndpointConfig.Builder();
154: }
155:
156: /**
157: * Builds a configuration object using the attributes set on this builder.
158: *
159: * @return a new configuration object.
160: */
161: public ClientEndpointConfig build() {
162: return new DefaultClientEndpointConfig(this.preferredSubprotocols, this.extensions, this.encoders,
163: this.decoders, this.sslContext, this.clientEndpointConfigurator);
164: }
165:
166: /**
167: * Sets the configurator object for the configuration this builder will build.
168: *
169: * @param clientEndpointConfigurator the configurator
170: * @return the builder instance
171: */
172: public ClientEndpointConfig.Builder configurator(ClientEndpointConfig.Configurator clientEndpointConfigurator) {
173: this.clientEndpointConfigurator = clientEndpointConfigurator;
174: return this;
175: }
176:
177: /**
178: * Set the preferred sub protocols for the configuration this builder will build. The list is treated in order
179: * of preference, favorite first, that this client would like to use for its sessions.
180: *
181: * @param preferredSubprotocols the preferred subprotocol names.
182: * @return the builder instance
183: */
184: public ClientEndpointConfig.Builder preferredSubprotocols(List<String> preferredSubprotocols) {
185: this.preferredSubprotocols = (preferredSubprotocols == null) ? new ArrayList<>()
186: : preferredSubprotocols;
187: return this;
188: }
189:
190: /**
191: * Set the extensions for the configuration this builder will build. The list is treated in order of preference,
192: * favorite first, that the client would like to use for its sessions.
193: *
194: * @param extensions the extensions
195: * @return the builder instance
196: */
197: public ClientEndpointConfig.Builder extensions(List<Extension> extensions) {
198: this.extensions = (extensions == null) ? new ArrayList<>() : extensions;
199: return this;
200: }
201:
202: /**
203: * Assign the list of encoder implementation classes the client will use.
204: *
205: * @param encoders the encoder implementation classes
206: * @return the builder instance
207: */
208: public ClientEndpointConfig.Builder encoders(List<Class<? extends Encoder>> encoders) {
209: this.encoders = (encoders == null) ? new ArrayList<>() : encoders;
210: return this;
211: }
212:
213: /**
214: * Assign the list of decoder implementation classes the client will use.
215: *
216: * @param decoders the decoder implementation classes
217: * @return this builder instance
218: */
219: public ClientEndpointConfig.Builder decoders(List<Class<? extends Decoder>> decoders) {
220: this.decoders = (decoders == null) ? new ArrayList<>() : decoders;
221: return this;
222: }
223:
224: /**
225: * Assign the SSLContext to be used when connection to the WebSocket server. If there is an existing connection
226: * to the server that uses the same SSLContext and that connection supports multiplexing WebSocket connections
227: * then the container may choose to re-use that connection rather than creating a new one. Containers may
228: * provide container specific configuration to control this behaviour.
229: *
230: * @param sslContext The SSLContext which must be initialised for secure WebSocket (wss) connections or
231: * {@code null} for insecure WebSocket (ws) connections.
232: * @return this builder instance
233: */
234: public ClientEndpointConfig.Builder sslContext(SSLContext sslContext) {
235: this.sslContext = sslContext;
236: return this;
237: }
238: }
239: }