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.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 }