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  }