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 The Apache MINA Project (dev@mina.apache.org)
57   * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
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 MINA Project (dev@mina.apache.org)
86       * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $
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  }