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