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 }