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.handler.chain;
    21
    22  import org.apache.mina.common.IoSession;
    23
    24  /**
    25   * <p>A {@link IoHandlerCommand} encapsulates a unit of processing work to be
    26   * performed, whose purpose is to examine and/or modify the state of a
    27   * transaction that is represented by custom attributes provided by
    28   * {@link IoSession}.  Individual {@link IoHandlerCommand}s can be assembled into
    29   * a {@link IoHandlerChain}, which allows them to either complete the
    30   * required processing or delegate further processing to the next
    31   * {@link IoHandlerCommand} in the {@link IoHandlerChain}.</p>
    32   *
    33   * <p>{@link IoHandlerCommand} implementations typically retrieve and store state
    34   * information in the {@link IoSession} that is passed as a parameter to
    35   * the {@link #execute(NextCommand,IoSession,Object)} method, using custom
    36   * session attributes.  If you think getting attributes is tedious process,
    37   * you can create a bean which contains getters and setters of all properties
    38   * and store the bean as a session attribute:</p>
    39   *
    40   * <pre>
    41   * public class MyContext {
    42   *   public String getPropertyX() { ... };
    43   *   public void setPropertyX(String propertyX) { ... };
    44   *   public int getPropertyZ() { ... };
    45   *   public void setPropertyZ(int propertyZ) { ... };
    46   * }
    47   *
    48   * public class MyHandlderCommand implements IoHandlerCommand {
    49   *   public void execute( NextCommand next, IoSession session, Object message ) throws Exception {
    50   *     MyContext ctx = session.getAttribute( "mycontext" );
    51   *     ...
    52   *   }
    53   * }
    54   * </pre>
    55   *
    56   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
    57   * @version $Rev: 555855 $, $Date: 2007-07-13 05:19:00 +0200 (Fri, 13 Jul 2007) $
    58   */
    59  public interface IoHandlerCommand {
    60      /**
    61       * <p>Execute a unit of processing work to be performed.  This
    62       * {@link IoHandlerCommand} may either complete the required processing
    63       * and just return to stop the processing, or delegate remaining
    64       * processing to the next {@link IoHandlerCommand} in a {@link IoHandlerChain}
    65       * containing this {@link IoHandlerCommand} by calling
    66       * {@link NextCommand#execute(IoSession,Object)}.
    67       *
    68       * @param next an indirect reference to the next {@link IoHandlerCommand} that
    69       *             provides a way to forward the request to the next {@link IoHandlerCommand}.
    70       * @param session the {@link IoSession} which is associated with
    71       *                this request
    72       * @param message the message object of this request
    73       *
    74       * @exception Exception general purpose exception return
    75       *                      to indicate abnormal termination
    76       */
    77      void execute(NextCommand next, IoSession session, Object message)
    78              throws Exception;
    79
    80      /**
    81       * Represents an indirect reference to the next {@link IoHandlerCommand} of
    82       * the {@link IoHandlerChain}.  This interface provides a way to forward
    83       * the request to the next {@link IoHandlerCommand}.
    84       *
    85       * @author The Apache Directory Project (mina-dev@directory.apache.org)
    86       * @version $Rev: 555855 $, $Date: 2007-07-13 05:19:00 +0200 (Fri, 13 Jul 2007) $
    87       */
    88      public interface NextCommand {
    89          /**
    90           * Forwards the request to the next {@link IoHandlerCommand} in the
    91           * {@link IoHandlerChain}.
    92           */
    93          void execute(IoSession session, Object message) throws Exception;
    94      }
    95  }