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.core.session.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="http://mina.apache.org">Apache MINA Project</a>
    57   */
    58  public interface IoHandlerCommand {
    59      /**
    60       * <p>Execute a unit of processing work to be performed.  This
    61       * {@link IoHandlerCommand} may either complete the required processing
    62       * and just return to stop the processing, or delegate remaining
    63       * processing to the next {@link IoHandlerCommand} in a {@link IoHandlerChain}
    64       * containing this {@link IoHandlerCommand} by calling
    65       * {@link NextCommand#execute(IoSession,Object)}.
    66       *
    67       * @param next an indirect reference to the next {@link IoHandlerCommand} that
    68       *             provides a way to forward the request to the next {@link IoHandlerCommand}.
    69       * @param session the {@link IoSession} which is associated with
    70       *                this request
    71       * @param message the message object of this request
    72       *
    73       * @exception Exception general purpose exception return
    74       *                      to indicate abnormal termination
    75       */
    76      void execute(NextCommand next, IoSession session, Object message) throws Exception;
    77
    78      /**
    79       * Represents an indirect reference to the next {@link IoHandlerCommand} of
    80       * the {@link IoHandlerChain}.  This interface provides a way to forward
    81       * the request to the next {@link IoHandlerCommand}.
    82       *
    83       * @author <a href="http://mina.apache.org">Apache MINA Project</a>
    84       */
    85      public interface NextCommand {
    86          /**
    87           * Forwards the request to the next {@link IoHandlerCommand} in the
    88           * {@link IoHandlerChain}.
    89           */
    90          void execute(IoSession session, Object message) throws Exception;
    91      }
    92  }