KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xsocket > stream > IMultithreadedServer


1 // $Id: IMultithreadedServer.java 1540 2007-07-21 13:09:27Z grro $
2 /*
3  * Copyright (c) xsocket.org, 2006 - 2007. All rights reserved.
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  *
19  * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
20  * The latest copy of this software may be found on http://www.xsocket.org/
21  */
22 package org.xsocket.stream;
23
24 import java.io.Closeable JavaDoc;
25 import java.io.IOException JavaDoc;
26 import java.net.InetAddress JavaDoc;
27 import java.util.Map JavaDoc;
28 import java.util.concurrent.Executor JavaDoc;
29
30
31 import org.xsocket.IWorkerPool;
32
33
34
35
36
37
38 /**
39  * A server accepts new incomming connections, and delegates the handling of the
40  * {@link INonBlockingConnection} to the assigned handler.
41  *
42  * The server includes dispatchers, which are responsible to perform the
43  * socket I/O operations. A connection is assigned to one dispatcher. <br>
44  * To handle application-relevant events like <code>onData</code>,
45  * <code>onClose</code> or <code>onConnect</code> the appropriated callback method
46  * of the assigned {@link IHandler} will be called. The supported callback
47  * methods of the handler will be analysed by using reflection during the server start-up
48  * phase. The callback method will be marked by implementing the specifc interface
49  * like {@link IDataHandler} or {@link IConnectHandler}. Often a
50  * handler will implement serveral handler interfaces.<br>
51  * If a handler implements the {@link IConnectionScoped} interface, a clone of
52  * the registered handler will be created for each new incomming connection.
53  * <br>
54  * E.g.
55  * <pre>
56  * ...
57  * IMultithreadedConnectionServer smtpServer = new MultithreadedTcpServer(port, new SmtpProtcolHandler());
58  * StreamUtils.start(server);
59  * ...
60  *
61  *
62  * // Handler definition
63  * class SmtpProtcolHandler implements IDataHandler, IConnectHandler, IConnectionScoped {
64  * private ArrayList<String> rcptTos = new ArrayList<String>();
65  * ...
66  *
67  * public boolean onConnect(INonBlockingConnection connection) throws IOException {
68  * connection.setAutoflush(false);
69  * connection.setFlushmode(FlushMode.ASYNC);
70  *
71  * connection.write("220 this is the example smtp server" + LINE_DELIMITER);
72  * connection.flush();
73  * return true;
74  * }
75  *
76  *
77  *
78  * public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException {
79  * switch (state) {
80  * case COMMAND_HANDLING:
81  * handleCommand(connection);
82  * break;
83  *
84  * case MESSAGE_DATA_HANDLING:
85  * handleMessageData(connection);
86  * break;
87  * }
88  * return true;
89  * }
90  *
91  * private void handleCommand(INonBlockingConnection connection) throws IOException, BufferUnderflowException {
92  * ...
93  *
94  *
95  *
96  * &#064Override
97  * public Object clone() throws CloneNotSupportedException {
98  * SmtpProtocolHandler copy = (SmtpProtocolHandler) super.clone();
99  * copy.rcptTos = new ArrayList<String>(); // deep copy!
100  * return copy;
101  * }
102  * }
103  * </pre>
104  *
105  *
106  * @author grro@xsocket.org
107  */
108 public interface IMultithreadedServer extends Runnable JavaDoc, Closeable JavaDoc {
109
110
111     /**
112      * the default receive buffer preallocation size
113      * @deprecated
114      */
115     public static final int DEFAULT_RECEIVE_BUFFER_PREALLOCATION_SIZE = 64768;
116     
117
118     /**
119      * the default idle timeout
120      */
121     public static final int DEFAULT_IDLE_TIMEOUT_SEC = 1 * 60 * 60; // one hour
122
123     
124     
125     /**
126      * the default connection timeout
127      */
128     public static final int DEFAULT_CONNECTION_TIMEOUT_SEC = Integer.MAX_VALUE; // no timeout
129
130
131     public static final String JavaDoc SO_RCVBUF = IConnection.SO_RCVBUF;
132     public static final String JavaDoc SO_REUSEADDR = IConnection.SO_REUSEADDR;
133     
134     
135     /**
136      * signals, if service is running
137      *
138      * @return true, if the server is running
139      */
140     public boolean isOpen();
141
142     
143     /**
144      * set the handler. The server performs
145      * the initialzation of the given handler
146      * immediately.
147      *
148      * @param handler the handler. (supported: IConnectHandler, IDisconnectHandler, IDataHandler, ITimeoutHandler, IConnectionScoped, ILifeCycle)
149      */
150     public void setHandler(IHandler handler);
151     
152     
153     
154     /**
155      * replace the worker pool with the given one. By setting the WorkerPool with <code>null</code> the
156      * worker pool will be deactivated. The callback handler will be executed by the main
157      * dispatching thread. If the handler performs blocking operations, the disptaching will
158      * also be blocked!<br><br>
159      *
160      * By closing the endpoint, the close method of the worker pool will be called
161      *
162      * @deprecated worker pool should only be set by calling the constructor
163      *
164      * @param workerPool the worker pool to set or <code>null</code> to deactivate the worker pool
165      */
166     public void setWorkerPool(IWorkerPool workerPool);
167
168
169     /**
170      * return the worker pool
171      *
172      * @deprecated use {@link IMultithreadedServer#getWorkerpool()} instead
173      * @return the worker pool
174      */
175     public IWorkerPool getWorkerPool();
176     
177
178     /**
179      * return the worker pool
180      *
181      * @return the worker pool
182      */
183     public Executor JavaDoc getWorkerpool();
184
185     
186     /**
187      * set the size of the preallocation buffer,
188      * for reading incomming data
189      *
190      * @deprecated use System.property instead. see {@link org.xsocket.stream.io.impl.IoProvider}
191      * @param size preallocation buffer size
192      */
193     public void setReceiveBufferPreallocationSize(int size);
194
195     
196     /**
197      * get the size of the preallocation buffer,
198      * for reading incomming data
199      *
200      * @deprecated on replacement
201      * @return preallocation buffer size
202      */
203     public int getReceiveBufferPreallocationSize();
204     
205     
206
207     
208     /**
209      * returns the idle timeout in sec.
210      *
211      * @return idle timeout in sec
212      */
213     public int getIdleTimeoutSec();
214     
215     
216     
217     /**
218      * sets the idle timeout in sec
219      *
220      * @param timeoutInSec idle timeout in sec
221      */
222     public void setIdleTimeoutSec(int timeoutInSec);
223
224     
225     /**
226      * adds a listener
227      * @param listener gthe listener to add
228      */
229     public void addListener(IMutlithreadedServerListener listener);
230     
231     
232     /**
233      * removes a listener
234      * @param listener the listener to remove
235      * @return true, is the listener has been removed
236      */
237     public boolean removeListener(IMutlithreadedServerListener listener);
238     
239     
240     /**
241      * gets the connection timeout
242      *
243      * @return connection timeout
244      */
245     public int getConnectionTimeoutSec();
246     
247     
248     /**
249      * sets the max time for a connections. By
250      * exceeding this time the connection will be
251      * terminated
252      *
253      * @param timeoutSec the connection timeout in sec
254      */
255     public void setConnectionTimeoutSec(int timeoutSec);
256     
257     
258     
259     /**
260      * get the server port
261      *
262      * @return the server port
263      */
264     public int getLocalPort();
265     
266
267     /**
268      * get the local address
269      * @return the local address
270      */
271     public InetAddress JavaDoc getLocalAddress();
272
273     
274     /**
275      * set the dispatcher pool size
276      *
277      * @deprecated
278      * @param size the dispatcher pool size
279      */
280     public void setDispatcherPoolSize(int size);
281     
282     
283     /**
284      * get the dispatcher pool size
285      *
286      * @deprecate
287      *
288      * @return the dispatcher pool size
289      */
290     public int getDispatcherPoolSize();
291     
292     
293     
294     /**
295      * returns the vlaue of a option
296      *
297      * @param name the name of the option
298      * @return the value of the option
299      * @throws IOException In an I/O error occurs
300      */
301     public Object JavaDoc getOption(String JavaDoc name) throws IOException JavaDoc;
302     
303     
304     
305     /**
306      * Returns an unmodifiable map of the options supported by this endpont.
307      *
308      * The key in the returned map is the name of a option, and its value
309      * is the type of the option value. The returned map will never contain null keys or values.
310      *
311      * @return An unmodifiable map of the options supported by this channel
312      */
313     public Map JavaDoc<String JavaDoc,Class JavaDoc> getOptions();
314 }
315
Popular Tags