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.Collection;
23 import java.util.Map;
24 import java.util.Set;
25
26 import org.apache.mina.core.IoUtil;
27 import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
28 import org.apache.mina.core.filterchain.IoFilterChain;
29 import org.apache.mina.core.filterchain.IoFilterChainBuilder;
30 import org.apache.mina.core.future.WriteFuture;
31 import org.apache.mina.core.session.IoSession;
32 import org.apache.mina.core.session.IoSessionConfig;
33 import org.apache.mina.core.session.IoSessionDataStructureFactory;
34
35 /**
36 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
37 * that provide I/O service and manage {@link IoSession}s.
38 *
39 * @author The Apache MINA Project (dev@mina.apache.org)
40 * @version $Rev: 677580 $, $Date: 2008-07-17 15:27:07 +0200 (jeu, 17 jui 2008) $
41 */
42 public interface IoService {
43 /**
44 * Returns the {@link TransportMetadata} that this service runs on.
45 */
46 TransportMetadata getTransportMetadata();
47
48 /**
49 * Adds an {@link IoServiceListener} that listens any events related with
50 * this service.
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 void removeListener(IoServiceListener listener);
59
60 /**
61 * Returns <tt>true</tt> if and if only {@link #dispose()} method has
62 * been called. Please note that this method will return <tt>true</tt>
63 * even after all the related resources are released.
64 */
65 boolean isDisposing();
66
67 /**
68 * Returns <tt>true</tt> if and if only all resources of this processor
69 * have been disposed.
70 */
71 boolean isDisposed();
72
73 /**
74 * Releases any resources allocated by this service. Please note that
75 * this method might block as long as there are any sessions managed by
76 * this service.
77 */
78 void dispose();
79
80 /**
81 * Returns the handler which will handle all connections managed by this service.
82 */
83 IoHandler getHandler();
84
85 /**
86 * Sets the handler which will handle all connections managed by this service.
87 */
88 void setHandler(IoHandler handler);
89
90 /**
91 * Returns the map of all sessions which are currently managed by this
92 * service. The key of map is the {@link IoSession#getId() ID} of the
93 * session.
94 *
95 * @return the sessions. An empty collection if there's no session.
96 */
97 Map<Long, IoSession> getManagedSessions();
98
99 /**
100 * Returns the number of all sessions which are currently managed by this
101 * service.
102 */
103 int getManagedSessionCount();
104
105 /**
106 * Returns the default configuration of the new {@link IoSession}s
107 * created by this service.
108 */
109 IoSessionConfig getSessionConfig();
110
111 /**
112 * Returns the {@link IoFilterChainBuilder} which will build the
113 * {@link IoFilterChain} of all {@link IoSession}s which is created
114 * by this service.
115 * The default value is an empty {@link DefaultIoFilterChainBuilder}.
116 */
117 IoFilterChainBuilder getFilterChainBuilder();
118
119 /**
120 * Sets the {@link IoFilterChainBuilder} which will build the
121 * {@link IoFilterChain} of all {@link IoSession}s which is created
122 * by this service.
123 * If you specify <tt>null</tt> this property will be set to
124 * an empty {@link DefaultIoFilterChainBuilder}.
125 */
126 void setFilterChainBuilder(IoFilterChainBuilder builder);
127
128 /**
129 * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
130 * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
131 * but a {@link DefaultIoFilterChainBuilder}. Modifying the returned builder
132 * won't affect the existing {@link IoSession}s at all, because
133 * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
134 *
135 * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
136 * not a {@link DefaultIoFilterChainBuilder}
137 */
138 DefaultIoFilterChainBuilder getFilterChain();
139
140 /**
141 * Returns a value of whether or not this service is active
142 *
143 * @return
144 * whether of not the service is active.
145 */
146 boolean isActive();
147
148 /**
149 * Returns the time when this service was activated. It returns the last
150 * time when this service was activated if the service is not active now.
151 *
152 * @return
153 * The time by using {@link System#currentTimeMillis()}
154 */
155 long getActivationTime();
156
157 /**
158 * Writes the specified {@code message} to all the {@link IoSession}s
159 * managed by this service. This method is a convenience shortcut for
160 * {@link IoUtil#broadcast(Object, Collection)}.
161 */
162 Set<WriteFuture> broadcast(Object message);
163
164 /**
165 * Returns the {@link IoSessionDataStructureFactory} that provides
166 * related data structures for a new session created by this service.
167 */
168 IoSessionDataStructureFactory getSessionDataStructureFactory();
169
170 /**
171 * Sets the {@link IoSessionDataStructureFactory} that provides
172 * related data structures for a new session created by this service.
173 */
174 void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
175
176 /**
177 * Returns the number of bytes scheduled to be written
178 *
179 * @return
180 * The number of bytes scheduled to be written
181 */
182 int getScheduledWriteBytes();
183
184 /**
185 * Returns the number of messages scheduled to be written
186 *
187 * @return
188 * The number of messages scheduled to be written
189 */
190 int getScheduledWriteMessages();
191
192 /**
193 * Returns the IoServiceIdleState for this service.
194 *
195 * @return The idle state object for this service.
196 */
197 IoServiceIdleState getIdleState();
198
199 /**
200 * Returns the IoServiceStatistics object for this service.
201 *
202 * @return The statistics object for this service.
203 */
204 IoServiceStatistics getStatistics();
205 }