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.Flushable;
024: import java.io.IOException;
025: import java.io.UnsupportedEncodingException;
026: import java.net.SocketTimeoutException;
027: import java.nio.BufferOverflowException;
028: import java.nio.BufferUnderflowException;
029: import java.nio.ByteBuffer;
030: import java.nio.channels.ClosedChannelException;
031: import java.nio.channels.FileChannel;
032: import java.nio.channels.GatheringByteChannel;
033: import java.nio.channels.ReadableByteChannel;
034: import java.nio.channels.WritableByteChannel;
035: import java.util.concurrent.Executor;
036:
037: import org.xsocket.IDataSink;
038: import org.xsocket.IDataSource;
039: import org.xsocket.MaxReadSizeExceededException;
040:
041: /**
042: * A connection which accesses the underlying channel in a non-blocking manner. <br><br>
043: *
044: * @author grro@xsocket.org
045: */
046: public interface INonBlockingConnection extends IConnection,
047: IDataSource, IDataSink, GatheringByteChannel,
048: ReadableByteChannel, WritableByteChannel, Flushable {
049:
050: public static final int UNLIMITED = Integer.MAX_VALUE;
051:
052: /**
053: * set the connection handler
054: *
055: * @param handler the handler
056: * @throws IOException If some other I/O error occurs
057: */
058: public void setHandler(IHandler handler) throws IOException;
059:
060: /**
061: * gets the encoding (used by string related methods like write(String) ...)
062: *
063: * @return the encoding
064: */
065: public String getEncoding();
066:
067: /**
068: * sets the encoding (used by string related methods like write(String) ...)
069: *
070: * @param encoding the encoding
071: */
072: public void setEncoding(String encoding);
073:
074: /**
075: * set autoflush. If autoflush is activated, each write call
076: * will cause a flush. <br><br>
077: *
078: * By default the autoflush is deactivated
079: *
080: * @param autoflush true if autoflush should be activated
081: */
082: public void setAutoflush(boolean autoflush);
083:
084: /**
085: * get autoflush
086: *
087: * @return true, if autoflush is activated
088: */
089: public boolean isAutoflush();
090:
091: /**
092: * flush the send buffer. The method call will block until
093: * the outgoing data has been flushed into the underlying
094: * os-specific send buffer.
095: *
096: * @throws IOException If some other I/O error occurs
097: * @throws SocketTimeoutException If the timeout has been reached
098: * @throws ClosedChannelException if the underlying channel is closed
099: */
100: public void flush() throws ClosedChannelException, IOException,
101: SocketTimeoutException;
102:
103: /**
104: * set the flush mode <br><br> By setting the flush mode with ASYNC (default is SYNC)
105: * the data will be transferred to the underlying connection in a asynchronous way.
106: * In most cases there are high performance improvements. If the {@link IReadWriteableConnection#write(ByteBuffer)}
107: * or {@link IReadWriteableConnection#write(ByteBuffer[])} method will be used, the flush mode
108: * {@link FlushMode#ASYNC} could have side-effects. Because the buffer will be
109: * written asynchronous, it could occur, that the passed-over buffers are not already
110: * written by returning from the write call.
111: *
112: * @param flushMode {@link FlushMode#ASYNC} if flush should be performed asynchronous,
113: * {@link FlushMode#SYNC} if flush should be perform synchronous
114: */
115: public void setFlushmode(FlushMode flushMode);
116:
117: /**
118: * return the flush mode
119: * @return the flush mode
120: */
121: public FlushMode getFlushmode();
122:
123: /**
124: * ad hoc activation of a secured mode (SSL). By performing of this
125: * method all remaining data to send will be flushed.
126: * After this all data will be sent and received in the secured mode
127: *
128: * @throws IOException If some other I/O error occurs
129: */
130: public void activateSecuredMode() throws IOException;
131:
132: /**
133: * returns the size of the data which have already been written, but not
134: * yet transferred to the underlying socket.
135: *
136: * @return the size of the pending data to write
137: */
138: public int getPendingWriteDataSize();
139:
140: /**
141: * suspend reading data from the underlying subsystem
142: *
143: * @throws IOException If some other I/O error occurs
144: */
145: public void suspendRead() throws IOException;
146:
147: /**
148: * resume reading data from the underlying subsystem
149: *
150: * @throws IOException If some other I/O error occurs
151: */
152: public void resumeRead() throws IOException;
153:
154: /**
155: * write a message
156: *
157: * @param message the message to write
158: * @param encoding the encoding which should be used th encode the chars into byte (e.g. `US-ASCII` or `UTF-8`)
159: * @return the number of written bytes
160: * @throws BufferOverflowException If the no enough space is available
161: * @throws IOException If some other I/O error occurs
162: */
163: public int write(String message, String encoding)
164: throws IOException, BufferOverflowException;
165:
166: /**
167: * read a ByteBuffer by using a delimiter. The default encoding will be used to decode the delimiter
168: *
169: * For performance reasons, the ByteBuffer readByteBuffer method is
170: * generally preferable to get bytes
171: *
172: * @param delimiter the delimiter
173: * @param encoding the encoding to use
174: * @return the ByteBuffer
175: * @throws BufferUnderflowException If not enough data is available
176: * @throws IOException If some other I/O error occurs
177: */
178: public ByteBuffer[] readByteBufferByDelimiter(String delimiter,
179: String encoding) throws IOException,
180: BufferUnderflowException;
181:
182: /**
183: * read a ByteBuffer by using a delimiter
184: *
185: * For performance reasons, the ByteBuffer readByteBuffer method is
186: * generally preferable to get bytes
187: *
188: * @param delimiter the delimiter
189: * @param encoding the encoding of the delimiter
190: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
191: * @return the ByteBuffer
192: * @throws BufferUnderflowException If not enough data is available
193: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
194: * @throws IOException If some other I/O error occurs
195: */
196: public ByteBuffer[] readByteBufferByDelimiter(String delimiter,
197: String encoding, int maxLength) throws IOException,
198: BufferUnderflowException, MaxReadSizeExceededException;
199:
200: /**
201: * read a byte array by using a delimiter
202: *
203: * For performance reasons, the ByteBuffer readByteBuffer method is
204: * generally preferable to get bytes
205: *
206: * @param delimiter the delimiter
207: * @param encoding the encoding to use
208: * @return the read bytes
209: * @throws BufferUnderflowException If not enough data is available
210: * @throws IOException If some other I/O error occurs
211: */
212: public byte[] readBytesByDelimiter(String delimiter, String encoding)
213: throws IOException, BufferUnderflowException;
214:
215: /**
216: * read a byte array by using a delimiter
217: *
218: * For performance reasons, the ByteBuffer readByteBuffer method is
219: * generally preferable to get bytes
220: *
221: * @param delimiter the delimiter
222: * @param encoding the encoding to use
223: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
224: * @return the read bytes
225: * @throws BufferUnderflowException If not enough data is available
226: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
227: * @throws IOException If some other I/O error occurs
228: */
229: public byte[] readBytesByDelimiter(String delimiter,
230: String encoding, int maxLength) throws IOException,
231: BufferUnderflowException, MaxReadSizeExceededException;
232:
233: /**
234: * read a string by using a delimiter
235: *
236: * @param delimiter the delimiter
237: * @param encoding the encoding to use
238: * @return the string
239: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
240: * @throws IOException If some other I/O error occurs
241: * @throws BufferUnderflowException If not enough data is available
242: * @throws UnsupportedEncodingException if the given encoding is not supported
243: */
244: public String readStringByDelimiter(String delimiter,
245: String encoding) throws IOException,
246: BufferUnderflowException, UnsupportedEncodingException,
247: MaxReadSizeExceededException;
248:
249: /**
250: * read a string by using a delimiter
251: *
252: * @param delimiter the delimiter
253: * @param encoding the encoding to use
254: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
255: * @return the string
256: * @throws BufferUnderflowException If not enough data is available
257: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
258: * @throws IOException If some other I/O error occurs
259: * @throws UnsupportedEncodingException If the given encoding is not supported
260: */
261: public String readStringByDelimiter(String delimiter,
262: String encoding, int maxLength) throws IOException,
263: BufferUnderflowException, UnsupportedEncodingException,
264: MaxReadSizeExceededException;
265:
266: /**
267: * read a string by using a length definition
268: *
269: * @param length the amount of bytes to read.
270: * @param encoding the encoding to use
271: * @return the string
272: * @throws IOException If some other I/O error occurs
273: * @throws BufferUnderflowException If not enough data is available
274: * @throws UnsupportedEncodingException if the given encoding is not supported
275: * @throws IllegalArgumentException, if the length parameter is negative
276: */
277: public String readStringByLength(int length, String encoding)
278: throws IOException, BufferUnderflowException,
279: UnsupportedEncodingException;
280:
281: /**
282: * transfer the data of the file channel to this data sink
283: *
284: * @param source the source channel
285: * @return the number of transfered bytes
286: * @throws BufferOverflowException If the no enough space is available
287: * @throws IOException If some other I/O error occurs
288: */
289: public long transferFrom(FileChannel source) throws IOException,
290: BufferOverflowException;
291:
292: /**
293: * Returns the index of the first occurrence of the given string.
294: *
295: * @param str any string
296: * @return if the string argument occurs as a substring within this object, then
297: * the index of the first character of the first such substring is returned;
298: * if it does not occur as a substring, -1 is returned.
299: * @throws IOException If some other I/O error occurs
300: */
301: public int indexOf(String str) throws IOException;
302:
303: /**
304: * Returns the index of the first occurrence of the given string.
305: *
306: * @param str any string
307: * @param encoding the encoding to use
308: * @return if the string argument occurs as a substring within this object, then
309: * the index of the first character of the first such substring is returned;
310: * if it does not occur as a substring, -1 is returned.
311: * @throws IOException If some other I/O error occurs
312: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
313: */
314: public int indexOf(String str, String encoding) throws IOException;
315:
316: /**
317: * set the send delay time. WData to write will be buffered
318: * internally and be written to the underlying subsystem
319: * based on the given write rate.
320: * The write methods will <b>not</b> block for this time. <br>
321: *
322: * By default the write transfer rate is set with UNLIMITED <br><br>
323: *
324: * Reduced write transfer is only supported for FlushMode.ASYNC. see
325: * {@link INonBlockingConnection#setFlushmode(org.xsocket.connection.IConnection.FlushMode))}
326: *
327: * @param bytesPerSecond the transfer rate of the outgoing data
328: * @throws ClosedChannelException If the underlying socket is already closed
329: * @throws IOException If some other I/O error occurs
330: */
331: public void setWriteTransferRate(int bytesPerSecond)
332: throws ClosedChannelException, IOException;
333:
334: /**
335: * set the read rate. By default the read transfer rate is set with UNLIMITED <br><br>
336: *
337: * @param bytesPerSecond the transfer rate of the outgoing data
338: * @throws ClosedChannelException If the underlying socket is already closed
339: * @throws IOException If some other I/O error occurs
340: */
341: // public void setReadTransferRate(int bytesPerSecond) throws ClosedChannelException, IOException;
342:
343: /**
344: * get the number of available bytes to read
345: *
346: * @return the number of available bytes, possibly zero, or -1 if the channel has reached end-of-stream
347: */
348: public int available() throws IOException;
349:
350: /**
351: * get the version of read buffer. The version number increases, if
352: * the read buffer queue has been modified
353: *
354: * @return the version of the read buffer
355: * @throws IOException If some other I/O error occurs
356: */
357: public int getReadBufferVersion() throws IOException;
358:
359: /**
360: * return if the data source is open. Default is true
361: * @return true, if the data source is open
362: */
363: public boolean isOpen();
364:
365: /**
366: * return the worker pool which is used to process the call back methods
367: *
368: * @return the worker pool
369: */
370: public Executor getWorkerpool();
371:
372: /**
373: * Resets to the marked write position. If the connection has been marked,
374: * then attempt to reposition it at the mark.
375: *
376: * @return true, if reset was successful
377: */
378: public boolean resetToWriteMark();
379:
380: /**
381: * Resets to the marked read position. If the connection has been marked,
382: * then attempt to reposition it at the mark.
383: *
384: * @return true, if reset was successful
385: */
386: public boolean resetToReadMark();
387:
388: /**
389: * Marks the write position in the connection.
390: */
391: public void markWritePosition();
392:
393: /**
394: * Marks the read position in the connection. Subsequent calls to resetToReadMark() will attempt
395: * to reposition the connection to this point.
396: *
397: */
398: public void markReadPosition();
399:
400: /**
401: * remove the read mark
402: */
403: public void removeReadMark();
404:
405: /**
406: * remove the write mark
407: */
408: public void removeWriteMark();
409: }
|