1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.mina.core.service;
21
22 import java.util.Map;
23 import java.util.Set;
24
25 import org.apache.mina.core.IoUtil;
26 import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
27 import org.apache.mina.core.filterchain.IoFilterChain;
28 import org.apache.mina.core.filterchain.IoFilterChainBuilder;
29 import org.apache.mina.core.future.WriteFuture;
30 import org.apache.mina.core.session.IoSession;
31 import org.apache.mina.core.session.IoSessionConfig;
32 import org.apache.mina.core.session.IoSessionDataStructureFactory;
33
34 /**
35 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
36 * that provide I/O service and manage {@link IoSession}s.
37 *
38 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
39 */
40 public interface IoService {
41 /**
42 * @return the {@link TransportMetadata} that this service runs on.
43 */
44 TransportMetadata getTransportMetadata();
45
46 /**
47 * Adds an {@link IoServiceListener} that listens any events related with
48 * this service.
49 *
50 * @param listener The listener to add
51 */
52 void addListener(IoServiceListener listener);
53
54 /**
55 * Removed an existing {@link IoServiceListener} that listens any events
56 * related with this service.
57 *
58 * @param listener The listener to use
59 */
60 void removeListener(IoServiceListener listener);
61
62 /**
63 * @return <tt>true</tt> if and if only {@link #dispose()} method has
64 * been called. Please note that this method will return <tt>true</tt>
65 * even after all the related resources are released.
66 */
67 boolean isDisposing();
68
69 /**
70 * @return <tt>true</tt> if and if only all resources of this processor
71 * have been disposed.
72 */
73 boolean isDisposed();
74
75 /**
76 * Releases any resources allocated by this service. Please note that
77 * this method might block as long as there are any sessions managed by
78 * this service.
79 */
80 void dispose();
81
82 /**
83 * Releases any resources allocated by this service. Please note that
84 * this method might block as long as there are any sessions managed by this service.
85 *
86 * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
87 * will probably lead to a deadlock.
88 *
89 * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
90 */
91 void dispose(boolean awaitTermination);
92
93 /**
94 * @return the handler which will handle all connections managed by this service.
95 */
96 IoHandler getHandler();
97
98 /**
99 * 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 }