View Javadoc

1   /*
2    *   @(#) $Id: IoHandler.java 210062 2005-07-11 03:52:38Z trustin $
3    *
4    *   Copyright 2004 The Apache Software Foundation
5    *
6    *   Licensed under the Apache License, Version 2.0 (the "License");
7    *   you may not use this file except in compliance with the License.
8    *   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, software
13   *   distributed under the License is distributed on an "AS IS" BASIS,
14   *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   *   See the License for the specific language governing permissions and
16   *   limitations under the License.
17   *
18   */
19  package org.apache.mina.io;
20  
21  import java.io.IOException;
22  
23  import org.apache.mina.common.ByteBuffer;
24  import org.apache.mina.common.IdleStatus;
25  
26  /***
27   * Handles all I/O events fired by {@link IoAcceptor} and {@link IoConnector}.
28   * There are 6 event handler methods, and they are all invoked by MINA
29   * automatically.  Most users of MINA I/O package will be OK with this single
30   * interface to implement their protocols.
31   * <p>
32   * Please refer to
33   * <a href="../../../../../xref-examples/org/apache/mina/examples/echoserver/EchoProtocolHandler.html"><code>EchoProtocolHandler</code></a>
34   * example. 
35   * 
36   * @author Trustin Lee (trustin@apache.org)
37   * @version $Rev: 210062 $, $Date: 2005-07-11 12:52:38 +0900 $
38   * 
39   * @see IoHandlerAdapter
40   */
41  public interface IoHandler
42  {
43      /***
44       * Invoked when the session is created.  Initialize default socket
45       * parameters and user-defined attributes here.
46       */
47      void sessionCreated( IoSession session ) throws Exception;
48      
49      /***
50       * Invoked when the connection is opened.  This method is not invoked if the
51       * transport type is UDP.
52       */
53      void sessionOpened( IoSession session ) throws Exception;
54  
55      /***
56       * Invoked when the connection is closed.  This method is not invoked if the
57       * transport type is UDP.
58       */
59      void sessionClosed( IoSession session ) throws Exception;
60  
61      /***
62       * Invoked when the connection is idle.  Refer to {@link IdleStatus}.  This
63       * method is not invoked if the transport type is UDP.
64       */
65      void sessionIdle( IoSession session, IdleStatus status ) throws Exception;
66  
67      /***
68       * Invoked when any exception is thrown by user {@link IoHandler}
69       * implementation or by MINA.  If <code>cause</code> is instanceof
70       * {@link IOException}, MINA will close the connection automatically.
71       */
72      void exceptionCaught( IoSession session, Throwable cause ) throws Exception;
73  
74      /***
75       * Invoked when data is read from the connection.  You can access
76       * <code>buf</code> to get read data.  <code>buf</code> returns to
77       * the internal buffer pool of MINA after this method is invoked, so
78       * please don't try to reuse it.
79       */
80      void dataRead( IoSession session, ByteBuffer buf ) throws Exception;
81  
82      /***
83       * Invoked when MINA wrote {@link IoSession#write(ByteBuffer, Object)}
84       * request successfully.  <code>marker</code> is what you specified at the
85       * point of invocation of {@link IoSession#write(ByteBuffer, Object)}.
86       */
87      void dataWritten( IoSession session, Object marker ) throws Exception;
88  }