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 The Apache MINA Project (dev@mina.apache.org)
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 * Returns the handler which will handle all connections managed by this service.
80 */
81 IoHandler getHandler();
82
83 /**
84 * Sets the handler which will handle all connections managed by this service.
85 */
86 void setHandler(IoHandler handler);
87
88 /**
89 * Returns the map of all sessions which are currently managed by this
90 * service. The key of map is the {@link IoSession#getId() ID} of the
91 * session.
92 *
93 * @return the sessions. An empty collection if there's no session.
94 */
95 Map<Long, IoSession> getManagedSessions();
96
97 /**
98 * Returns the number of all sessions which are currently managed by this
99 * service.
100 */
101 int getManagedSessionCount();
102
103 /**
104 * Returns the default configuration of the new {@link IoSession}s
105 * created by this service.
106 */
107 IoSessionConfig getSessionConfig();
108
109 /**
110 * Returns the {@link IoFilterChainBuilder} which will build the
111 * {@link IoFilterChain} of all {@link IoSession}s which is created
112 * by this service.
113 * The default value is an empty {@link DefaultIoFilterChainBuilder}.
114 */
115 IoFilterChainBuilder getFilterChainBuilder();
116
117 /**
118 * Sets the {@link IoFilterChainBuilder} which will build the
119 * {@link IoFilterChain} of all {@link IoSession}s which is created
120 * by this service.
121 * If you specify <tt>null</tt> this property will be set to
122 * an empty {@link DefaultIoFilterChainBuilder}.
123 */
124 void setFilterChainBuilder(IoFilterChainBuilder builder);
125
126 /**
127 * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
128 * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
129 * but a {@link DefaultIoFilterChainBuilder}. Modifying the returned builder
130 * won't affect the existing {@link IoSession}s at all, because
131 * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
132 *
133 * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
134 * not a {@link DefaultIoFilterChainBuilder}
135 */
136 DefaultIoFilterChainBuilder getFilterChain();
137
138 /**
139 * Returns a value of whether or not this service is active
140 *
141 * @return whether of not the service is active.
142 */
143 boolean isActive();
144
145 /**
146 * Returns the time when this service was activated. It returns the last
147 * time when this service was activated if the service is not active now.
148 *
149 * @return The time by using {@link System#currentTimeMillis()}
150 */
151 long getActivationTime();
152
153 /**
154 * Writes the specified {@code message} to all the {@link IoSession}s
155 * managed by this service. This method is a convenience shortcut for
156 * {@link IoUtil#broadcast(Object, Collection)}.
157 */
158 Set<WriteFuture> broadcast(Object message);
159
160 /**
161 * Returns the {@link IoSessionDataStructureFactory} that provides
162 * related data structures for a new session created by this service.
163 */
164 IoSessionDataStructureFactory getSessionDataStructureFactory();
165
166 /**
167 * Sets the {@link IoSessionDataStructureFactory} that provides
168 * related data structures for a new session created by this service.
169 */
170 void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
171
172 /**
173 * Returns the number of bytes scheduled to be written
174 *
175 * @return The number of bytes scheduled to be written
176 */
177 int getScheduledWriteBytes();
178
179 /**
180 * Returns the number of messages scheduled to be written
181 *
182 * @return The number of messages scheduled to be written
183 */
184 int getScheduledWriteMessages();
185
186 /**
187 * Returns the IoServiceStatistics object for this service.
188 *
189 * @return The statistics object for this service.
190 */
191 IoServiceStatistics getStatistics();
192 }