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.common;
21
22 import java.net.SocketAddress;
23 import java.util.Set;
24
25 /**
26 * A handle which represents connection between two endpoints regardless of
27 * transport types.
28 * <p>
29 * {@link IoSession} provides user-defined attributes. User-defined attributes
30 * are application-specific data which is associated with a session.
31 * It often contains objects that represents the state of a higher-level protocol
32 * and becomes a way to exchange data between filters and handlers.
33 *
34 * <h3>Adjusting Transport Type Specific Properties</h3>
35 * <p>
36 * You can simply downcast the session to an appropriate subclass.
37 * </p>
38 *
39 * <h3>Thread Safety</h3>
40 * <p>
41 * {@link IoSession} is thread-safe. But please note that performing
42 * more than one {@link #write(Object)} calls at the same time will
43 * cause the {@link IoFilter#filterWrite(IoFilter.NextFilter, IoSession, IoFilter.WriteRequest)}
44 * is executed simnutaneously, and therefore you have to make sure the
45 * {@link IoFilter} implementations you're using are thread-safe, too.
46 * </p>
47 *
48 * @author The Apache Directory Project (mina-dev@directory.apache.org)
49 * @version $Rev: 555855 $, $Date: 2007-07-13 12:19:00 +0900 (Fri, 13 Jul 2007) $
50 */
51 public interface IoSession {
52
53 /**
54 * Returns the {@link IoService} which provides I/O service to this session.
55 */
56 IoService getService();
57
58 /**
59 * Returns the {@link IoServiceConfig} of this session.
60 */
61 IoServiceConfig getServiceConfig();
62
63 /**
64 * Returns the {@link IoHandler} which handles this session.
65 */
66 IoHandler getHandler();
67
68 /**
69 * Returns the configuration of this session.
70 */
71 IoSessionConfig getConfig();
72
73 /**
74 * Returns the filter chain that only affects this session.
75 */
76 IoFilterChain getFilterChain();
77
78 /**
79 * Writes the specified <code>message</code> to remote peer. This
80 * operation is asynchronous; {@link IoHandler#messageSent(IoSession, Object)}
81 * will be invoked when the message is actually sent to remote peer.
82 * You can also wait for the returned {@link WriteFuture} if you want
83 * to wait for the message actually written.
84 */
85 WriteFuture write(Object message);
86
87 /**
88 * Closes this session immediately. This operation is asynthronous.
89 * Wait for the returned {@link CloseFuture} if you want to wait for
90 * the session actually closed.
91 */
92 CloseFuture close();
93
94 /**
95 * Returns an attachment of this session.
96 * This method is identical with <tt>getAttribute( "" )</tt>.
97 */
98 Object getAttachment();
99
100 /**
101 * Sets an attachment of this session.
102 * This method is identical with <tt>setAttribute( "", attachment )</tt>.
103 *
104 * @return Old attachment. <tt>null</tt> if it is new.
105 */
106 Object setAttachment(Object attachment);
107
108 /**
109 * Returns the value of user-defined attribute of this session.
110 *
111 * @param key the key of the attribute
112 * @return <tt>null</tt> if there is no attribute with the specified key
113 */
114 Object getAttribute(String key);
115
116 /**
117 * Sets a user-defined attribute.
118 *
119 * @param key the key of the attribute
120 * @param value the value of the attribute
121 * @return The old value of the attribute. <tt>null</tt> if it is new.
122 */
123 Object setAttribute(String key, Object value);
124
125 /**
126 * Sets a user defined attribute without a value. This is useful when
127 * you just want to put a 'mark' attribute. Its value is set to
128 * {@link Boolean#TRUE}.
129 *
130 * @param key the key of the attribute
131 * @return The old value of the attribute. <tt>null</tt> if it is new.
132 */
133 Object setAttribute(String key);
134
135 /**
136 * Removes a user-defined attribute with the specified key.
137 *
138 * @return The old value of the attribute. <tt>null</tt> if not found.
139 */
140 Object removeAttribute(String key);
141
142 /**
143 * Returns <tt>true</tt> if this session contains the attribute with
144 * the specified <tt>key</tt>.
145 */
146 boolean containsAttribute(String key);
147
148 /**
149 * Returns the set of keys of all user-defined attributes.
150 */
151 Set<String> getAttributeKeys();
152
153 /**
154 * Returns transport type of this session.
155 */
156 TransportType getTransportType();
157
158 /**
159 * Returns <code>true</code> if this session is connected with remote peer.
160 */
161 boolean isConnected();
162
163 /**
164 * Returns <code>true</tt> if and only if this session is being closed
165 * (but not disconnected yet) or is closed.
166 */
167 boolean isClosing();
168
169 /**
170 * Returns the {@link CloseFuture} of this session. This method returns
171 * the same instance whenever user calls it.
172 */
173 CloseFuture getCloseFuture();
174
175 /**
176 * Returns the socket address of remote peer.
177 */
178 SocketAddress getRemoteAddress();
179
180 /**
181 * Returns the socket address of local machine which is associated with this
182 * session.
183 */
184 SocketAddress getLocalAddress();
185
186 /**
187 * Returns the socket address of the {@link IoService} listens to to manage
188 * this session. If this session is managed by {@link IoAcceptor}, it
189 * returns the {@link SocketAddress} which is specified as a parameter of
190 * {@link IoAcceptor#bind(SocketAddress, IoHandler)}. If this session is
191 * managed by {@link IoConnector}, this method returns the same address with
192 * that of {@link #getRemoteAddress()}.
193 */
194 SocketAddress getServiceAddress();
195
196 /**
197 * Returns idle time for the specified type of idleness in seconds.
198 */
199 int getIdleTime(IdleStatus status);
200
201 /**
202 * Returns idle time for the specified type of idleness in milliseconds.
203 */
204 long getIdleTimeInMillis(IdleStatus status);
205
206 /**
207 * Sets idle time for the specified type of idleness in seconds.
208 */
209 void setIdleTime(IdleStatus status, int idleTime);
210
211 /**
212 * Returns write timeout in seconds.
213 */
214 int getWriteTimeout();
215
216 /**
217 * Returns write timeout in milliseconds.
218 */
219 long getWriteTimeoutInMillis();
220
221 /**
222 * Sets write timeout in seconds.
223 */
224 void setWriteTimeout(int writeTimeout);
225
226 /**
227 * Returns the current {@link TrafficMask} of this session.
228 */
229 TrafficMask getTrafficMask();
230
231 /**
232 * Sets the {@link TrafficMask} of this session which will result
233 * the parent {@link IoService} to start to control the traffic
234 * of this session immediately.
235 */
236 void setTrafficMask(TrafficMask trafficMask);
237
238 /**
239 * A shortcut method for {@link #setTrafficMask(TrafficMask)} that
240 * suspends read operations for this session.
241 */
242 void suspendRead();
243
244 /**
245 * A shortcut method for {@link #setTrafficMask(TrafficMask)} that
246 * suspends write operations for this session.
247 */
248 void suspendWrite();
249
250 /**
251 * A shortcut method for {@link #setTrafficMask(TrafficMask)} that
252 * resumes read operations for this session.
253 */
254 void resumeRead();
255
256 /**
257 * A shortcut method for {@link #setTrafficMask(TrafficMask)} that
258 * resumes write operations for this session.
259 */
260 void resumeWrite();
261
262 /**
263 * Returns the total number of bytes which were read from this session.
264 */
265 long getReadBytes();
266
267 /**
268 * Returns the total number of bytes which were written to this session.
269 */
270 long getWrittenBytes();
271
272 /**
273 * Returns the total number of messages which were read and decoded from this session.
274 */
275 long getReadMessages();
276
277 /**
278 * Returns the total number of messages which were written and encoded by this session.
279 */
280 long getWrittenMessages();
281
282 /**
283 * Returns the total number of write requests which were written to this session.
284 */
285 long getWrittenWriteRequests();
286
287 /**
288 * Returns the number of write requests which are scheduled to be written
289 * to this session.
290 */
291 int getScheduledWriteRequests();
292
293 /**
294 * Returns the number of bytes which are scheduled to be written to this
295 * session.
296 */
297 int getScheduledWriteBytes();
298
299 /**
300 * Returns the time in millis when this session is created.
301 */
302 long getCreationTime();
303
304 /**
305 * Returns the time in millis when I/O occurred lastly.
306 */
307 long getLastIoTime();
308
309 /**
310 * Returns the time in millis when read operation occurred lastly.
311 */
312 long getLastReadTime();
313
314 /**
315 * Returns the time in millis when write operation occurred lastly.
316 */
317 long getLastWriteTime();
318
319 /**
320 * Returns <code>true</code> if this session is idle for the specified
321 * {@link IdleStatus}.
322 */
323 boolean isIdle(IdleStatus status);
324
325 /**
326 * Returns the number of the fired continuous <tt>sessionIdle</tt> events
327 * for the specified {@link IdleStatus}.
328 * <p>
329 * If <tt>sessionIdle</tt> event is fired first after some time after I/O,
330 * <tt>idleCount</tt> becomes <tt>1</tt>. <tt>idleCount</tt> resets to
331 * <tt>0</tt> if any I/O occurs again, otherwise it increases to
332 * <tt>2</tt> and so on if <tt>sessionIdle</tt> event is fired again without
333 * any I/O between two (or more) <tt>sessionIdle</tt> events.
334 */
335 int getIdleCount(IdleStatus status);
336
337 /**
338 * Returns the time in millis when the last <tt>sessionIdle</tt> event
339 * is fired for the specified {@link IdleStatus}.
340 */
341 long getLastIdleTime(IdleStatus status);
342 }