IoSession


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 (금, 13  7월 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 }
343
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags