| /* |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| */ |
| |
| package javax.websocket; |
| |
| import java.util.Collections; |
| import java.util.HashMap; |
| import java.util.List; |
| import java.util.Map; |
| |
| /** |
| * The ClientEndpointConfig is a special kind of endpoint configuration object that contains web socket configuration |
| * information specific only to client endpoints. Developers deploying programmatic client endpoints can create |
| * instances of this configuration by using a ClientEndpointConfig.Builder. Developers can override some of the |
| * configuration operations by providing an implementation of ClientEndpointConfig.Configurator. |
| * |
| */ |
| public interface ClientEndpointConfig extends EndpointConfig { |
| |
| /** |
| * The ClientEndpointConfig.Builder is a class used for creating ClientEndpointConfig objects for the purposes of |
| * deploying a client endpoint. Here are some examples: Building a plain configuration with no encoders, decoders, |
| * subprotocols or extensions. ClientEndpointConfig cec = ClientEndpointConfig.Builder.create().build(); Building a |
| * configuration with no subprotocols and a custom configurator. |
| * <p/> |
| * <code> |
| * ClientEndpointConfig customCec = ClientEndpointConfig.Builder.create() |
| * .preferredSubprotocols(mySubprotocols) |
| * .configurator(new MyClientConfigurator()) |
| * .build(); |
| * </code> |
| * |
| */ |
| public static final class Builder { |
| |
| private Configurator configurator; |
| private List<String> preferredSubprotocols; |
| private List<Extension> extensions; |
| private List<Class<? extends Encoder>> encoders; |
| private List<Class<? extends Decoder>> decoders; |
| private Map<String, Object> userProperties = new HashMap<String, Object>(); |
| |
| /** |
| * Creates a new builder object with no subprotocols, extensions, encoders, decoders and a null configurator. |
| * |
| * @return a new builder object |
| */ |
| public static Builder create() { |
| return new Builder(); |
| } |
| |
| /** |
| * Builds a configuration object using the attributes set on this builder. |
| * |
| * @return a new configuration object |
| */ |
| public ClientEndpointConfig build() { |
| if (decoders == null) |
| decoders = Collections.emptyList(); |
| if (encoders == null) |
| encoders = Collections.emptyList(); |
| if (extensions == null) |
| extensions = Collections.emptyList(); |
| if (preferredSubprotocols == null) |
| preferredSubprotocols = Collections.emptyList(); |
| |
| return new ClientEndpointConfig() { |
| |
| @Override |
| public List<Class<? extends Encoder>> getEncoders() { |
| return encoders; |
| } |
| |
| @Override |
| public List<Class<? extends Decoder>> getDecoders() { |
| return decoders; |
| } |
| |
| @Override |
| public Map<String, Object> getUserProperties() { |
| return userProperties; |
| } |
| |
| @Override |
| public List<String> getPreferredSubprotocols() { |
| return preferredSubprotocols; |
| } |
| |
| @Override |
| public List<Extension> getExtensions() { |
| return extensions; |
| } |
| |
| @Override |
| public Configurator getConfigurator() { |
| return configurator; |
| } |
| |
| }; |
| } |
| |
| /** |
| * Sets the configurator object for the configuration this builder will build. |
| * |
| * @param clientEndpointConfigurator |
| * the configurator |
| * @return the builder instance |
| */ |
| public Builder configurator(Configurator clientEndpointConfigurator) { |
| this.configurator = clientEndpointConfigurator; |
| return this; |
| } |
| |
| /** |
| * Set the preferred sub protocols for the configuration this builder will build. The list is treated in order |
| * of preference, favorite first, that this client would like to use for its sessions. |
| * |
| * @param preferredSubprotocols |
| * the preferred subprotocol names. |
| * @return the builder instance |
| */ |
| public Builder preferredSubprotocols(List<String> preferredSubprotocols) { |
| this.preferredSubprotocols = preferredSubprotocols; |
| return this; |
| } |
| |
| /** |
| * Set the extensions for the configuration this builder will build. The list is treated in order of preference, |
| * favorite first, that the client would like to use for its sessions. |
| * |
| * @param extensions |
| * the extensions |
| * @return the builder instance |
| */ |
| public ClientEndpointConfig.Builder extensions(List<Extension> extensions) { |
| this.extensions = extensions; |
| return this; |
| } |
| |
| /** |
| * Assign the list of encoder implementation classes the client will use. |
| * |
| * @param encoders |
| * the encoder implementation classes |
| * @return the builder instance |
| */ |
| public Builder encoders(List<Class<? extends Encoder>> encoders) { |
| this.encoders = encoders; |
| return this; |
| } |
| |
| /** |
| * Assign the list of decoder implementation classes the client will use. |
| * |
| * @param decoders |
| * the decoder implementation classes |
| * @return the builder instance |
| */ |
| public Builder decoders(List<Class<? extends Decoder>> decoders) { |
| this.decoders = decoders; |
| return this; |
| } |
| } |
| |
| /** |
| * The Configurator class may be extended by developers who want to provide custom configuration algorithms, such as |
| * intercepting the opening handshake, or providing arbitrary methods and algorithms that can be accessed from each |
| * endpoint instance configured with this configurator. |
| * |
| */ |
| public static class Configurator { |
| |
| public Configurator() { |
| // no-op |
| } |
| |
| /** |
| * This method is called by the implementation after it has formulated the handshake request that will be used |
| * to initiate the connection to the server, but before it has sent any part of the request. This allows the |
| * developer to inspect and modify the handshake request headers prior to the start of the handshake |
| * interaction. |
| * |
| * @param headers |
| * the mutable map of handshake request headers the implementation is about to send to start the |
| * handshake interaction. |
| */ |
| public void beforeRequest(Map<String, List<String>> headers) { |
| // no-op |
| } |
| |
| /** |
| * This method is called by the implementation after it has received a handshake response from the server as a |
| * result of a handshake interaction it initiated. The developer may implement this method in order to inspect |
| * the returning handshake response. |
| * |
| * @param hr |
| * the handshake response sent by the server. |
| */ |
| public void afterResponse(HandshakeResponse hr) { |
| // no-op |
| } |
| } |
| |
| /** |
| * Return the ordered list of sub protocols a client endpoint would like to use, in order of preference, favorite |
| * first that this client would like to use for its sessions. This list is used to generate the |
| * Sec-WebSocket-Protocol header in the opening handshake for clients using this configuration. The first protocol |
| * name is the most preferred. See <a href="http://tools.ietf.org/html/rfc6455#section-4.1">Client Opening |
| * Handshake</a>. |
| * |
| * @return the list of the preferred subprotocols, the empty list if there are none |
| */ |
| List<String> getPreferredSubprotocols(); |
| |
| /** |
| * Return the extensions, in order of preference, favorite first, that this client would like to use for its |
| * sessions. These are the extensions that will be used to populate the Sec-WebSocket-Extensions header in the |
| * opening handshake for clients using this configuration. The first extension in the list is the most preferred |
| * extension. See <a href="http://tools.ietf.org/html/rfc6455#section-9.1">Negotiating Extensions</a>. |
| * |
| * @return the list of extensions, the empty list if there are none. |
| */ |
| List<Extension> getExtensions(); |
| |
| /** |
| * Return the custom configurator for this configuration. If the developer did not provide one, the platform default |
| * configurator is returned. |
| * |
| * @return the configurator in use with this configuration. |
| */ |
| ClientEndpointConfig.Configurator getConfigurator(); |
| } |