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.core.filterchain;
    21
    22  import org.apache.mina.core.service.IoHandler;
    23  import org.apache.mina.core.session.IdleStatus;
    24  import org.apache.mina.core.session.IoSession;
    25  import org.apache.mina.core.write.WriteRequest;
    26  import org.apache.mina.filter.util.ReferenceCountingFilter;
    27
    28  /**
    29   * A filter which intercepts {@link IoHandler} events like Servlet
    30   * filters.  Filters can be used for these purposes:
    31   * <ul>
    32   *   <li>Event logging,</li>
    33   *   <li>Performance measurement,</li>
    34   *   <li>Authorization,</li>
    35   *   <li>Overload control,</li>
    36   *   <li>Message transformation (e.g. encryption and decryption, ...),</li>
    37   *   <li>and many more.</li>
    38   * </ul>
    39   * <p>
    40   * <strong>Please NEVER implement your filters to wrap
    41   * {@link IoSession}s.</strong> Users can cache the reference to the
    42   * session, which might malfunction if any filters are added or removed later.
    43   *
    44   * <h3>The Life Cycle</h3>
    45   * {@link IoFilter}s are activated only when they are inside {@link IoFilterChain}.
    46   * <p>
    47   * When you add an {@link IoFilter} to an {@link IoFilterChain}:
    48   * <ol>
    49   *   <li>{@link #init()} is invoked by {@link ReferenceCountingFilter} if
    50   *       the filter is added at the first time.</li>
    51   *   <li>{@link #onPreAdd(IoFilterChain, String, NextFilter)} is invoked to notify
    52   *       that the filter will be added to the chain.</li>
    53   *   <li>The filter is added to the chain, and all events and I/O requests
    54   *       pass through the filter from now.</li>
    55   *   <li>{@link #onPostAdd(IoFilterChain, String, NextFilter)} is invoked to notify
    56   *       that the filter is added to the chain.</li>
    57   *   <li>The filter is removed from the chain if {@link #onPostAdd(IoFilterChain, String, org.apache.mina.core.filterchain.IoFilter.NextFilter)}
    58   *       threw an exception.  {@link #destroy()} is also invoked by
    59   *       {@link ReferenceCountingFilter} if the filter is the last filter which
    60   *       was added to {@link IoFilterChain}s.</li>
    61   * </ol>
    62   * <p>
    63   * When you remove an {@link IoFilter} from an {@link IoFilterChain}:
    64   * <ol>
    65   *   <li>{@link #onPreRemove(IoFilterChain, String, NextFilter)} is invoked to
    66   *       notify that the filter will be removed from the chain.</li>
    67   *   <li>The filter is removed from the chain, and any events and I/O requests
    68   *       don't pass through the filter from now.</li>
    69   *   <li>{@link #onPostRemove(IoFilterChain, String, NextFilter)} is invoked to
    70   *       notify that the filter is removed from the chain.</li>
    71   *   <li>{@link #destroy()} is invoked by {@link ReferenceCountingFilter} if
    72   *       the removed filter was the last one.</li>
    73   * </ol>
    74   *
    75   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    76   *
    77   * @see IoFilterAdapter
    78   */
    79  public interface IoFilter {
    80      /**
    81       * Invoked by {@link ReferenceCountingFilter} when this filter
    82       * is added to a {@link IoFilterChain} at the first time, so you can
    83       * initialize shared resources.  Please note that this method is never
    84       * called if you don't wrap a filter with {@link ReferenceCountingFilter}.
    85       */
    86      void init() throws Exception;
    87
    88      /**
    89       * Invoked by {@link ReferenceCountingFilter} when this filter
    90       * is not used by any {@link IoFilterChain} anymore, so you can destroy
    91       * shared resources.  Please note that this method is never called if
    92       * you don't wrap a filter with {@link ReferenceCountingFilter}.
    93       */
    94      void destroy() throws Exception;
    95
    96      /**
    97       * Invoked before this filter is added to the specified <tt>parent</tt>.
    98       * Please note that this method can be invoked more than once if
    99       * this filter is added to more than one parents.  This method is not
    100      * invoked before {@link #init()} is invoked.
    101      *
    102      * @param parent the parent who called this method
    103      * @param name the name assigned to this filter
    104      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
    105      *                   this object until this filter is removed from the chain.
    106      */
    107     void onPreAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
    108
    109     /**
    110      * Invoked after this filter is added to the specified <tt>parent</tt>.
    111      * Please note that this method can be invoked more than once if
    112      * this filter is added to more than one parents.  This method is not
    113      * invoked before {@link #init()} is invoked.
    114      *
    115      * @param parent the parent who called this method
    116      * @param name the name assigned to this filter
    117      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
    118      *                   this object until this filter is removed from the chain.
    119      */
    120     void onPostAdd(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
    121
    122     /**
    123      * Invoked before this filter is removed from the specified <tt>parent</tt>.
    124      * Please note that this method can be invoked more than once if
    125      * this filter is removed from more than one parents.
    126      * This method is always invoked before {@link #destroy()} is invoked.
    127      *
    128      * @param parent the parent who called this method
    129      * @param name the name assigned to this filter
    130      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
    131      *                   this object until this filter is removed from the chain.
    132      */
    133     void onPreRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
    134
    135     /**
    136      * Invoked after this filter is removed from the specified <tt>parent</tt>.
    137      * Please note that this method can be invoked more than once if
    138      * this filter is removed from more than one parents.
    139      * This method is always invoked before {@link #destroy()} is invoked.
    140      *
    141      * @param parent the parent who called this method
    142      * @param name the name assigned to this filter
    143      * @param nextFilter the {@link NextFilter} for this filter.  You can reuse
    144      *                   this object until this filter is removed from the chain.
    145      */
    146     void onPostRemove(IoFilterChain parent, String name, NextFilter nextFilter) throws Exception;
    147
    148     /**
    149      * Filters {@link IoHandler#sessionCreated(IoSession)} event.
    150      */
    151     void sessionCreated(NextFilter nextFilter, IoSession session) throws Exception;
    152
    153     /**
    154      * Filters {@link IoHandler#sessionOpened(IoSession)} event.
    155      */
    156     void sessionOpened(NextFilter nextFilter, IoSession session) throws Exception;
    157
    158     /**
    159      * Filters {@link IoHandler#sessionClosed(IoSession)} event.
    160      */
    161     void sessionClosed(NextFilter nextFilter, IoSession session) throws Exception;
    162
    163     /**
    164      * Filters {@link IoHandler#sessionIdle(IoSession,IdleStatus)}
    165      * event.
    166      */
    167     void sessionIdle(NextFilter nextFilter, IoSession session, IdleStatus status) throws Exception;
    168
    169     /**
    170      * Filters {@link IoHandler#exceptionCaught(IoSession,Throwable)}
    171      * event.
    172      */
    173     void exceptionCaught(NextFilter nextFilter, IoSession session, Throwable cause) throws Exception;
    174
    175     /**
    176      * Filters {@link IoHandler#messageReceived(IoSession,Object)}
    177      * event.
    178      */
    179     void messageReceived(NextFilter nextFilter, IoSession session, Object message) throws Exception;
    180
    181     /**
    182      * Filters {@link IoHandler#messageSent(IoSession,Object)}
    183      * event.
    184      */
    185     void messageSent(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
    186
    187     /**
    188      * Filters {@link IoSession#close()} method invocation.
    189      */
    190     void filterClose(NextFilter nextFilter, IoSession session) throws Exception;
    191
    192     /**
    193      * Filters {@link IoSession#write(Object)} method invocation.
    194      */
    195     void filterWrite(NextFilter nextFilter, IoSession session, WriteRequest writeRequest) throws Exception;
    196
    197     /**
    198      * Represents the next {@link IoFilter} in {@link IoFilterChain}.
    199      */
    200     public interface NextFilter {
    201         /**
    202          * Forwards <tt>sessionCreated</tt> event to next filter.
    203          */
    204         void sessionCreated(IoSession session);
    205
    206         /**
    207          * Forwards <tt>sessionOpened</tt> event to next filter.
    208          */
    209         void sessionOpened(IoSession session);
    210
    211         /**
    212          * Forwards <tt>sessionClosed</tt> event to next filter.
    213          */
    214         void sessionClosed(IoSession session);
    215
    216         /**
    217          * Forwards <tt>sessionIdle</tt> event to next filter.
    218          */
    219         void sessionIdle(IoSession session, IdleStatus status);
    220
    221         /**
    222          * Forwards <tt>exceptionCaught</tt> event to next filter.
    223          */
    224         void exceptionCaught(IoSession session, Throwable cause);
    225
    226         /**
    227          * Forwards <tt>messageReceived</tt> event to next filter.
    228          */
    229         void messageReceived(IoSession session, Object message);
    230
    231         /**
    232          * Forwards <tt>messageSent</tt> event to next filter.
    233          */
    234         void messageSent(IoSession session, WriteRequest writeRequest);
    235
    236         /**
    237          * Forwards <tt>filterWrite</tt> event to next filter.
    238          */
    239         void filterWrite(IoSession session, WriteRequest writeRequest);
    240
    241         /**
    242          * Forwards <tt>filterClose</tt> event to next filter.
    243          */
    244         void filterClose(IoSession session);
    245
    246     }
    247 }