/*
* 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();
}