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.IdleStatus; 32 import org.apache.mina.core.session.IoSession; 33 import org.apache.mina.core.session.IoSessionConfig; 34 import org.apache.mina.core.session.IoSessionDataStructureFactory; 35 36 /** 37 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s 38 * that provide I/O service and manage {@link IoSession}s. 39 * 40 * @author The Apache MINA Project (dev@mina.apache.org) 41 * @version $Rev: 671827 $, $Date: 2008-06-26 10:49:48 +0200 (jeu, 26 jun 2008) $ 42 */ 43 public interface IoService { 44 /** 45 * Returns the {@link TransportMetadata} that this service runs on. 46 */ 47 TransportMetadata getTransportMetadata(); 48 49 /** 50 * Adds an {@link IoServiceListener} that listens any events related with 51 * this service. 52 */ 53 void addListener(IoServiceListener listener); 54 55 /** 56 * Removed an existing {@link IoServiceListener} that listens any events 57 * related with this service. 58 */ 59 void removeListener(IoServiceListener listener); 60 61 /** 62 * Returns <tt>true</tt> if and if only {@link #dispose()} method has 63 * been called. Please note that this method will return <tt>true</tt> 64 * even after all the related resources are released. 65 */ 66 boolean isDisposing(); 67 68 /** 69 * Returns <tt>true</tt> if and if only all resources of this processor 70 * have been disposed. 71 */ 72 boolean isDisposed(); 73 74 /** 75 * Releases any resources allocated by this service. Please note that 76 * this method might block as long as there are any sessions managed by 77 * this service. 78 */ 79 void dispose(); 80 81 /** 82 * Returns the handler which will handle all connections managed by this service. 83 */ 84 IoHandler getHandler(); 85 86 /** 87 * Sets the handler which will handle all connections managed by this service. 88 */ 89 void setHandler(IoHandler handler); 90 91 /** 92 * Returns the map of all sessions which are currently managed by this 93 * service. The key of map is the {@link IoSession#getId() ID} of the 94 * session. 95 * 96 * @return the sessions. An empty collection if there's no session. 97 */ 98 Map<Long, IoSession> getManagedSessions(); 99 100 /** 101 * Returns the number of all sessions which are currently managed by this 102 * service. 103 */ 104 int getManagedSessionCount(); 105 106 /** 107 * Returns the maximum number of sessions which were being managed at the 108 * same time. 109 */ 110 int getLargestManagedSessionCount(); 111 112 /** 113 * Returns the cumulative number of sessions which were managed (or are 114 * being managed) by this service, which means 'currently managed session 115 * count + closed session count'. 116 */ 117 long getCumulativeManagedSessionCount(); 118 119 /** 120 * Returns the default configuration of the new {@link IoSession}s 121 * created by this service. 122 */ 123 IoSessionConfig getSessionConfig(); 124 125 /** 126 * Returns the {@link IoFilterChainBuilder} which will build the 127 * {@link IoFilterChain} of all {@link IoSession}s which is created 128 * by this service. 129 * The default value is an empty {@link DefaultIoFilterChainBuilder}. 130 */ 131 IoFilterChainBuilder getFilterChainBuilder(); 132 133 /** 134 * Sets the {@link IoFilterChainBuilder} which will build the 135 * {@link IoFilterChain} of all {@link IoSession}s which is created 136 * by this service. 137 * If you specify <tt>null</tt> this property will be set to 138 * an empty {@link DefaultIoFilterChainBuilder}. 139 */ 140 void setFilterChainBuilder(IoFilterChainBuilder builder); 141 142 /** 143 * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>. 144 * Please note that the returned object is not a <b>real</b> {@link IoFilterChain} 145 * but a {@link DefaultIoFilterChainBuilder}. Modifying the returned builder 146 * won't affect the existing {@link IoSession}s at all, because 147 * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s. 148 * 149 * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is 150 * not a {@link DefaultIoFilterChainBuilder} 151 */ 152 DefaultIoFilterChainBuilder getFilterChain(); 153 154 /** 155 * Returns a value of whether or not this service is active 156 * 157 * @return 158 * whether of not the service is active. 159 */ 160 boolean isActive(); 161 162 /** 163 * Returns the time when this service was activated. It returns the last 164 * time when this service was activated if the service is not active now. 165 * 166 * @return 167 * The time by using {@link System#currentTimeMillis()} 168 */ 169 long getActivationTime(); 170 171 /** 172 * Returns the time in millis when I/O occurred lastly. 173 */ 174 long getLastIoTime(); 175 176 /** 177 * Returns the time in millis when read operation occurred lastly. 178 */ 179 long getLastReadTime(); 180 181 /** 182 * Returns the time in millis when write operation occurred lastly. 183 */ 184 long getLastWriteTime(); 185 186 /** 187 * Returns <code>true</code> if this service is idle for the specified 188 * {@link IdleStatus}. 189 */ 190 boolean isIdle(IdleStatus status); 191 192 /** 193 * Returns <code>true</code> if this service is {@link IdleStatus#READER_IDLE}. 194 * @see #isIdle(IdleStatus) 195 */ 196 boolean isReaderIdle(); 197 198 /** 199 * Returns <code>true</code> if this service is {@link IdleStatus#WRITER_IDLE}. 200 * @see #isIdle(IdleStatus) 201 */ 202 boolean isWriterIdle(); 203 204 /** 205 * Returns <code>true</code> if this service is {@link IdleStatus#BOTH_IDLE}. 206 * @see #isIdle(IdleStatus) 207 */ 208 boolean isBothIdle(); 209 210 /** 211 * Returns the number of the fired continuous <tt>serviceIdle</tt> events 212 * for the specified {@link IdleStatus}. 213 * <p/> 214 * If <tt>serviceIdle</tt> event is fired first after some time after I/O, 215 * <tt>idleCount</tt> becomes <tt>1</tt>. <tt>idleCount</tt> resets to 216 * <tt>0</tt> if any I/O occurs again, otherwise it increases to 217 * <tt>2</tt> and so on if <tt>serviceIdle</tt> event is fired again without 218 * any I/O between two (or more) <tt>serviceIdle</tt> events. 219 */ 220 int getIdleCount(IdleStatus status); 221 222 /** 223 * Returns the number of the fired continuous <tt>serviceIdle</tt> events 224 * for {@link IdleStatus#READER_IDLE}. 225 * @see #getIdleCount(IdleStatus) 226 */ 227 int getReaderIdleCount(); 228 229 /** 230 * Returns the number of the fired continuous <tt>serviceIdle</tt> events 231 * for {@link IdleStatus#WRITER_IDLE}. 232 * @see #getIdleCount(IdleStatus) 233 */ 234 int getWriterIdleCount(); 235 236 /** 237 * Returns the number of the fired continuous <tt>serviceIdle</tt> events 238 * for {@link IdleStatus#BOTH_IDLE}. 239 * @see #getIdleCount(IdleStatus) 240 */ 241 int getBothIdleCount(); 242 243 /** 244 * Returns the time in milliseconds when the last <tt>serviceIdle</tt> event 245 * is fired for the specified {@link IdleStatus}. 246 */ 247 long getLastIdleTime(IdleStatus status); 248 249 /** 250 * Returns the time in milliseconds when the last <tt>serviceIdle</tt> event 251 * is fired for {@link IdleStatus#READER_IDLE}. 252 * @see #getLastIdleTime(IdleStatus) 253 */ 254 long getLastReaderIdleTime(); 255 256 /** 257 * Returns the time in milliseconds when the last <tt>serviceIdle</tt> event 258 * is fired for {@link IdleStatus#WRITER_IDLE}. 259 * @see #getLastIdleTime(IdleStatus) 260 */ 261 long getLastWriterIdleTime(); 262 263 /** 264 * Returns the time in milliseconds when the last <tt>serviceIdle</tt> event 265 * is fired for {@link IdleStatus#BOTH_IDLE}. 266 * @see #getLastIdleTime(IdleStatus) 267 */ 268 long getLastBothIdleTime(); 269 270 /** 271 * Returns idle time for the specified type of idleness in seconds. 272 */ 273 int getIdleTime(IdleStatus status); 274 275 /** 276 * Returns idle time for the specified type of idleness in milliseconds. 277 */ 278 long getIdleTimeInMillis(IdleStatus status); 279 280 /** 281 * Sets idle time for the specified type of idleness in seconds. 282 */ 283 void setIdleTime(IdleStatus status, int idleTime); 284 285 /** 286 * Returns idle time for {@link IdleStatus#READER_IDLE} in seconds. 287 */ 288 int getReaderIdleTime(); 289 290 /** 291 * Returns idle time for {@link IdleStatus#READER_IDLE} in milliseconds. 292 */ 293 long getReaderIdleTimeInMillis(); 294 295 /** 296 * Sets idle time for {@link IdleStatus#READER_IDLE} in seconds. 297 */ 298 void setReaderIdleTime(int idleTime); 299 300 /** 301 * Returns idle time for {@link IdleStatus#WRITER_IDLE} in seconds. 302 */ 303 int getWriterIdleTime(); 304 305 /** 306 * Returns idle time for {@link IdleStatus#WRITER_IDLE} in milliseconds. 307 */ 308 long getWriterIdleTimeInMillis(); 309 310 /** 311 * Sets idle time for {@link IdleStatus#WRITER_IDLE} in seconds. 312 */ 313 void setWriterIdleTime(int idleTime); 314 315 /** 316 * Returns idle time for {@link IdleStatus#BOTH_IDLE} in seconds. 317 */ 318 int getBothIdleTime(); 319 320 /** 321 * Returns idle time for {@link IdleStatus#BOTH_IDLE} in milliseconds. 322 */ 323 long getBothIdleTimeInMillis(); 324 325 /** 326 * Sets idle time for {@link IdleStatus#WRITER_IDLE} in seconds. 327 */ 328 void setBothIdleTime(int idleTime); 329 330 /** 331 * Returns the number of bytes read by this service 332 * 333 * @return 334 * The number of bytes this service has read 335 */ 336 long getReadBytes(); 337 338 /** 339 * Returns the number of bytes written out by this service 340 * 341 * @return 342 * The number of bytes this service has written 343 */ 344 long getWrittenBytes(); 345 346 /** 347 * Returns the number of messages this services has read 348 * 349 * @return 350 * The number of messages this services has read 351 */ 352 long getReadMessages(); 353 354 /** 355 * Returns the number of messages this service has written 356 * 357 * @return 358 * The number of messages this service has written 359 */ 360 long getWrittenMessages(); 361 362 /** 363 * Returns the number of read bytes per second. 364 */ 365 double getReadBytesThroughput(); 366 367 /** 368 * Returns the number of written bytes per second. 369 */ 370 double getWrittenBytesThroughput(); 371 372 /** 373 * Returns the number of read messages per second. 374 */ 375 double getReadMessagesThroughput(); 376 377 /** 378 * Returns the number of written messages per second. 379 */ 380 double getWrittenMessagesThroughput(); 381 382 /** 383 * Returns the maximum of the {@link #getReadBytesThroughput() readBytesThroughput}. 384 */ 385 double getLargestReadBytesThroughput(); 386 387 /** 388 * Returns the maximum of the {@link #getWrittenBytesThroughput() writtenBytesThroughput}. 389 */ 390 double getLargestWrittenBytesThroughput(); 391 392 /** 393 * Returns the maximum of the {@link #getReadMessagesThroughput() readMessagesThroughput}. 394 */ 395 double getLargestReadMessagesThroughput(); 396 397 /** 398 * Returns the maximum of the {@link #getWrittenMessagesThroughput() writtenMessagesThroughput}. 399 */ 400 double getLargestWrittenMessagesThroughput(); 401 402 /** 403 * Returns the interval (seconds) between each throughput calculation. 404 * The default value is <tt>3</tt> seconds. 405 */ 406 int getThroughputCalculationInterval(); 407 408 /** 409 * Returns the interval (milliseconds) between each throughput calculation. 410 * The default value is <tt>3</tt> seconds. 411 */ 412 long getThroughputCalculationIntervalInMillis(); 413 414 /** 415 * Sets the interval (seconds) between each throughput calculation. The 416 * default value is <tt>3</tt> seconds. 417 */ 418 void setThroughputCalculationInterval(int throughputCalculationInterval); 419 420 /** 421 * Returns the number of bytes scheduled to be written 422 * 423 * @return 424 * The number of bytes scheduled to be written 425 */ 426 int getScheduledWriteBytes(); 427 428 /** 429 * Returns the number of messages scheduled to be written 430 * 431 * @return 432 * The number of messages scheduled to be written 433 */ 434 int getScheduledWriteMessages(); 435 436 /** 437 * Writes the specified {@code message} to all the {@link IoSession}s 438 * managed by this service. This method is a convenience shortcut for 439 * {@link IoUtil#broadcast(Object, Collection)}. 440 */ 441 Set<WriteFuture> broadcast(Object message); 442 443 /** 444 * Returns the {@link IoSessionDataStructureFactory} that provides 445 * related data structures for a new session created by this service. 446 */ 447 IoSessionDataStructureFactory getSessionDataStructureFactory(); 448 449 /** 450 * Sets the {@link IoSessionDataStructureFactory} that provides 451 * related data structures for a new session created by this service. 452 */ 453 void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory); 454 }