Java tutorial
/* * 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.Closeable; import java.io.IOException; import java.net.URI; import java.security.Principal; import java.util.List; import java.util.Map; import java.util.Set; public interface Session extends Closeable { /** * Get the container that created this session. * @return the container that created this session. */ WebSocketContainer getContainer(); /** * Registers a {@link MessageHandler} for incoming messages. Only one * {@link MessageHandler} may be registered for each message type (text, * binary, pong). The message type will be derived at runtime from the * provided {@link MessageHandler} instance. It is not always possible to do * this so it is better to use * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Partial)} * or * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Whole)}. * * @param handler The message handler for a incoming message * * @throws IllegalStateException If a message handler has already been * registered for the associated message type */ void addMessageHandler(MessageHandler handler) throws IllegalStateException; Set<MessageHandler> getMessageHandlers(); void removeMessageHandler(MessageHandler listener); String getProtocolVersion(); String getNegotiatedSubprotocol(); List<Extension> getNegotiatedExtensions(); boolean isSecure(); boolean isOpen(); /** * Get the idle timeout for this session. * @return The current idle timeout for this session in milliseconds. Zero * or negative values indicate an infinite timeout. */ long getMaxIdleTimeout(); /** * Set the idle timeout for this session. * @param timeout The new idle timeout for this session in milliseconds. * Zero or negative values indicate an infinite timeout. */ void setMaxIdleTimeout(long timeout); /** * Set the current maximum buffer size for binary messages. * @param max The new maximum buffer size in bytes */ void setMaxBinaryMessageBufferSize(int max); /** * Get the current maximum buffer size for binary messages. * @return The current maximum buffer size in bytes */ int getMaxBinaryMessageBufferSize(); /** * Set the maximum buffer size for text messages. * @param max The new maximum buffer size in characters. */ void setMaxTextMessageBufferSize(int max); /** * Get the maximum buffer size for text messages. * @return The maximum buffer size in characters. */ int getMaxTextMessageBufferSize(); RemoteEndpoint.Async getAsyncRemote(); RemoteEndpoint.Basic getBasicRemote(); /** * Provides a unique identifier for the session. This identifier should not * be relied upon to be generated from a secure random source. * @return A unique identifier for the session. */ String getId(); /** * Close the connection to the remote end point using the code * {@link javax.websocket.CloseReason.CloseCodes#NORMAL_CLOSURE} and an * empty reason phrase. * * @throws IOException if an I/O error occurs while the WebSocket session is * being closed. */ @Override void close() throws IOException; /** * Close the connection to the remote end point using the specified code * and reason phrase. * @param closeReason The reason the WebSocket session is being closed. * * @throws IOException if an I/O error occurs while the WebSocket session is * being closed. */ void close(CloseReason closeReason) throws IOException; URI getRequestURI(); Map<String, List<String>> getRequestParameterMap(); String getQueryString(); Map<String, String> getPathParameters(); Map<String, Object> getUserProperties(); Principal getUserPrincipal(); /** * Obtain the set of open sessions associated with the same local endpoint * as this session. * * @return The set of currently open sessions for the local endpoint that * this session is associated with. */ Set<Session> getOpenSessions(); /** * Registers a {@link MessageHandler} for partial incoming messages. Only * one {@link MessageHandler} may be registered for each message type (text * or binary, pong messages are never presented as partial messages). * * @param <T> The type of message that the given handler is intended * for * @param clazz The Class that implements T * @param handler The message handler for a incoming message * * @throws IllegalStateException If a message handler has already been * registered for the associated message type * * @since WebSocket 1.1 */ <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler) throws IllegalStateException; /** * Registers a {@link MessageHandler} for whole incoming messages. Only * one {@link MessageHandler} may be registered for each message type (text, * binary, pong). * * @param <T> The type of message that the given handler is intended * for * @param clazz The Class that implements T * @param handler The message handler for a incoming message * * @throws IllegalStateException If a message handler has already been * registered for the associated message type * * @since WebSocket 1.1 */ <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler) throws IllegalStateException; }