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.util.Map;
023import java.util.Set;
024
025import org.apache.mina.core.IoUtil;
026import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
027import org.apache.mina.core.filterchain.IoFilterChain;
028import org.apache.mina.core.filterchain.IoFilterChainBuilder;
029import org.apache.mina.core.future.WriteFuture;
030import org.apache.mina.core.session.IoSession;
031import org.apache.mina.core.session.IoSessionConfig;
032import org.apache.mina.core.session.IoSessionDataStructureFactory;
033
034/**
035 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
036 * that provide I/O service and manage {@link IoSession}s.
037 *
038 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
039 */
040public interface IoService {
041    /**
042     * @return the {@link TransportMetadata} that this service runs on.
043     */
044    TransportMetadata getTransportMetadata();
045
046    /**
047     * Adds an {@link IoServiceListener} that listens any events related with
048     * this service.
049     * 
050     * @param listener The listener to add
051     */
052    void addListener(IoServiceListener listener);
053
054    /**
055     * Removed an existing {@link IoServiceListener} that listens any events
056     * related with this service.
057     * 
058     * @param listener The listener to use
059     */
060    void removeListener(IoServiceListener listener);
061
062    /**
063     * @return <tt>true</tt> if and if only {@link #dispose()} method has
064     * been called.  Please note that this method will return <tt>true</tt>
065     * even after all the related resources are released.
066     */
067    boolean isDisposing();
068
069    /**
070     * @return <tt>true</tt> if and if only all resources of this processor
071     * have been disposed.
072     */
073    boolean isDisposed();
074
075    /**
076     * Releases any resources allocated by this service.  Please note that
077     * this method might block as long as there are any sessions managed by
078     * this service.
079     */
080    void dispose();
081
082    /**
083     * Releases any resources allocated by this service.  Please note that
084     * this method might block as long as there are any sessions managed by this service.
085     *
086     * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
087     * will probably lead to a deadlock.
088     *
089     * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
090     */
091    void dispose(boolean awaitTermination);
092
093    /**
094     * @return the handler which will handle all connections managed by this service.
095     */
096    IoHandler getHandler();
097
098    /**
099     * Sets the handler which will handle all connections managed by this service.
100     * 
101     * @param handler The IoHandler to use
102     */
103    void setHandler(IoHandler handler);
104
105    /**
106     * @return the map of all sessions which are currently managed by this
107     * service.  The key of map is the {@link IoSession#getId() ID} of the
108     * session. An empty collection if there's no session.
109     */
110    Map<Long, IoSession> getManagedSessions();
111
112    /**
113     * @return the number of all sessions which are currently managed by this
114     * service.
115     */
116    int getManagedSessionCount();
117
118    /**
119     * @return the default configuration of the new {@link IoSession}s
120     * created by this service.
121     */
122    IoSessionConfig getSessionConfig();
123
124    /**
125     * @return the {@link IoFilterChainBuilder} which will build the
126     * {@link IoFilterChain} of all {@link IoSession}s which is created
127     * by this service.
128     * The default value is an empty {@link DefaultIoFilterChainBuilder}.
129     */
130    IoFilterChainBuilder getFilterChainBuilder();
131
132    /**
133     * Sets the {@link IoFilterChainBuilder} which will build the
134     * {@link IoFilterChain} of all {@link IoSession}s which is created
135     * by this service.
136     * If you specify <tt>null</tt> this property will be set to
137     * an empty {@link DefaultIoFilterChainBuilder}.
138     * 
139     * @param builder The filter chain builder to use
140     */
141    void setFilterChainBuilder(IoFilterChainBuilder builder);
142
143    /**
144     * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
145     * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
146     * but a {@link DefaultIoFilterChainBuilder}.  Modifying the returned builder
147     * won't affect the existing {@link IoSession}s at all, because
148     * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
149     *
150     * @return The filter chain in use
151     * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
152     *                               not a {@link DefaultIoFilterChainBuilder}
153     */
154    DefaultIoFilterChainBuilder getFilterChain();
155
156    /**
157     * @return a value of whether or not this service is active
158     */
159    boolean isActive();
160
161    /**
162     * @return the time when this service was activated.  It returns the last
163     * time when this service was activated if the service is not active now.
164     */
165    long getActivationTime();
166
167    /**
168     * Writes the specified {@code message} to all the {@link IoSession}s
169     * managed by this service.  This method is a convenience shortcut for
170     * {@link IoUtil#broadcast(Object, Collection)}.
171     * 
172     * @param message the message to broadcast
173     * @return The set of WriteFuture associated to the message being broadcasted
174     */
175    Set<WriteFuture> broadcast(Object message);
176
177    /**
178     * @return the {@link IoSessionDataStructureFactory} that provides
179     * related data structures for a new session created by this service.
180     */
181    IoSessionDataStructureFactory getSessionDataStructureFactory();
182
183    /**
184     * Sets the {@link IoSessionDataStructureFactory} that provides
185     * related data structures for a new session created by this service.
186     * 
187     * @param sessionDataStructureFactory The factory to use
188     */
189    void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
190
191    /**
192     * @return The number of bytes scheduled to be written
193     */
194    int getScheduledWriteBytes();
195
196    /**
197     * @return The number of messages scheduled to be written
198     */
199    int getScheduledWriteMessages();
200
201    /**
202     * @return The statistics object for this service.
203     */
204    IoServiceStatistics getStatistics();
205}