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 * Returns 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 void addListener(IoServiceListener listener);
51
52 /**
53 * Removed an existing {@link IoServiceListener} that listens any events
54 * related with this service.
55 */
56 void removeListener(IoServiceListener listener);
57
58 /**
59 * Returns <tt>true</tt> if and if only {@link #dispose()} method has
60 * been called. Please note that this method will return <tt>true</tt>
61 * even after all the related resources are released.
62 */
63 boolean isDisposing();
64
65 /**
66 * Returns <tt>true</tt> if and if only all resources of this processor
67 * have been disposed.
68 */
69 boolean isDisposed();
70
71 /**
72 * Releases any resources allocated by this service. Please note that
73 * this method might block as long as there are any sessions managed by
74 * this service.
75 */
76 void dispose();
77
78 /**
79 * Releases any resources allocated by this service. Please note that
80 * this method might block as long as there are any sessions managed by this service.
81 *
82 * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
83 * will probably lead to a deadlock.
84 *
85 * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
86 */
87 void dispose(boolean awaitTermination);
88
89 /**
90 * Returns the handler which will handle all connections managed by this service.
91 */
92 IoHandler getHandler();
93
94 /**
95 * Sets the handler which will handle all connections managed by this service.
96 */
97 void setHandler(IoHandler handler);
98
99 /**
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 }