1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.mina.api;
21
22 import java.net.SocketAddress;
23 import java.util.Collections;
24 import java.util.Set;
25
26 import javax.net.ssl.SSLContext;
27
28 import org.apache.mina.session.AttributeKey;
29 import org.apache.mina.session.WriteRequest;
30 import org.apache.mina.transport.nio.SelectorLoop;
31 import org.apache.mina.transport.nio.SslHelper;
32
33 /**
34 * A handle which represents a connection between two end-points regardless of transport types.
35 * <p/>
36 * {@link IoSession} provides user-defined attributes. User-defined attributes are application-specific data which are
37 * associated with a session. It often contains objects that represents the state of a higher-level protocol and becomes
38 * a way to exchange data between filters and handlers.
39 * <p/>
40 * <h3>Adjusting Transport Type Specific Properties</h3>
41 * <p/>
42 * You can simply downcast the session to an appropriate subclass.
43 * </p>
44 * <p/>
45 * <h3>Thread Safety</h3>
46 * <p/>
47 * {@link IoSession} is thread-safe. But please note that performing more than one {@link #write(Object)} calls at the
48 * same time will cause the {@link IoFilter#filterWrite(IoFilter.NextFilter,IoSession,WriteRequest)} to be executed
49 * simultaneously, and therefore you have to make sure the {@link IoFilter} implementations you're using are
50 * thread-safe, too.
51 * </p>
52 *
53 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
54 */
55 public interface IoSession {
56 /** The SslHelper instance name, stored in the session's attributes */
57 AttributeKey<SslHelper> SSL_HELPER = new AttributeKey<SslHelper>(SslHelper.class, "internal_sslHelper");
58
59 /**
60 * The unique identifier of this session.
61 *
62 * @return the session's unique identifier
63 */
64 long getId();
65
66 /* ADDRESSES */
67
68 /**
69 * Returns the socket address of remote peer.
70 *
71 * @return the remote socket address
72 */
73 SocketAddress getRemoteAddress();
74
75 /**
76 * Gets the local address of the local peer.
77 *
78 * @return the socket address of local machine which is associated with this session.
79 */
80 SocketAddress getLocalAddress();
81
82 /**
83 * Gets the service this session is attached to.
84 *
85 * @return the {@link IoService} which provides {@link IoSession} to this session.
86 */
87 IoService getService();
88
89 /* READ / WRITE / CLOSE */
90
91 /**
92 * Tells if the session is currently closed.
93 *
94 * @return <code>true</code> if this session is disconnected with remote peer.
95 */
96 boolean isClosed();
97
98 /**
99 * Tells if the session is being closed.
100 *
101 * @return <code>true</code> if this session is in the process of being closed.
102 */
103 boolean isClosing();
104
105 /**
106 * Tells if the session is currently connected and able to process incoming requests and to send outgoing responses.
107 *
108 * @return <code>true</code> if this session is connected with remote peer.
109 */
110 boolean isConnected();
111
112 /**
113 * Tells if the session is created.
114 *
115 * @return <code>true</code> if this session is created.
116 */
117 boolean isCreated();
118
119 /**
120 * Tells if the session is processing a SSL/TLS handshake.
121 *
122 * @return <code>true</tt> if and only if this session is processing a SSL/TLS handshake.
123 */
124 boolean isSecuring();
125
126 /**
127 * Tells if the session is belonging to a secured connection.
128 *
129 * @return <code>true</tt> if and only if this session is belonging a secured connection.
130 */
131 boolean isSecured();
132
133 /**
134 * Changes the session's state from the current state to a new state. Not all the transition are allowed. Here is
135 * the list of all the possible transitions :<br/>
136 * <ul>
137 * <li>CREATED -> CONNECTED</li>
138 * <li>CREATED -> SECURING</li>
139 * <li>CREATED -> CLOSING</li>
140 * <li>CONNECTED -> SECURING</li>
141 * <li>CONNECTED -> CLOSING</li>
142 * <li>SECURING -> SECURED</li>
143 * <li>SECURING -> CLOSING</li>
144 * <li>SECURED -> CONNECTED</li>
145 * <li>SECURED -> SECURING</li>
146 * <li>SECURED -> CLOSING</li>
147 * <li>CLOSING -> CLOSED</li>
148 * </ul>
149 *
150 * @param newState The final SessionState
151 */
152 void changeState(SessionState newState);
153
154 /**
155 * Initializes the SSL/TLS environment for this session.
156 *
157 * @param sslContext The SLLCOntext instance to use.
158 */
159 void initSecure(SSLContext sslContext);
160
161 /**
162 * Tells if the session is using SSL/TLS.
163 *
164 * @return <code>true</tt> if and only if this session is exchanging data over a SSL/TLS connection
165 */
166 boolean isConnectedSecured();
167
168 /**
169 * Closes this session immediately or after all queued write requests are flushed. This operation is asynchronous.
170 * Wait for the returned {@link IoFuture} if you want to wait for the session actually closed. Once this method has
171 * been called, no incoming request will be accepted.
172 *
173 * @param immediately {@code true} to close this session immediately. {@code false} to close this session after all
174 * queued write requests are flushed.
175 * @return A {@link IoFuture} that will contains the session's state
176 */
177 IoFuture<Void> close(boolean immediately);
178
179 /* READ/WRITE PAUSE MANAGEMENT */
180 /**
181 * Suspends read operations for this session.
182 */
183 void suspendRead();
184
185 /**
186 * Suspends write operations for this session.
187 */
188 void suspendWrite();
189
190 /**
191 * Resumes read operations for this session.
192 */
193 void resumeRead();
194
195 /**
196 * Resumes write operations for this session.
197 */
198 void resumeWrite();
199
200 /**
201 * Is read operation is suspended for this session.
202 *
203 * @return <code>true</code> if suspended
204 */
205 boolean isReadSuspended();
206
207 /**
208 * Is write operation is suspended for this session.
209 *
210 * @return <code>true</code> if suspended
211 */
212 boolean isWriteSuspended();
213
214 /* BASIC STATS */
215 /**
216 * Gets the total number of bytes read for this session since it was created.
217 *
218 * Returns the total number of bytes which were read from this session.
219 */
220 long getReadBytes();
221
222 /**
223 * Gets the total number of bytes written for this session since it was created.
224 *
225 * @return the total number of bytes which were written to this session.
226 */
227 long getWrittenBytes();
228
229 /* IDLE management */
230 /**
231 * Gets the session configuration, it where the idle timeout are set and other transport specific configuration.
232 *
233 * @return the session's configuration
234 */
235 IoSessionConfig getConfig();
236
237 /**
238 * The session's creation time.
239 *
240 * @return the session's creation time in milliseconds
241 */
242 long getCreationTime();
243
244 /**
245 * Returns the time in millisecond when I/O occurred lastly (either read or write).
246 *
247 * @return the time of the last read or write done for this session
248 */
249 long getLastIoTime();
250
251 /**
252 * Returns the time in millisecond when the last I/O read occurred.
253 *
254 * Returns the time in millisecond when read operation occurred lastly.
255 */
256 long getLastReadTime();
257
258 /**
259 * Returns the time in millisecond when the last I/O write occurred.
260 *
261 * Returns the time in millisecond when write operation occurred lastly.
262 */
263 long getLastWriteTime();
264
265 /* Session context management */
266
267 /**
268 * Returns the value of the user-defined attribute for the given <code>key</code>.If the there is no attribute with
269 * the specified key the <tt>defaultValue</tt> will be returned.
270 *
271 * @param key the attribute's key, must not be <code>null</code>
272 * @return <tt>defaultValue</tt> if there is no attribute with the specified key
273 * @exception IllegalArgumentException if <code>key==null</code>
274 * @see #setAttribute(AttributeKey, Object)
275 */
276 <T> T getAttribute(AttributeKey<T> key, T defaultValue);
277
278 /**
279 * Returns the value of the user-defined attribute for the given <code>key</code>.If the there is no attribute with
280 * the specified key <code>null</code> will be returned.
281 *
282 * @param key the attribute's key, must not be <code>null</code>
283 * @return <code>null</code> if there is no attribute with the specified key
284 * @exception IllegalArgumentException if <code>key==null</code>
285 * @see #setAttribute(AttributeKey, Object)
286 */
287 <T> T getAttribute(AttributeKey<T> key);
288
289 /**
290 * Sets a user-defined attribute. If the <code>value</code> is <code>null</code> the attribute will be removed from
291 * this {@link IoSession}.
292 *
293 * @param key the attribute's key, must not be <code>null</code>
294 * @param value the attribute's value, <code>null</code> to remove the attribute
295 * @return the old attribute's value or <code>null</code> if there is no previous value
296 * @exception IllegalArgumentException <ul>
297 * <li>if <code>key==null</code>
298 * <li>if <code>value</code> is not <code>null</code> and not an instance of type that is specified in by
299 * the given <code>key</code> (see {@link AttributeKey#getType()})
300 *
301 * </ul>
302 *
303 * @see #getAttribute(AttributeKey)
304 */
305 <T> T setAttribute(AttributeKey<? extends T> key, T value);
306
307 /**
308 * Returns an unmodifiable {@link Set} of all Keys of this {@link IoSession}. If this {@link IoSession} contains no
309 * attributes an empty {@link Set} will be returned.
310 *
311 * @return all Keys, never <code>null</code>
312 * @see Collections#unmodifiableSet(Set)
313 */
314 Set<AttributeKey<?>> getAttributeKeys();
315
316 /**
317 * Removes the specified Attribute from this container. The old value will be returned, <code>null</code> will be
318 * rutrnen if there is no such attribute in this container.<br>
319 * <br>
320 * This method is equivalent to <code>setAttribute(key,null)</code>.
321 *
322 * @param key of the attribute to be removed,must not be <code>null</code>
323 * @return the removed value, <code>null</code> if this container doesn't contain the specified attribute
324 * @exception IllegalArgumentException if <code>key==null</code>
325 */
326 <T> T removeAttribute(AttributeKey<T> key);
327
328 /**
329 * State of a {@link IoSession}
330 *
331 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
332 *
333 */
334 enum SessionState {
335 CREATED, CONNECTED, CLOSING, CLOSED, SECURING, SECURED
336 }
337
338 /* SESSION WRITING */
339 /**
340 * Enqueue a message for writing. This method wont block ! The message will by asynchronously processed by the
341 * filter chain and wrote to socket by the {@link SelectorLoop}
342 *
343 */
344 void write(Object message);
345
346 /**
347 * Same as {@link IoSession#write(Object)}, but provide a {@link IoFuture} for tracking the completion of this
348 * write.
349 *
350 * @param message the message to be processed and written
351 * @return the {@link IoFuture} for tracking this asynchronous operation
352 */
353 IoFuture<Void> writeWithFuture(Object message);
354
355 /**
356 * Internal method for enqueue write request after filter chain processing
357 *
358 * @param writeRequest the message to put in the write request
359 * @return the created write request
360 */
361 WriteRequest enqueueWriteRequest(WriteRequest writeRequest);
362
363 }