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       * Returns the handler which will handle all connections managed by this service.
80       */
81      IoHandler getHandler();
82  
83      /**
84       * Sets the handler which will handle all connections managed by this service.
85       */
86      void setHandler(IoHandler handler);
87  
88      /**
89       * Returns the map of all sessions which are currently managed by this
90       * service.  The key of map is the {@link IoSession#getId() ID} of the
91       * session.
92       *
93       * @return the sessions. An empty collection if there's no session.
94       */
95      Map<Long, IoSession> getManagedSessions();
96  
97      /**
98       * Returns the number of all sessions which are currently managed by this
99       * service.
100      */
101     int getManagedSessionCount();
102 
103     /**
104      * Returns the default configuration of the new {@link IoSession}s
105      * created by this service.
106      */
107     IoSessionConfig getSessionConfig();
108 
109     /**
110      * Returns the {@link IoFilterChainBuilder} which will build the
111      * {@link IoFilterChain} of all {@link IoSession}s which is created
112      * by this service.
113      * The default value is an empty {@link DefaultIoFilterChainBuilder}.
114      */
115     IoFilterChainBuilder getFilterChainBuilder();
116 
117     /**
118      * Sets the {@link IoFilterChainBuilder} which will build the
119      * {@link IoFilterChain} of all {@link IoSession}s which is created
120      * by this service.
121      * If you specify <tt>null</tt> this property will be set to
122      * an empty {@link DefaultIoFilterChainBuilder}.
123      */
124     void setFilterChainBuilder(IoFilterChainBuilder builder);
125 
126     /**
127      * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>{@link #getFilterChainBuilder()}<tt> )</tt>.
128      * Please note that the returned object is not a <b>real</b> {@link IoFilterChain}
129      * but a {@link DefaultIoFilterChainBuilder}.  Modifying the returned builder
130      * won't affect the existing {@link IoSession}s at all, because
131      * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
132      *
133      * @throws IllegalStateException if the current {@link IoFilterChainBuilder} is
134      *                               not a {@link DefaultIoFilterChainBuilder}
135      */
136     DefaultIoFilterChainBuilder getFilterChain();
137 
138     /**
139      * Returns a value of whether or not this service is active
140      *
141      * @return whether of not the service is active.
142      */
143     boolean isActive();
144 
145     /**
146      * Returns the time when this service was activated.  It returns the last
147      * time when this service was activated if the service is not active now.
148      *
149      * @return The time by using {@link System#currentTimeMillis()}
150      */
151     long getActivationTime();
152 
153     /**
154      * Writes the specified {@code message} to all the {@link IoSession}s
155      * managed by this service.  This method is a convenience shortcut for
156      * {@link IoUtil#broadcast(Object, Collection)}.
157      */
158     Set<WriteFuture> broadcast(Object message);
159 
160     /**
161      * Returns the {@link IoSessionDataStructureFactory} that provides
162      * related data structures for a new session created by this service.
163      */
164     IoSessionDataStructureFactory getSessionDataStructureFactory();
165 
166     /**
167      * Sets the {@link IoSessionDataStructureFactory} that provides
168      * related data structures for a new session created by this service.
169      */
170     void setSessionDataStructureFactory(IoSessionDataStructureFactory sessionDataStructureFactory);
171 
172     /**
173      * Returns the number of bytes scheduled to be written
174      *
175      * @return The number of bytes scheduled to be written
176      */
177     int getScheduledWriteBytes();
178 
179     /**
180      * Returns the number of messages scheduled to be written
181      *
182      * @return The number of messages scheduled to be written
183      */
184     int getScheduledWriteMessages();
185 
186     /**
187      * Returns the IoServiceStatistics object for this service.
188      * 
189      * @return The statistics object for this service.
190      */
191     IoServiceStatistics getStatistics();
192 }