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.handler.multiton;
021
022import java.io.IOException;
023
024import org.apache.mina.core.service.IoHandler;
025import org.apache.mina.core.session.IdleStatus;
026import org.apache.mina.core.session.IoSession;
027
028/**
029 * A session handler without an {@link IoSession} parameter for simplicity.
030 * <p>
031 * A {@link SingleSessionIoHandler} is similar to an {@link IoHandler} with
032 * the notable difference that a {@link SingleSessionIoHandler} is used only
033 * by one session at a time. Thus, there is no {@link IoSession} parameter in
034 * the methods of this interface.
035 * </p>
036 * <p>
037 * Because events are passed to the session in order, it is possible to store
038 * conversational state as instance variables in this object.
039 * </p>
040 *
041 * WARNING: This class is badly named as the actual {@link IoHandler} implementor
042 * is in fact the {@link SingleSessionIoHandlerDelegate}.
043 * 
044 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
045 */
046@Deprecated
047public interface SingleSessionIoHandler {
048
049    /**
050     * Invoked when the session is created. Initialize default socket parameters
051     * and user-defined attributes here.
052     *
053     * @throws Exception If the session can't be created
054     * @see IoHandler#sessionCreated(IoSession)
055     */
056    void sessionCreated() throws Exception;
057
058    /**
059     * Invoked when the connection is opened. This method is not invoked if the
060     * transport type is UDP.
061     *
062     * @throws Exception If the session can't be opened
063     * @see IoHandler#sessionOpened(IoSession)
064     */
065    void sessionOpened() throws Exception;
066
067    /**
068     * Invoked when the connection is closed. This method is not invoked if the
069     * transport type is UDP.
070     *
071     * @throws Exception If the session can't be closed
072     * @see IoHandler#sessionClosed(IoSession)
073     */
074    void sessionClosed() throws Exception;
075
076    /**
077     * Invoked when the connection is idle. Refer to {@link IdleStatus}. This
078     * method is not invoked if the transport type is UDP.
079     *
080     * @param status the type of idleness
081     * @throws Exception If the idle event can't be handled
082     * @see IoHandler#sessionIdle(IoSession, IdleStatus)
083     */
084    void sessionIdle(IdleStatus status) throws Exception;
085
086    /**
087     * Invoked when any exception is thrown by user {@link IoHandler}
088     * implementation or by MINA. If <code>cause</code> is instanceof
089     * {@link IOException}, MINA will close the connection automatically.
090     *
091     * @param cause the caught exception
092     * @throws Exception If the exception can't be handled
093     * @see IoHandler#exceptionCaught(IoSession, Throwable)
094     */
095    void exceptionCaught(Throwable cause) throws Exception;
096
097    /**
098     * Invoked when a half-duplex connection is closed
099     * 
100     * @param session The current session
101     */
102    void inputClosed(IoSession session);
103
104    /**
105     * Invoked when protocol message is received. Implement your protocol flow
106     * here.
107     *
108     * @param message the received message
109     * @throws Exception If the received message can't be processed
110     * @see IoHandler#messageReceived(IoSession, Object)
111     */
112    void messageReceived(Object message) throws Exception;
113
114    /**
115     * Invoked when protocol message that user requested by
116     * {@link IoSession#write(Object)} is sent out actually.
117     *
118     * @param message the sent message
119     * @throws Exception If the sent message can't be processed
120     * @see IoHandler#messageSent(IoSession, Object)
121     */
122    void messageSent(Object message) throws Exception;
123
124}