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