xref: /unit/src/java/javax/websocket/Session.java (revision 1157:7ae152bda303)
1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements.  See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License.  You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package javax.websocket;
18 
19 import java.io.Closeable;
20 import java.io.IOException;
21 import java.net.URI;
22 import java.security.Principal;
23 import java.util.List;
24 import java.util.Map;
25 import java.util.Set;
26 
27 public interface Session extends Closeable {
28 
29     /**
30      * Get the container that created this session.
31      * @return the container that created this session.
32      */
getContainer()33     WebSocketContainer getContainer();
34 
35     /**
36      * Registers a {@link MessageHandler} for incoming messages. Only one
37      * {@link MessageHandler} may be registered for each message type (text,
38      * binary, pong). The message type will be derived at runtime from the
39      * provided {@link MessageHandler} instance. It is not always possible to do
40      * this so it is better to use
41      * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Partial)}
42      * or
43      * {@link #addMessageHandler(Class, javax.websocket.MessageHandler.Whole)}.
44      *
45      * @param handler   The message handler for a incoming message
46      *
47      * @throws IllegalStateException  If a message handler has already been
48      *                                registered for the associated message type
49      */
addMessageHandler(MessageHandler handler)50     void addMessageHandler(MessageHandler handler) throws IllegalStateException;
51 
getMessageHandlers()52     Set<MessageHandler> getMessageHandlers();
53 
removeMessageHandler(MessageHandler listener)54     void removeMessageHandler(MessageHandler listener);
55 
getProtocolVersion()56     String getProtocolVersion();
57 
getNegotiatedSubprotocol()58     String getNegotiatedSubprotocol();
59 
getNegotiatedExtensions()60     List<Extension> getNegotiatedExtensions();
61 
isSecure()62     boolean isSecure();
63 
isOpen()64     boolean isOpen();
65 
66     /**
67      * Get the idle timeout for this session.
68      * @return The current idle timeout for this session in milliseconds. Zero
69      *         or negative values indicate an infinite timeout.
70      */
getMaxIdleTimeout()71     long getMaxIdleTimeout();
72 
73     /**
74      * Set the idle timeout for this session.
75      * @param timeout The new idle timeout for this session in milliseconds.
76      *                Zero or negative values indicate an infinite timeout.
77      */
setMaxIdleTimeout(long timeout)78     void setMaxIdleTimeout(long timeout);
79 
80     /**
81      * Set the current maximum buffer size for binary messages.
82      * @param max The new maximum buffer size in bytes
83      */
setMaxBinaryMessageBufferSize(int max)84     void setMaxBinaryMessageBufferSize(int max);
85 
86     /**
87      * Get the current maximum buffer size for binary messages.
88      * @return The current maximum buffer size in bytes
89      */
getMaxBinaryMessageBufferSize()90     int getMaxBinaryMessageBufferSize();
91 
92     /**
93      * Set the maximum buffer size for text messages.
94      * @param max The new maximum buffer size in characters.
95      */
setMaxTextMessageBufferSize(int max)96     void setMaxTextMessageBufferSize(int max);
97 
98     /**
99      * Get the maximum buffer size for text messages.
100      * @return The maximum buffer size in characters.
101      */
getMaxTextMessageBufferSize()102     int getMaxTextMessageBufferSize();
103 
getAsyncRemote()104     RemoteEndpoint.Async getAsyncRemote();
105 
getBasicRemote()106     RemoteEndpoint.Basic getBasicRemote();
107 
108     /**
109      * Provides a unique identifier for the session. This identifier should not
110      * be relied upon to be generated from a secure random source.
111      * @return A unique identifier for the session.
112      */
getId()113     String getId();
114 
115     /**
116      * Close the connection to the remote end point using the code
117      * {@link javax.websocket.CloseReason.CloseCodes#NORMAL_CLOSURE} and an
118      * empty reason phrase.
119      *
120      * @throws IOException if an I/O error occurs while the WebSocket session is
121      *                     being closed.
122      */
123     @Override
close()124     void close() throws IOException;
125 
126 
127     /**
128      * Close the connection to the remote end point using the specified code
129      * and reason phrase.
130      * @param closeReason The reason the WebSocket session is being closed.
131      *
132      * @throws IOException if an I/O error occurs while the WebSocket session is
133      *                     being closed.
134      */
close(CloseReason closeReason)135     void close(CloseReason closeReason) throws IOException;
136 
getRequestURI()137     URI getRequestURI();
138 
getRequestParameterMap()139     Map<String, List<String>> getRequestParameterMap();
140 
getQueryString()141     String getQueryString();
142 
getPathParameters()143     Map<String,String> getPathParameters();
144 
getUserProperties()145     Map<String,Object> getUserProperties();
146 
getUserPrincipal()147     Principal getUserPrincipal();
148 
149     /**
150      * Obtain the set of open sessions associated with the same local endpoint
151      * as this session.
152      *
153      * @return The set of currently open sessions for the local endpoint that
154      * this session is associated with.
155      */
getOpenSessions()156     Set<Session> getOpenSessions();
157 
158     /**
159      * Registers a {@link MessageHandler} for partial incoming messages. Only
160      * one {@link MessageHandler} may be registered for each message type (text
161      * or binary, pong messages are never presented as partial messages).
162      *
163      * @param <T>       The type of message that the given handler is intended
164      *                  for
165      * @param clazz     The Class that implements T
166      * @param handler   The message handler for a incoming message
167      *
168      * @throws IllegalStateException  If a message handler has already been
169      *                                registered for the associated message type
170      *
171      * @since WebSocket 1.1
172      */
addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)173     <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler)
174             throws IllegalStateException;
175 
176     /**
177      * Registers a {@link MessageHandler} for whole incoming messages. Only
178      * one {@link MessageHandler} may be registered for each message type (text,
179      * binary, pong).
180      *
181      * @param <T>       The type of message that the given handler is intended
182      *                  for
183      * @param clazz     The Class that implements T
184      * @param handler   The message handler for a incoming message
185      *
186      * @throws IllegalStateException  If a message handler has already been
187      *                                registered for the associated message type
188      *
189      * @since WebSocket 1.1
190      */
addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler)191     <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler)
192             throws IllegalStateException;
193 }
194