查看本类的 API文档回源码主页即时通讯网 - 即时通讯开发者社区!
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.Map;
23  import java.util.Set;
24  
25  import org.apache.mina.core.IoUtil;
26  import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder;
27  import org.apache.mina.core.filterchain.IoFilterChain;
28  import org.apache.mina.core.filterchain.IoFilterChainBuilder;
29  import org.apache.mina.core.future.WriteFuture;
30  import org.apache.mina.core.session.IoSession;
31  import org.apache.mina.core.session.IoSessionConfig;
32  import org.apache.mina.core.session.IoSessionDataStructureFactory;
33  
34  /**
35   * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s
36   * that provide I/O service and manage {@link IoSession}s.
37   *
38   * @author <a href="http://mina.apache.org">Apache MINA Project</a>
39   */
40  public interface IoService {
41      /**
42       * @return the {@link TransportMetadata} that this service runs on.
43       */
44      TransportMetadata getTransportMetadata();
45  
46      /**
47       * Adds an {@link IoServiceListener} that listens any events related with
48       * this service.
49       * 
50       * @param listener The listener to add
51       */
52      void addListener(IoServiceListener listener);
53  
54      /**
55       * Removed an existing {@link IoServiceListener} that listens any events
56       * related with this service.
57       * 
58       * @param listener The listener to use
59       */
60      void removeListener(IoServiceListener listener);
61  
62      /**
63       * @return <tt>true</tt> if and if only {@link #dispose()} method has
64       * been called.  Please note that this method will return <tt>true</tt>
65       * even after all the related resources are released.
66       */
67      boolean isDisposing();
68  
69      /**
70       * @return <tt>true</tt> if and if only all resources of this processor
71       * have been disposed.
72       */
73      boolean isDisposed();
74  
75      /**
76       * Releases any resources allocated by this service.  Please note that
77       * this method might block as long as there are any sessions managed by
78       * this service.
79       */
80      void dispose();
81  
82      /**
83       * Releases any resources allocated by this service.  Please note that
84       * this method might block as long as there are any sessions managed by this service.
85       *
86       * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
87       * will probably lead to a deadlock.
88       *
89       * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
90       */
91      void dispose(boolean awaitTermination);
92  
93      /**
94       * @return the handler which will handle all connections managed by this service.
95       */
96      IoHandler getHandler();
97  
98      /**
99       * Sets the handler which will handle all connections managed by this service.
100      * 
101      * @param handler The IoHandler to use
102      */
103     void setHandler(IoHandler handler);
104 
105     /**
106      * @return the map of all sessions which are currently managed by this
107      * service.  The key of map is the {@link IoSession#getId() ID} of the
108      * session. An empty collection if there's no session.
109      */
110     Map<Long, IoSession> getManagedSessions();
111 
112     /**
113      * @return the number of all sessions which are currently managed by this
114      * service.
115      */
116     int getManagedSessionCount();
117 
118     /**
119      * @return the default configuration of the new {@link IoSession}s
120      * created by this service.
121      */
122     IoSessionConfig getSessionConfig();
123 
124     /**
125      * @return the {@link IoFilterChainBuilder} which will build the
126      * {@link IoFilterChain} of all {@link IoSession}s which is created
127      * by this service.
128      * The default value is an empty {@link DefaultIoFilterChainBuilder}.
129      */
130     IoFilterChainBuilder getFilterChainBuilder();
131 
132     /**
133      * Sets the {@link IoFilterChainBuilder} which will build the
134      * {@link IoFilterChain} of all {@link IoSession}s which is created
135      * by this service.
136      * If you specify <tt>null</tt> this property will be set to
137      * an empty {@link DefaultIoFilterChainBuilder}.
138      * 
139      * @param builder The filter chain builder to use
140      */
141     void setFilterChainBuilder(IoFilterChainBuilder builder);
142 
143     /**
144      * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
145      * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
146      * but a {@link DefaultIoFilterChainBuilder}.  Modifying the returned builder
147      * won't affect the existing {@link IoSession}s at all, because
148      * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
149      *
150      * @return The filter chain in use
151      * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
152      *                               not a {@link DefaultIoFilterChainBuilder}
153      */
154     DefaultIoFilterChainBuilder getFilterChain();
155 
156     /**
157      * @return a value of whether or not this service is active
158      */
159     boolean isActive();
160 
161     /**
162      * @return the time when this service was activated.  It returns the last
163      * time when this service was activated if the service is not active now.
164      */
165     long getActivationTime();
166 
167     /**
168      * Writes the specified {@code message} to all the {@link IoSession}s
169      * managed by this service.  This method is a convenience shortcut for
170      * {@link IoUtil#broadcast(Object, Collection)}.
171      * 
172      * @param message the message to broadcast
173      * @return The set of WriteFuture associated to the message being broadcasted
174      */
175     Set<WriteFuture> broadcast(Object message);
176 
177     /**
178      * @return the {@link IoSessionDataStructureFactory} that provides
179      * related data structures for a new session created by this service.
180      */
181     IoSessionDataStructureFactory getSessionDataStructureFactory();
182 
183     /**
184      * Sets the {@link IoSessionDataStructureFactory} that provides
185      * related data structures for a new session created by this service.
186      * 
187      * @param sessionDataStructureFactory The factory to use
188      */
189     void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
190 
191     /**
192      * @return The number of bytes scheduled to be written
193      */
194     int getScheduledWriteBytes();
195 
196     /**
197      * @return The number of messages scheduled to be written
198      */
199     int getScheduledWriteMessages();
200 
201     /**
202      * @return The statistics object for this service.
203      */
204     IoServiceStatistics getStatistics();
205 }