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 * @return 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 * @param listener The listener to add 051 */ 052 void addListener(IoServiceListener listener); 053 054 /** 055 * Removed an existing {@link IoServiceListener} that listens any events 056 * related with this service. 057 * 058 * @param listener The listener to use 059 */ 060 void removeListener(IoServiceListener listener); 061 062 /** 063 * @return <tt>true</tt> if and if only {@link #dispose()} method has 064 * been called. Please note that this method will return <tt>true</tt> 065 * even after all the related resources are released. 066 */ 067 boolean isDisposing(); 068 069 /** 070 * @return <tt>true</tt> if and if only all resources of this processor 071 * have been disposed. 072 */ 073 boolean isDisposed(); 074 075 /** 076 * Releases any resources allocated by this service. Please note that 077 * this method might block as long as there are any sessions managed by 078 * this service. 079 */ 080 void dispose(); 081 082 /** 083 * Releases any resources allocated by this service. Please note that 084 * this method might block as long as there are any sessions managed by this service. 085 * 086 * Warning : calling this method from a IoFutureListener with <code>awaitTermination</code> = true 087 * will probably lead to a deadlock. 088 * 089 * @param awaitTermination When true this method will block until the underlying ExecutorService is terminated 090 */ 091 void dispose(boolean awaitTermination); 092 093 /** 094 * @return the handler which will handle all connections managed by this service. 095 */ 096 IoHandler getHandler(); 097 098 /** 099 * 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}