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 java.util.List;
    23
    24  import org.apache.mina.core.filterchain.IoFilter.NextFilter;
    25  import org.apache.mina.core.service.IoHandler;
    26  import org.apache.mina.core.session.IdleStatus;
    27  import org.apache.mina.core.session.IoSession;
    28  import org.apache.mina.core.write.WriteRequest;
    29
    30  /**
    31   * A container of {@link IoFilter}s that forwards {@link IoHandler} events
    32   * to the consisting filters and terminal {@link IoHandler} sequentially.
    33   * Every {@link IoSession} has its own {@link IoFilterChain} (1-to-1 relationship).
    34   *
    35   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    36   */
    37  public interface IoFilterChain {
    38      /**
    39       * Returns the parent {@link IoSession} of this chain.
    40       *
    41       * @return {@link IoSession}
    42       */
    43      IoSession getSession();
    44
    45      /**
    46       * Returns the {@link Entry} with the specified <tt>name</tt> in this chain.
    47       *
    48       * @param name The filter's name we are looking for
    49       * @return <tt>null</tt> if there's no such name in this chain
    50       */
    51      Entry getEntry(String name);
    52
    53      /**
    54       * Returns the {@link Entry} with the specified <tt>filter</tt> in this chain.
    55       *
    56       * @param filter  The Filter we are looking for
    57       * @return <tt>null</tt> if there's no such filter in this chain
    58       */
    59      Entry getEntry(IoFilter filter);
    60
    61      /**
    62       * Returns the {@link Entry} with the specified <tt>filterType</tt>
    63       * in this chain. If there's more than one filter with the specified
    64       * type, the first match will be chosen.
    65       *
    66       * @param filterType The filter class we are looking for
    67       * @return <tt>null</tt> if there's no such name in this chain
    68       */
    69      Entry getEntry(Class<? extends IoFilter> filterType);
    70
    71      /**
    72       * Returns the {@link IoFilter} with the specified <tt>name</tt> in this chain.
    73       *
    74       * @param name the filter's name
    75       * @return <tt>null</tt> if there's no such name in this chain
    76       */
    77      IoFilter get(String name);
    78
    79      /**
    80       * Returns the {@link IoFilter} with the specified <tt>filterType</tt>
    81       * in this chain. If there's more than one filter with the specified
    82       * type, the first match will be chosen.
    83       *
    84       * @param filterType The filter class
    85       * @return <tt>null</tt> if there's no such name in this chain
    86       */
    87      IoFilter get(Class<? extends IoFilter> filterType);
    88
    89      /**
    90       * Returns the {@link NextFilter} of the {@link IoFilter} with the
    91       * specified <tt>name</tt> in this chain.
    92       *
    93       * @param name The filter's name we want the next filter
    94       * @return <tt>null</tt> if there's no such name in this chain
    95       */
    96      NextFilter getNextFilter(String name);
    97
    98      /**
    99       * Returns the {@link NextFilter} of the specified {@link IoFilter}
    100      * in this chain.
    101      *
    102      * @param filter The filter for which we want the next filter
    103      * @return <tt>null</tt> if there's no such name in this chain
    104      */
    105     NextFilter getNextFilter(IoFilter filter);
    106
    107     /**
    108      * Returns the {@link NextFilter} of the specified <tt>filterType</tt>
    109      * in this chain.  If there's more than one filter with the specified
    110      * type, the first match will be chosen.
    111      *
    112      * @param filterType The Filter class for which we want the next filter
    113      * @return <tt>null</tt> if there's no such name in this chain
    114      */
    115     NextFilter getNextFilter(Class<? extends IoFilter> filterType);
    116
    117     /**
    118      * @return The list of all {@link Entry}s this chain contains.
    119      */
    120     List<Entry> getAll();
    121
    122     /**
    123      * @return The reversed list of all {@link Entry}s this chain contains.
    124      */
    125     List<Entry> getAllReversed();
    126
    127     /**
    128      * @param name The filter's name we are looking for
    129      *
    130      * @return <tt>true</tt> if this chain contains an {@link IoFilter} with the
    131      * specified <tt>name</tt>.
    132      */
    133     boolean contains(String name);
    134
    135     /**
    136      * @param filter The filter we are looking for
    137      *
    138      * @return <tt>true</tt> if this chain contains the specified <tt>filter</tt>.
    139      */
    140     boolean contains(IoFilter filter);
    141
    142     /**
    143      * @param  filterType The filter's class we are looking for
    144      *
    145      * @return <tt>true</tt> if this chain contains an {@link IoFilter} of the
    146      * specified <tt>filterType</tt>.
    147      */
    148     boolean contains(Class<? extends IoFilter> filterType);
    149
    150     /**
    151      * Adds the specified filter with the specified name at the beginning of this chain.
    152      *
    153      * @param name The filter's name
    154      * @param filter The filter to add
    155      */
    156     void addFirst(String name, IoFilter filter);
    157
    158     /**
    159      * Adds the specified filter with the specified name at the end of this chain.
    160      *
    161      * @param name The filter's name
    162      * @param filter The filter to add
    163      */
    164     void addLast(String name, IoFilter filter);
    165
    166     /**
    167      * Adds the specified filter with the specified name just before the filter whose name is
    168      * <code>baseName</code> in this chain.
    169      *
    170      * @param baseName The targeted Filter's name
    171      * @param name The filter's name
    172      * @param filter The filter to add
    173      */
    174     void addBefore(String baseName, String name, IoFilter filter);
    175
    176     /**
    177      * Adds the specified filter with the specified name just after the filter whose name is
    178      * <code>baseName</code> in this chain.
    179      *
    180      * @param baseName The targeted Filter's name
    181      * @param name The filter's name
    182      * @param filter The filter to add
    183      */
    184     void addAfter(String baseName, String name, IoFilter filter);
    185
    186     /**
    187      * Replace the filter with the specified name with the specified new
    188      * filter.
    189      *
    190      * @param name The name of the filter we want to replace
    191      * @param newFilter The new filter
    192      * @return the old filter
    193      */
    194     IoFilter replace(String name, IoFilter newFilter);
    195
    196     /**
    197      * Replace the filter with the specified name with the specified new
    198      * filter.
    199      *
    200      * @param oldFilter The filter we want to replace
    201      * @param newFilter The new filter
    202      */
    203     void replace(IoFilter oldFilter, IoFilter newFilter);
    204
    205     /**
    206      * Replace the filter of the specified type with the specified new
    207      * filter.  If there's more than one filter with the specified type,
    208      * the first match will be replaced.
    209      *
    210      * @param oldFilterType The filter class we want to replace
    211      * @param newFilter The new filter
    212      */
    213     IoFilter replace(Class<? extends IoFilter> oldFilterType, IoFilter newFilter);
    214
    215     /**
    216      * Removes the filter with the specified name from this chain.
    217      *
    218      * @param name The name of the filter to remove
    219      * @return The removed filter
    220      */
    221     IoFilter remove(String name);
    222
    223     /**
    224      * Replace the filter with the specified name with the specified new
    225      * filter.
    226      *
    227      * @param name The filter to remove
    228      */
    229     void remove(IoFilter filter);
    230
    231     /**
    232      * Replace the filter of the specified type with the specified new
    233      * filter.  If there's more than one filter with the specified type,
    234      * the first match will be replaced.
    235      *
    236      * @param name The filter class to remove
    237      * @return The removed filter
    238      */
    239     IoFilter remove(Class<? extends IoFilter> filterType);
    240
    241     /**
    242      * Removes all filters added to this chain.
    243      */
    244     void clear() throws Exception;
    245
    246     /**
    247      * Fires a {@link IoHandler#sessionCreated(IoSession)} event. Most users don't need to
    248      * call this method at all. Please use this method only when you implement a new transport
    249      * or fire a virtual event.
    250      */
    251     public void fireSessionCreated();
    252
    253     /**
    254      * Fires a {@link IoHandler#sessionOpened(IoSession)} event. Most users don't need to call
    255      * this method at all. Please use this method only when you implement a new transport or
    256      * fire a virtual event.
    257      */
    258     public void fireSessionOpened();
    259
    260     /**
    261      * Fires a {@link IoHandler#sessionClosed(IoSession)} event. Most users don't need to call
    262      * this method at all. Please use this method only when you implement a new transport or
    263      * fire a virtual event.
    264      */
    265     public void fireSessionClosed();
    266
    267     /**
    268      * Fires a {@link IoHandler#sessionIdle(IoSession, IdleStatus)} event. Most users don't
    269      * need to call this method at all. Please use this method only when you implement a new
    270      * transport or fire a virtual event.
    271      *
    272      * @param status The current status to propagate
    273      */
    274     public void fireSessionIdle(IdleStatus status);
    275
    276     /**
    277      * Fires a {@link IoHandler#messageReceived(Object)} event. Most users don't need to
    278      * call this method at all. Please use this method only when you implement a new transport
    279      * or fire a virtual event.
    280      *
    281      * @param message The received message
    282      */
    283     public void fireMessageReceived(Object message);
    284
    285     /**
    286      * Fires a {@link IoHandler#messageSent(IoSession)} event. Most users don't need to call
    287      * this method at all. Please use this method only when you implement a new transport or
    288      * fire a virtual event.
    289      *
    290      * @param request The sent request
    291      */
    292     public void fireMessageSent(WriteRequest request);
    293
    294     /**
    295      * Fires a {@link IoHandler#exceptionCaught(IoSession, Throwable)} event. Most users don't
    296      * need to call this method at all. Please use this method only when you implement a new
    297      * transport or fire a virtual event.
    298      *
    299      * @param cause The exception cause
    300      */
    301     public void fireExceptionCaught(Throwable cause);
    302
    303     /**
    304      * Fires a {@link IoSession#write(Object)} event. Most users don't need to call this
    305      * method at all. Please use this method only when you implement a new transport or fire a
    306      * virtual event.
    307      *
    308      * @param writeRequest The message to write
    309      */
    310     public void fireFilterWrite(WriteRequest writeRequest);
    311
    312     /**
    313      * Fires a {@link IoSession#close()} event. Most users don't need to call this method at
    314      * all. Please use this method only when you implement a new transport or fire a virtual
    315      * event.
    316      */
    317     public void fireFilterClose();
    318
    319     /**
    320      * Represents a name-filter pair that an {@link IoFilterChain} contains.
    321      *
    322      * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    323      */
    324     public interface Entry {
    325         /**
    326          * Returns the name of the filter.
    327          */
    328         String getName();
    329
    330         /**
    331          * Returns the filter.
    332          */
    333         IoFilter getFilter();
    334
    335         /**
    336          * @return The {@link NextFilter} of the filter.
    337          */
    338         NextFilter getNextFilter();
    339
    340         /**
    341          * Adds the specified filter with the specified name just before this entry.
    342          */
    343         void addBefore(String name, IoFilter filter);
    344
    345         /**
    346          * Adds the specified filter with the specified name just after this entry.
    347          */
    348         void addAfter(String name, IoFilter filter);
    349
    350         /**
    351          * Replace the filter of this entry with the specified new filter.
    352          */
    353         void replace(IoFilter newFilter);
    354
    355         /**
    356          * Removes this entry from the chain it belongs to.
    357          */
    358         void remove();
    359     }
    360 }