001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: *
019: */
020: package org.apache.mina.common;
021:
022: import java.util.Collection;
023: import java.util.Set;
024:
025: /**
026: * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
027: * that provide I/O service and manage {@link IoSession}s.
028: *
029: * @author The Apache MINA Project (dev@mina.apache.org)
030: * @version $Rev: 606098 $, $Date: 2007-12-20 22:11:58 -0700 (Thu, 20 Dec 2007) $
031: */
032: public interface IoService {
033: /**
034: * Returns the {@link TransportMetadata} that this service runs on.
035: */
036: TransportMetadata getTransportMetadata();
037:
038: /**
039: * Adds an {@link IoServiceListener} that listens any events related with
040: * this service.
041: */
042: void addListener(IoServiceListener listener);
043:
044: /**
045: * Removed an existing {@link IoServiceListener} that listens any events
046: * related with this service.
047: */
048: void removeListener(IoServiceListener listener);
049:
050: /**
051: * Returns <tt>true</tt> if and if only {@link #dispose()} method has
052: * been called. Please note that this method will return <tt>true</tt>
053: * even after all the related resources are released.
054: */
055: boolean isDisposing();
056:
057: /**
058: * Returns <tt>true</tt> if and if only all resources of this processor
059: * have been disposed.
060: */
061: boolean isDisposed();
062:
063: /**
064: * Releases any resources allocated by this service. Please note that
065: * this method might block as long as there are any sessions managed by
066: * this service.
067: */
068: void dispose();
069:
070: /**
071: * Returns the handler which will handle all connections managed by this service.
072: */
073: IoHandler getHandler();
074:
075: /**
076: * Sets the handler which will handle all connections managed by this service.
077: */
078: void setHandler(IoHandler handler);
079:
080: /**
081: * Returns all sessions which are currently managed by this service.
082: *
083: * @return the sessions. An empty collection if there's no session.
084: */
085: Set<IoSession> getManagedSessions();
086:
087: /**
088: * Returns the number of all sessions which are currently managed by this
089: * service.
090: */
091: int getManagedSessionCount();
092:
093: /**
094: * Returns the maximum number of sessions which were being managed at the
095: * same time.
096: */
097: int getLargestManagedSessionCount();
098:
099: /**
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(
406: int throughputCalculationInterval);
407:
408: /**
409: * Returns the number of bytes scheduled to be written
410: *
411: * @return
412: * The number of bytes scheduled to be written
413: */
414: long getScheduledWriteBytes();
415:
416: /**
417: * Returns the number of messages scheduled to be written
418: *
419: * @return
420: * The number of messages scheduled to be written
421: */
422: long getScheduledWriteMessages();
423:
424: /**
425: * Writes the specified {@code message} to all the {@link IoSession}s
426: * managed by this service. This method is a convenience shortcut for
427: * {@link IoUtil#broadcast(Object, Collection)}.
428: */
429: Set<WriteFuture> broadcast(Object message);
430:
431: /**
432: * Returns the {@link IoSessionDataStructureFactory} that provides
433: * related data structures for a new session created by this service.
434: */
435: IoSessionDataStructureFactory getSessionDataStructureFactory();
436:
437: /**
438: * Sets the {@link IoSessionDataStructureFactory} that provides
439: * related data structures for a new session created by this service.
440: */
441: void setSessionDataStructureFactory(
442: IoSessionDataStructureFactory sessionDataStructureFactory);
443: }
|