001/* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 * 019 */ 020package org.apache.mina.core.service; 021 022import java.util.Map; 023import java.util.Set; 024 025import org.apache.mina.core.IoUtil; 026import org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder; 027import org.apache.mina.core.filterchain.IoFilterChain; 028import org.apache.mina.core.filterchain.IoFilterChainBuilder; 029import org.apache.mina.core.future.WriteFuture; 030import org.apache.mina.core.session.IoSession; 031import org.apache.mina.core.session.IoSessionConfig; 032import org.apache.mina.core.session.IoSessionDataStructureFactory; 033 034/** 035 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s 036 * that provide I/O service and manage {@link IoSession}s. 037 * 038 * @author <a href="http://mina.apache.org">Apache MINA Project</a> 039 */ 040public interface IoService { 041 /** 042 * Returns the {@link TransportMetadata} that this service runs on. 043 */ 044 TransportMetadata getTransportMetadata(); 045 046 /** 047 * Adds an {@link IoServiceListener} that listens any events related with 048 * this service. 049 */ 050 void addListener(IoServiceListener listener); 051 052 /** 053 * Removed an existing {@link IoServiceListener} that listens any events 054 * related with this service. 055 */ 056 void removeListener(IoServiceListener listener); 057 058 /** 059 * Returns <tt>true</tt> if and if only {@link #dispose()} method has 060 * been called. Please note that this method will return <tt>true</tt> 061 * even after all the related resources are released. 062 */ 063 boolean isDisposing(); 064 065 /** 066 * Returns <tt>true</tt> if and if only all resources of this processor 067 * have been disposed. 068 */ 069 boolean isDisposed(); 070 071 /** 072 * Releases any resources allocated by this service. Please note that 073 * this method might block as long as there are any sessions managed by 074 * this service. 075 */ 076 void dispose(); 077 078 /** 079 * Releases any resources allocated by this service. Please note that 080 * this method might block as long as there are any sessions managed by this service. 081 * 082 * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true 083 * will probably lead to a deadlock. 084 * 085 * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated 086 */ 087 void dispose(boolean awaitTermination); 088 089 /** 090 * Returns the handler which will handle all connections managed by this service. 091 */ 092 IoHandler getHandler(); 093 094 /** 095 * Sets the handler which will handle all connections managed by this service. 096 */ 097 void setHandler(IoHandler handler); 098 099 /** 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}