001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.mina.core.service; 021 022import java.io.IOException; 023 024import org.apache.mina.core.session.IdleStatus; 025import org.apache.mina.core.session.IoSession; 026 027/** 028 * Handles all I/O events fired by MINA. 029 * 030 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 031 * 032 * @see IoHandlerAdapter 033 */ 034public interface IoHandler { 035 /** 036 * Invoked from an I/O processor thread when a new connection has been created. 037 * Because this method is supposed to be called from the same thread that 038 * handles I/O of multiple sessions, please implement this method to perform 039 * tasks that consumes minimal amount of time such as socket parameter 040 * and user-defined session attribute initialization. 041 * 042 * @param session The session being created 043 * @throws Exception If we get an exception while processing the create event 044 */ 045 void sessionCreated(IoSession session) throws Exception; 046 047 /** 048 * Invoked when a connection has been opened. This method is invoked after 049 * {@link #sessionCreated(IoSession)}. The biggest difference from 050 * {@link #sessionCreated(IoSession)} is that it's invoked from other thread 051 * than an I/O processor thread once thread model is configured properly. 052 * 053 * @param session The session being opened 054 * @throws Exception If we get an exception while processing the open event 055 */ 056 void sessionOpened(IoSession session) throws Exception; 057 058 /** 059 * Invoked when a connection is closed. 060 * 061 * @param session The session being closed 062 * @throws Exception If we get an exception while processing the close event 063 */ 064 void sessionClosed(IoSession session) throws Exception; 065 066 /** 067 * Invoked with the related {@link IdleStatus} when a connection becomes idle. 068 * This method is not invoked if the transport type is UDP; it's a known bug, 069 * and will be fixed in 2.0. 070 * 071 * @param session The idling session 072 * @param status The session's status 073 * @throws Exception If we get an exception while processing the idle event 074 */ 075 void sessionIdle(IoSession session, IdleStatus status) throws Exception; 076 077 /** 078 * Invoked when any exception is thrown by user {@link IoHandler} 079 * implementation or by MINA. If <code>cause</code> is an instance of 080 * {@link IOException}, MINA will close the connection automatically. 081 * 082 * @param session The session for which we have got an exception 083 * @param cause The exception that has been caught 084 * @throws Exception If we get an exception while processing the caught exception 085 */ 086 void exceptionCaught(IoSession session, Throwable cause) throws Exception; 087 088 /** 089 * Invoked when a message is received. 090 * 091 * @param session The session that is receiving a message 092 * @param message The received message 093 * @throws Exception If we get an exception while processing the received message 094 */ 095 void messageReceived(IoSession session, Object message) throws Exception; 096 097 /** 098 * Invoked when a message written by {@link IoSession#write(Object)} is 099 * sent out. 100 * 101 * @param session The session that has sent a full message 102 * @param message The sent message 103 * @throws Exception If we get an exception while processing the sent message 104 */ 105 void messageSent(IoSession session, Object message) throws Exception; 106 107 /** 108 * Handle the closure of an half-duplex TCP channel 109 * 110 * @param session The session which input is being closed 111 * @throws Exception If we get an exception while closing the input 112 */ 113 void inputClosed(IoSession session) throws Exception; 114}