View Javadoc

    1   /*
    2    * Copyright 2012 The Netty Project
    3    *
    4    * The Netty Project licenses this file to you under the Apache License,
    5    * version 2.0 (the "License"); you may not use this file except in compliance
    6    * with the License. You may obtain a copy of the License at:
    7    *
    8    *   http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
    13   * License for the specific language governing permissions and limitations
    14   * under the License.
    15   */
    16  package org.jboss.netty.channel;
    17
    18  /**
    19   * Handles or intercepts a downstream {@link ChannelEvent}, and sends a
    20   * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
    21   * <p>
    22   * The most common use case of this interface is to intercept an I/O request
    23   * such as {@link Channel#write(Object)} and {@link Channel#close()}.
    24   *
    25   * <h3>{@link SimpleChannelDownstreamHandler}</h3>
    26   * <p>
    27   * In most cases, you will get to use a {@link SimpleChannelDownstreamHandler}
    28   * to implement a downstream handler because it provides an individual handler
    29   * method for each event type.  You might want to implement this interface
    30   * directly though if you want to handle various types of events in more
    31   * generic way.
    32   *
    33   * <h3>Firing an event to the next handler</h3>
    34   * <p>
    35   * You can forward the received event downstream or upstream.  In most cases,
    36   * {@link ChannelDownstreamHandler} will send the event downstream
    37   * (i.e. outbound) although it is legal to send the event upstream (i.e. inbound):
    38   *
    39   * <pre>
    40   * // Sending the event downstream (outbound)
    41   * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
    42   *     ...
    43   *     ctx.sendDownstream(e);
    44   *     ...
    45   * }
    46   *
    47   * // Sending the event upstream (inbound)
    48   * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
    49   *     ...
    50   *     ctx.sendUpstream(new {@link UpstreamChannelStateEvent}(...));
    51   *     ...
    52   * }
    53   * </pre>
    54   *
    55   * <h4>Using the helper class to send an event</h4>
    56   * <p>
    57   * You will also find various helper methods in {@link Channels} to be useful
    58   * to generate and send an artificial or manipulated event.
    59   * <p>
    60   * <strong>Caution:</strong>
    61   * <p>
    62   * Use the *Later(..) methods of the {@link Channels} class if you want to send an upstream event
    63   * from a {@link ChannelDownstreamHandler} otherwise you may run into threading issues.
    64   *
    65   * <h3>State management</h3>
    66   *
    67   * Please refer to {@link ChannelHandler}.
    68   *
    69   * <h3>Thread safety</h3>
    70   * <p>
    71   * {@link #handleDownstream(ChannelHandlerContext, ChannelEvent) handleDownstream}
    72   * may be invoked by more than one thread simultaneously.  If the handler
    73   * accesses a shared resource or stores stateful information, you might need
    74   * proper synchronization in the handler implementation.
    75   *
    76   * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
    77   */
    78  public interface ChannelDownstreamHandler extends ChannelHandler {
    79
    80      /**
    81       * Handles the specified downstream event.
    82       *
    83       * @param ctx  the context object for this handler
    84       * @param e    the downstream event to process or intercept
    85       */
    86      void handleDownstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
    87  }