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