001: /*
002: * Copyright (c) xsocket.org, 2006 - 2008. All rights reserved.
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2.1 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: *
018: * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
019: * The latest copy of this software may be found on http://www.xsocket.org/
020: */
021: package org.xsocket.connection;
022:
023: import java.io.Closeable;
024: import java.io.IOException;
025: import java.net.InetAddress;
026: import java.nio.channels.ClosedChannelException;
027: import java.util.Map;
028: import java.util.concurrent.Executor;
029:
030: import org.xsocket.connection.IConnection.FlushMode;
031:
032: /**
033: * A server accepts new incoming connections, and delegates the handling of the
034: * {@link INonBlockingConnection} to the assigned handler.
035: *
036: * The server includes dispatchers, which are responsible to perform the
037: * socket I/O operations. A connection is assigned to one dispatcher. <br>
038: * To handle application-relevant events like <code>onData</code>,
039: * <code>onClose</code> or <code>onConnect</code> the appropriated callback method
040: * of the assigned {@link IHandler} will be called. The supported callback
041: * methods of the handler will be analyzed by using reflection during the server start-up
042: * phase. The callback method will be marked by implementing the specific interface
043: * like {@link IDataHandler} or {@link IConnectHandler}. Often a
044: * handler will implement several handler interfaces.<br>
045: * <br>
046: * E.g.
047: * <pre>
048: * ...
049: * IServer smtpServer = new Server(port, new SmtpProtcolHandler());
050: * ConnectionUtils.start(server);
051: * ...
052: *
053: *
054: * // Handler definition
055: * class SmtpProtcolHandler implements IDataHandler, IConnectHandler {
056: * ...
057: *
058: * public boolean onConnect(INonBlockingConnection connection) throws IOException {
059: * connection.setAutoflush(false);
060: * connection.setFlushmode(FlushMode.ASYNC);
061: *
062: * connection.write("220 this is the example smtp server" + LINE_DELIMITER);
063: * connection.flush();
064: * return true;
065: * }
066: *
067: *
068: *
069: * public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException {
070: * switch (state) {
071: * case COMMAND_HANDLING:
072: * handleCommand(connection);
073: * break;
074: *
075: * case MESSAGE_DATA_HANDLING:
076: * handleMessageData(connection);
077: * break;
078: * }
079: * return true;
080: * }
081: *
082: * private void handleCommand(INonBlockingConnection connection) throws IOException, BufferUnderflowException {
083: * ...
084: * }
085: * }
086: * </pre>
087: *
088: *
089: * @author grro@xsocket.org
090: */
091: public interface IServer extends Runnable, Closeable {
092:
093: /**
094: * the default idle timeout
095: */
096: public static final int DEFAULT_IDLE_TIMEOUT_SEC = 1 * 60 * 60; // one hour
097:
098: /**
099: * the default connection timeout
100: */
101: public static final int DEFAULT_CONNECTION_TIMEOUT_SEC = Integer.MAX_VALUE; // no timeout
102:
103: /**
104: * the dafault host address
105: */
106: public static final String DEFAULT_HOST_ADDRESS = "0.0.0.0";
107:
108: public static final String SO_RCVBUF = IConnection.SO_RCVBUF;
109: public static final String SO_REUSEADDR = IConnection.SO_REUSEADDR;
110:
111: public static final int DEFAULT_READ_TRANSFER_PREALLOCATION_SIZE = 65536;
112: public static final int DEFAULT_READ_TRANSFER_PREALLOCATION_MIN_SIZE = 64;
113: public static final boolean DEFAULT_READ_TRANSFER_USE_DIRECT = true;
114:
115: /**
116: * signals, if service is running
117: *
118: * @return true, if the server is running
119: */
120: public boolean isOpen();
121:
122: /**
123: * returns the idle timeout in millis.
124: *
125: * @return idle timeout in millis
126: */
127: public long getIdleTimeoutMillis();
128:
129: /**
130: * sets the idle timeout in millis
131: *
132: * @param timeoutInSec idle timeout in millis
133: */
134: public void setIdleTimeoutMillis(long timeoutInMillis);
135:
136: /**
137: * gets the connection timeout
138: *
139: * @return connection timeout
140: */
141: public long getConnectionTimeoutMillis();
142:
143: /**
144: * sets the max time for a connections. By
145: * exceeding this time the connection will be
146: * terminated
147: *
148: * @param timeoutSec the connection timeout in millis
149: */
150: public void setConnectionTimeoutMillis(long timeoutMillis);
151:
152: /**
153: * set the send delay time for a connection. Data to write will be buffered
154: * internally and be written to the underlying subsystem
155: * based on the given write rate.
156: * The write methods will <b>not</b> block for this time. <br>
157: *
158: * By default the write transfer rate is set with UNLIMITED <br><br>
159: *
160: * Reduced write transfer is only supported for FlushMode.ASYNC. see
161: * {@link INonBlockingConnection#setFlushmode(org.xsocket.connection.IConnection.FlushMode))}
162: *
163: * @param bytesPerSecond the transfer rate of the outgoing data
164: * @throws IOException If some other I/O error occurs
165: */
166: public void setWriteTransferRate(int bytesPerSecond)
167: throws IOException;
168:
169: /**
170: * set the read rate. By default the read transfer rate is set with UNLIMITED <br><br>
171: *
172: * @param bytesPerSecond the transfer rate of the outgoing data
173: * @throws IOException If some other I/O error occurs
174: */
175: // public void setReadTransferRate(int bytesPerSecond) throws IOException;
176:
177: /**
178: * returns the number of open connections
179: * @return the number of open connections
180: */
181: public int getNumberOfOpenConnections();
182:
183: /**
184: * get the server port
185: *
186: * @return the server port
187: */
188: public int getLocalPort();
189:
190: /**
191: * return the worker pool
192: *
193: * @return the worker pool
194: */
195: public Executor getWorkerpool();
196:
197: /**
198: * sets the worker pool
199: * @param workerpool the workerpool
200: */
201: public void setWorkerpool(Executor workerpool);
202:
203: /**
204: * gets the handler
205: * @return the handler
206: */
207: public IHandler getHandler();
208:
209: /**
210: * sets the flush mode for new connections. See {@link INonBlockingConnection#setFlushmode(FlushMode)}
211: * for more information
212: *
213: * @param flusmode the flush mode
214: */
215: public void setFlushMode(FlushMode flusmode);
216:
217: /**
218: * return the flush mode for new connections
219: *
220: * @return the flush mode
221: */
222: public FlushMode getFlushMode();
223:
224: /**
225: * set autoflush for new connections. See {@link IReadWriteableConnection#setAutoflush(boolean)}
226: * for more information
227: *
228: * @param autoflush true if autoflush should be activated
229: */
230: public void setAutoflush(boolean autoflush);
231:
232: /**
233: * get autoflush. See {@link IReadWriteableConnection#setAutoflush(boolean)}
234: * for more information
235: *
236: * @return true, if autoflush is activated
237: */
238: public boolean getAutoflush();
239:
240: /**
241: * adds a listener
242: * @param listener gthe listener to add
243: */
244: public void addListener(IServerListener listener);
245:
246: /**
247: * removes a listener
248: * @param listener the listener to remove
249: * @return true, is the listener has been removed
250: */
251: public boolean removeListener(IServerListener listener);
252:
253: /**
254: * get the local address
255: * @return the local address
256: */
257: public InetAddress getLocalAddress();
258:
259: /**
260: * returns the vlaue of a option
261: *
262: * @param name the name of the option
263: * @return the value of the option
264: * @throws IOException In an I/O error occurs
265: */
266: public Object getOption(String name) throws IOException;
267:
268: /**
269: * set the log message, which will be printed out during the start up
270: *
271: * @param message the startUp log message
272: */
273: public void setStartUpLogMessage(String message);
274:
275: /**
276: * returns the startUp log message
277: *
278: * @return the startUp log message
279: */
280: public String getStartUpLogMessage();
281:
282: /**
283: * Returns an unmodifiable map of the options supported by this endpont.
284: *
285: * The key in the returned map is the name of a option, and its value
286: * is the type of the option value. The returned map will never contain null keys or values.
287: *
288: * @return An unmodifiable map of the options supported by this channel
289: */
290: @SuppressWarnings("unchecked")
291: public Map<String, Class> getOptions();
292: }
|