View Javadoc

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 }