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  import java.util.concurrent.Executor;
    19
    20  import org.jboss.netty.handler.execution.ExecutionHandler;
    21
    22
    23  /**
    24   * Handles or intercepts an upstream {@link ChannelEvent}, and sends a
    25   * {@link ChannelEvent} to the next handler in a {@link ChannelPipeline}.
    26   * <p>
    27   * The most common use case of this interface is to intercept an I/O event
    28   * generated by I/O workers to transform the received messages or execute
    29   * the relevant business logic.
    30   *
    31   * <h3>{@link SimpleChannelUpstreamHandler}</h3>
    32   * <p>
    33   * In most cases, you will get to use a {@link SimpleChannelUpstreamHandler} to
    34   * implement an upstream handler because it provides an individual handler
    35   * method for each event type.  You might want to implement this interface
    36   * directly though if you want to handle various types of events in more
    37   * generic way.
    38   *
    39   * <h3>Firing an event to the next handler</h3>
    40   * <p>
    41   * You can forward the received event upstream or downstream.  In most cases,
    42   * {@link ChannelUpstreamHandler} will send the event upstream (i.e. inbound)
    43   * although it is legal to send the event downstream (i.e. outbound):
    44   *
    45   * <pre>
    46   * // Sending the event upstream (inbound)
    47   * void handleUpstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
    48   *     ...
    49   *     ctx.sendUpstream(e);
    50   *     ...
    51   * }
    52   *
    53   * // Sending the event downstream (outbound)
    54   * void handleDownstream({@link ChannelHandlerContext} ctx, {@link ChannelEvent} e) throws Exception {
    55   *     ...
    56   *     ctx.sendDownstream(new {@link DownstreamMessageEvent}(...));
    57   *     ...
    58   * }
    59   * </pre>
    60   *
    61   * <h4>Using the helper class to send an event</h4>
    62   * <p>
    63   * You will also find various helper methods in {@link Channels} to be useful
    64   * to generate and send an artificial or manipulated event.
    65   *
    66   * <h3>State management</h3>
    67   *
    68   * Please refer to {@link ChannelHandler}.
    69   *
    70   * <h3>Thread safety</h3>
    71   * <p>
    72   * {@link #handleUpstream(ChannelHandlerContext, ChannelEvent) handleUpstream}
    73   * will be invoked sequentially by the same thread (i.e. an I/O thread) and
    74   * therefore a handler does not need to worry about being invoked with a new
    75   * upstream event before the previous upstream event is finished.
    76   * <p>
    77   * This does not necessarily mean that there's a dedicated thread per
    78   * {@link Channel}; the I/O thread of some transport can serve more than one
    79   * {@link Channel} (e.g. NIO transport), while the I/O thread of other
    80   * transports can serve only one (e.g. OIO transport).
    81   * <p>
    82   * However, if you add an {@link ExecutionHandler} to a {@link ChannelPipeline},
    83   * this behavior changes depending on what {@link Executor} was employed to
    84   * dispatch the events.  Please refer to {@link ExecutionHandler} for more
    85   * information.
    86   *
    87   * @apiviz.exclude ^org\.jboss\.netty\.handler\..*$
    88   */
    89  public interface ChannelUpstreamHandler extends ChannelHandler {
    90
    91      /**
    92       * Handles the specified upstream event.
    93       *
    94       * @param ctx  the context object for this handler
    95       * @param e    the upstream event to process or intercept
    96       */
    97      void handleUpstream(ChannelHandlerContext ctx, ChannelEvent e) throws Exception;
    98  }