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.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       * Returns 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      void addListener(IoServiceListener listener);
51  
52      /**
53       * Removed an existing {@link IoServiceListener} that listens any events
54       * related with this service.
55       */
56      void removeListener(IoServiceListener listener);
57  
58      /**
59       * Returns <tt>true</tt> if and if only {@link #dispose()} method has
60       * been called.  Please note that this method will return <tt>true</tt>
61       * even after all the related resources are released.
62       */
63      boolean isDisposing();
64  
65      /**
66       * Returns <tt>true</tt> if and if only all resources of this processor
67       * have been disposed.
68       */
69      boolean isDisposed();
70  
71      /**
72       * Releases any resources allocated by this service.  Please note that
73       * this method might block as long as there are any sessions managed by
74       * this service.
75       */
76      void dispose();
77  
78      /**
79       * Releases any resources allocated by this service.  Please note that
80       * this method might block as long as there are any sessions managed by this service.
81       *
82       * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true
83       * will probably lead to a deadlock.
84       *
85       * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated
86       */
87      void dispose(boolean awaitTermination);
88  
89      /**
90       * Returns the handler which will handle all connections managed by this service.
91       */
92      IoHandler getHandler();
93  
94      /**
95       * Sets the handler which will handle all connections managed by this service.
96       */
97      void setHandler(IoHandler handler);
98  
99      /**
100      * Returns the map of all sessions which are currently managed by this
101      * service.  The key of map is the {@link IoSession#getId() ID} of the
102      * session.
103      *
104      * @return the sessions. An empty collection if there's no session.
105      */
106     Map<Long, IoSession> getManagedSessions();
107 
108     /**
109      * Returns the number of all sessions which are currently managed by this
110      * service.
111      */
112     int getManagedSessionCount();
113 
114     /**
115      * Returns the default configuration of the new {@link IoSession}s
116      * created by this service.
117      */
118     IoSessionConfig getSessionConfig();
119 
120     /**
121      * Returns the {@link IoFilterChainBuilder} which will build the
122      * {@link IoFilterChain} of all {@link IoSession}s which is created
123      * by this service.
124      * The default value is an empty {@link DefaultIoFilterChainBuilder}.
125      */
126     IoFilterChainBuilder getFilterChainBuilder();
127 
128     /**
129      * Sets the {@link IoFilterChainBuilder} which will build the
130      * {@link IoFilterChain} of all {@link IoSession}s which is created
131      * by this service.
132      * If you specify <tt>null</tt> this property will be set to
133      * an empty {@link DefaultIoFilterChainBuilder}.
134      */
135     void setFilterChainBuilder(IoFilterChainBuilder builder);
136 
137     /**
138      * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
139      * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
140      * but a {@link DefaultIoFilterChainBuilder}.  Modifying the returned builder
141      * won't affect the existing {@link IoSession}s at all, because
142      * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
143      *
144      * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
145      *                               not a {@link DefaultIoFilterChainBuilder}
146      */
147     DefaultIoFilterChainBuilder getFilterChain();
148 
149     /**
150      * Returns a value of whether or not this service is active
151      *
152      * @return whether of not the service is active.
153      */
154     boolean isActive();
155 
156     /**
157      * Returns the time when this service was activated.  It returns the last
158      * time when this service was activated if the service is not active now.
159      *
160      * @return The time by using {@link System#currentTimeMillis()}
161      */
162     long getActivationTime();
163 
164     /**
165      * Writes the specified {@code message} to all the {@link IoSession}s
166      * managed by this service.  This method is a convenience shortcut for
167      * {@link IoUtil#broadcast(Object, Collection)}.
168      */
169     Set<WriteFuture> broadcast(Object message);
170 
171     /**
172      * Returns the {@link IoSessionDataStructureFactory} that provides
173      * related data structures for a new session created by this service.
174      */
175     IoSessionDataStructureFactory getSessionDataStructureFactory();
176 
177     /**
178      * Sets the {@link IoSessionDataStructureFactory} that provides
179      * related data structures for a new session created by this service.
180      */
181     void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
182 
183     /**
184      * Returns the number of bytes scheduled to be written
185      *
186      * @return The number of bytes scheduled to be written
187      */
188     int getScheduledWriteBytes();
189 
190     /**
191      * Returns the number of messages scheduled to be written
192      *
193      * @return The number of messages scheduled to be written
194      */
195     int getScheduledWriteMessages();
196 
197     /**
198      * Returns the IoServiceStatistics object for this service.
199      * 
200      * @return The statistics object for this service.
201      */
202     IoServiceStatistics getStatistics();
203 }