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.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 05:19:00 +0200 (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 }