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 org.apache.mina.core.session.IoSession;
023import org.apache.mina.core.write.WriteRequest;
024
025/**
026 * An internal interface to represent an 'I/O processor' that performs
027 * actual I/O operations for {@link IoSession}s.  It abstracts existing
028 * reactor frameworks such as Java NIO once again to simplify transport
029 * implementations.
030 *
031 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
032 * 
033 * @param <S> the type of the {@link IoSession} this processor can handle
034 */
035public interface IoProcessor<S extends IoSession> {
036
037    /**
038     * @return <tt>true</tt> if and if only {@link #dispose()} method has
039     * been called.  Please note that this method will return <tt>true</tt>
040     * even after all the related resources are released.
041     */
042    boolean isDisposing();
043
044    /**
045     * @return <tt>true</tt> if and if only all resources of this processor
046     * have been disposed.
047     */
048    boolean isDisposed();
049
050    /**
051     * Releases any resources allocated by this processor.  Please note that 
052     * the resources might not be released as long as there are any sessions
053     * managed by this processor.  Most implementations will close all sessions
054     * immediately and release the related resources.
055     */
056    void dispose();
057
058    /**
059     * Adds the specified {@code session} to the I/O processor so that
060     * the I/O processor starts to perform any I/O operations related
061     * with the {@code session}.
062     * 
063     * @param session The added session
064     */
065    void add(S session);
066
067    /**
068     * Flushes the internal write request queue of the specified
069     * {@code session}.
070     * 
071     * @param session The session we want the message to be written
072     */
073    void flush(S session);
074
075    /**
076     * Writes the WriteRequest for the specified {@code session}.
077     * 
078     * @param session The session we want the message to be written
079     * @param writeRequest the WriteRequest to write
080     */
081    void write(S session, WriteRequest writeRequest);
082
083    /**
084     * Controls the traffic of the specified {@code session} depending of the
085     * {@link IoSession#isReadSuspended()} and {@link IoSession#isWriteSuspended()}
086     * flags
087     * 
088     * @param session The session to be updated
089     */
090    void updateTrafficControl(S session);
091
092    /**
093     * Removes and closes the specified {@code session} from the I/O
094     * processor so that the I/O processor closes the connection
095     * associated with the {@code session} and releases any other related
096     * resources.
097     * 
098     * @param session The session to be removed
099     */
100    void remove(S session);
101}