| /* |
| * 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.io.IOException; |
| import java.net.URI; |
| import java.util.Set; |
| |
| /** |
| * A WebSocketContainer is an implementation provided object that provides applications a view on the container running |
| * it. The WebSocketContainer container various configuration parameters that control default session and buffer |
| * properties of the endpoints it contains. It also allows the developer to deploy websocket client endpoints by |
| * initiating a web socket handshake from the provided endpoint to a supplied URI where the peer endpoint is presumed to |
| * reside. |
| * <p/> |
| * A WebSocketContainer may be accessed by concurrent threads, so implementations must ensure the integrity of its |
| * mutable attributes in such circumstances. |
| */ |
| public interface WebSocketContainer { |
| |
| /** |
| * Return the number of milliseconds the implementation will timeout attempting to send a websocket message for all |
| * RemoteEndpoints associated with this container. A non-positive number indicates the implementation will not |
| * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each |
| * RemoteEndpoint. |
| * |
| * @return the timeout time in milliseconds. |
| */ |
| long getDefaultAsyncSendTimeout(); |
| |
| /** |
| * Sets the number of milliseconds the implementation will timeout attempting to send a websocket message for all |
| * RemoteEndpoints associated with this container. A non-positive number indicates the implementation will not |
| * timeout attempting to send a websocket message asynchronously. Note this default may be overridden in each |
| * RemoteEndpoint. |
| * |
| * @param timeoutmillis |
| */ |
| void setAsyncSendTimeout(long timeoutmillis); |
| |
| /** |
| * Connect the supplied annotated endpoint instance to its server. The supplied object must be a class decorated |
| * with the class level ServerEndpoint annotation. This method blocks until the connection is established, or throws |
| * an error if either the connection could not be made or there was a problem with the supplied endpoint class. If |
| * the developer uses this method to deploy the client endpoint, services like dependency injection that are |
| * supported, for example, when the implementation is part of the Java EE platform may not be available. If the |
| * client endpoint uses dependency injection, use connectToServer(java.lang.Class, java.net.URI) instead. |
| * |
| * @param annotatedEndpointInstance |
| * the annotated websocket client endpoint instance. |
| * @param path |
| * the complete path to the server endpoint. |
| * @return the Session created if the connection is successful. |
| * @throws DeploymentException |
| * if the annotated endpoint instance is not valid. |
| * @throws IOException |
| * if there was a network or protocol problem that prevented the client endpoint being connected to its |
| * server. |
| * @throws IllegalStateException |
| * if called during the deployment phase of the containing application. |
| */ |
| Session connectToServer(Object annotatedEndpointInstance, URI path) throws DeploymentException, IOException; |
| |
| /** |
| * Connect the supplied annotated endpoint to its server. The supplied object must be a class decorated with the |
| * class level ServerEndpoint annotation. This method blocks until the connection is established, or throws an error |
| * if either the connection could not be made or there was a problem with the supplied endpoint class. |
| * |
| * @param annotatedEndpointClass |
| * the annotated websocket client endpoint. |
| * @param path |
| * the complete path to the server endpoint. |
| * @return the Session created if the connection is successful. |
| * @throws DeploymentException |
| * if the class is not a valid annotated endpoint class. |
| * @throws IOException |
| * if there was a network or protocol problem that prevented the client endpoint being connected to its |
| * server. |
| * @throws IllegalStateException |
| * if called during the deployment phase of the containing application. |
| */ |
| Session connectToServer(Class<?> annotatedEndpointClass, URI path) throws DeploymentException, IOException; |
| |
| /** |
| * Connect the supplied programmatic client endpoint instance to its server with the given configuration. This |
| * method blocks until the connection is established, or throws an error if the connection could not be made. If the |
| * developer uses this method to deploy the client endpoint, services like dependency injection that are supported, |
| * for example, when the implementation is part of the Java EE platform may not be available. If the client endpoint |
| * uses dependency injection, use connectToServer(java.lang.Class, javax.websocket.ClientEndpointConfig, |
| * java.net.URI) instead. |
| * |
| * @param endpointInstance |
| * the programmatic client endpoint instance Endpoint. |
| * @param cec |
| * the configuration used to configure the programmatic endpoint. |
| * @param path |
| * the complete path to the server endpoint. |
| * @return the Session created if the connection is successful. |
| * @throws DeploymentException |
| * if the configuration is not valid |
| * @throws IOException |
| * if there was a network or protocol problem that prevented the client endpoint being connected to its |
| * server |
| * @throws IllegalStateException |
| * if called during the deployment phase of the containing application. |
| */ |
| Session connectToServer(Endpoint endpointInstance, ClientEndpointConfig cec, URI path) throws DeploymentException, |
| IOException; |
| |
| /** |
| * Connect the supplied programmatic endpoint to its server with the given configuration. This method blocks until |
| * the connection is established, or throws an error if the connection could not be made. |
| * |
| * @param endpointClass |
| * the programmatic client endpoint class Endpoint. |
| * @param cec |
| * the configuration used to configure the programmatic endpoint. |
| * @param path |
| * the complete path to the server endpoint. |
| * @return the Session created if the connection is successful. |
| * @throws DeploymentException |
| * if the configuration is not valid |
| * @throws IOException |
| * if there was a network or protocol problem that prevented the client endpoint being connected to its |
| * server |
| * @throws IllegalStateException |
| * if called during the deployment phase of the containing application. |
| */ |
| Session connectToServer(Class<? extends Endpoint> endpointClass, ClientEndpointConfig cec, URI path) |
| throws DeploymentException, IOException; |
| |
| /** |
| * Return the default time in milliseconds after which any web socket sessions in this container will be closed if |
| * it has been inactive. A value that is 0 or negative indicates the sessions will never timeout due to inactivity. |
| * The value may be overridden on a per session basis using Session.setMaxIdleTimeout(long) |
| * |
| * @return the default number of milliseconds after which an idle session in this container will be closed |
| */ |
| long getDefaultMaxSessionIdleTimeout(); |
| |
| /** |
| * Sets the default time in milliseconds after which any web socket sessions in this container will be closed if it |
| * has been inactive. A value that is 0 or negative indicates the sessions will never timeout due to inactivity. The |
| * value may be overridden on a per session basis using Session.setMaxIdleTimeout(long) |
| * |
| * @param tmeout |
| * the maximum time in milliseconds. |
| */ |
| void setDefaultMaxSessionIdleTimeout(long tmeout); |
| |
| /** |
| * Returns the default maximum size of incoming binary message that this container will buffer. This default may be |
| * overridden on a per session basis using Session.setMaxBinaryMessageBufferSize(int) |
| * |
| * @return the maximum size of incoming binary message in number of bytes. |
| */ |
| int getDefaultMaxBinaryMessageBufferSize(); |
| |
| /** |
| * Sets the default maximum size of incoming binary message that this container will buffer. |
| * |
| * @param max |
| * the maximum size of binary message in number of bytes. |
| */ |
| void setDefaultMaxBinaryMessageBufferSize(int max); |
| |
| /** |
| * Returns the default maximum size of incoming text message that this container will buffer. This default may be |
| * overridden on a per session basis using Session.setMaxTextMessageBufferSize(int) |
| * |
| * @return the maximum size of incoming text message in number of bytes. |
| */ |
| int getDefaultMaxTextMessageBufferSize(); |
| |
| /** |
| * Sets the maximum size of incoming text message that this container will buffer. |
| * |
| * @param max |
| * the maximum size of text message in number of bytes. |
| */ |
| void setDefaultMaxTextMessageBufferSize(int max); |
| |
| /** |
| * Return the set of Extensions installed in the container. |
| * |
| * @return the set of extensions. |
| */ |
| Set<Extension> getInstalledExtensions(); |
| |
| } |