View Javadoc

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 }