View Javadoc

1   /*
2    *   @(#) $Id: Session.java 210062 2005-07-11 03:52:38Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   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, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
17   *
18   */
19  package org.apache.mina.common;
20  
21  import java.net.SocketAddress;
22  import java.util.Set;
23  
24  /***
25   * A handle which represents connection between two endpoints regardless of 
26   * transport types.
27   * <p>
28   * Session provides user-defined attributes.  User-defined attributes are
29   * application-specific data which is associated with a session.
30   * It often contains objects that represents the state of a higher-level protocol
31   * and becomes a way to exchange data between filters and handlers.
32   *   
33   * @author Trustin Lee (trustin@apache.org)
34   * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
35   */
36  public interface Session {
37  
38      /***
39       * Closes this session immediately.  Calling method is identical with
40       * calling <tt>close( false )</tt>.
41       */
42      void close();
43  
44      /***
45       * Closes this session immediately.
46       * 
47       * @param wait <tt>true</tt> if you want to wait until closing process is
48       *             complete.
49       */
50      void close( boolean wait );
51      
52      /***
53       * Returns an attachment of this session.
54       * This method is identical with <tt>getAttribute( "" )</tt>.
55       */
56      Object getAttachment();
57  
58      /***
59       * Sets an attachment of this session.
60       * This method is identical with <tt>setAttribute( "", attachment )</tt>.
61       * 
62       * @return Old attachment.  <tt>null</tt> if it is new.
63       */
64      Object setAttachment( Object attachment );
65      
66      /***
67       * Returns the value of user-defined attribute of this session.
68       * 
69       * @param key the key of the attribute
70       * @return <tt>null</tt> if there is no attribute with the specified key
71       */
72      Object getAttribute( String key );
73      
74      /***
75       * Sets a user-defined attribute.
76       * 
77       * @param key the key of the attribute
78       * @param value the value of the attribute
79       * @return The old value of the attribute.  <tt>null</tt> if it is new.
80       */
81      Object setAttribute( String key, Object value );
82      
83      /***
84       * Removes a user-defined attribute with the specified key.
85       * 
86       * @return The old value of the attribute.  <tt>null</tt> if not found.
87       */
88      Object removeAttribute( String key );
89      
90      /***
91       * Returns the set of keys of all user-defined attributes.
92       */
93      Set getAttributeKeys();
94      
95      /***
96       * Returns transport type of this session.
97       */
98      TransportType getTransportType();
99  
100     /***
101      * Returns <code>true</code> if this session is connected with remote peer.
102      */
103     boolean isConnected();
104 
105     /***
106      * Returns the configuration of this session.
107      */
108     SessionConfig getConfig();
109 
110     /***
111      * Returns the socket address of remote peer. 
112      */
113     SocketAddress getRemoteAddress();
114 
115     /***
116      * Returns the socket address of local machine which is associated with this
117      * session.
118      */
119     SocketAddress getLocalAddress();
120 
121     /***
122      * Returns the total number of bytes which were read from this session.
123      */
124     long getReadBytes();
125 
126     /***
127      * Returns the total number of bytes which were written to this session.
128      */
129     long getWrittenBytes();
130 
131     /***
132      * Returns the total number of write requests which were written to this session.
133      */
134     long getWrittenWriteRequests();
135     
136     /***
137      * Returns the number of write requests which are scheduled to be written
138      * to this session.
139      */
140     int getScheduledWriteRequests();
141 
142     /***
143      * Returns the time in millis when I/O occurred lastly.
144      */
145     long getLastIoTime();
146 
147     /***
148      * Returns the time in millis when read operation occurred lastly.
149      */
150     long getLastReadTime();
151 
152     /***
153      * Returns the time in millis when write operation occurred lastly.
154      */
155     long getLastWriteTime();
156 
157     /***
158      * Returns <code>true</code> if this session is idle for the specified 
159      * {@link IdleStatus}.
160      */
161     boolean isIdle( IdleStatus status );
162 }