KickJava   Java API By Example, From Geeks To Geeks.

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


1 // $Id: INonBlockingConnection.java 1543 2007-07-21 14:25:09Z 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.IOException JavaDoc;
25 import java.io.UnsupportedEncodingException JavaDoc;
26 import java.nio.BufferUnderflowException JavaDoc;
27 import java.nio.ByteBuffer JavaDoc;
28 import java.nio.channels.WritableByteChannel JavaDoc;
29
30 import org.xsocket.ClosedConnectionException;
31 import org.xsocket.MaxReadSizeExceededException;
32
33
34 /**
35  * A connection which uses the underlying channel in a non-blocking manner. <br><br>
36  *
37  * @author grro@xsocket.org
38  */

39 public interface INonBlockingConnection extends IConnection {
40
41     public static final int UNLIMITED = Integer.MAX_VALUE;
42     public static final FlushMode INITIAL_FLUSH_MODE = FlushMode.SYNC;
43     
44     
45     /**
46      * get the number of available bytes to read
47      *
48      * @return the umber of available bytes
49      */

50     public int getNumberOfAvailableBytes();
51
52     
53
54     /**
55      * Returns the index of the first occurrence of the given string.
56      *
57      * @param str any string
58      * @return if the string argument occurs as a substring within this object, then the
59      * index of the first character of the first such substring is returned;
60      * if it does not occur as a substring, -1 is returned.
61      * @deprecated uses getIndexOf instead
62      */

63     public int indexOf(String JavaDoc str);
64     
65     
66     /**
67      * Returns the index of the first occurrence of the given string.
68      *
69      * @param str any string
70      * @return if the string argument occurs as a substring within this object, then the
71      * index of the first character of the first such substring is returned;
72      * @throws ClosedConnectionException If the underlying socket is already closed
73      * @throws IOException If some other I/O error occurs
74      * @throws BufferUnderflowException if the given string has not been found
75      */

76     public int getIndexOf(String JavaDoc str) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
77
78     
79     /**
80      * Returns the index of the first occurrence of the given string.
81      *
82      * @param str any string
83      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
84      * @return if the string argument occurs as a substring within this object, then the
85      * index of the first character of the first such substring is returned;
86      * @throws ClosedConnectionException If the underlying socket is already closed
87      * @throws IOException If some other I/O error occurs
88      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasnít been found
89      * @throws BufferUnderflowException if the given string has not been found
90      */

91     public int getIndexOf(String JavaDoc str, int maxLength) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, MaxReadSizeExceededException;
92     
93
94     
95     
96     /**
97      * read all received bytes
98      *
99      * @return the received bytes
100      * @throws ClosedConnectionException If the underlying socket is already closed
101      * @throws IOException If some other I/O error occurs
102      */

103     public ByteBuffer JavaDoc[] readAvailable() throws IOException JavaDoc, ClosedConnectionException;
104
105
106     
107     /**
108      * read all received byte buffers. In the case the delimiter has been
109      * found, the behavior is equals to the readRecordByDelimiter method.
110      * In this case the method returns true. <br>
111      * If the delimiter hasn't been reached, behavior is equals to the readAvailable
112      * method. In this case the method returns false; <br>
113      * The default encoding will be used to decode the delimiter
114      *
115      *
116      * @param delimiter the delimiter to use
117      * @param outputChannel the output channel to write the available bytes
118      * @return true, if the delimiter has been found
119      * @throws ClosedConnectionException If the underlying socket is already closed
120      * @throws IOException If some other I/O error occurs
121      */

122     public boolean readAvailableByDelimiter(String JavaDoc delimiter, WritableByteChannel JavaDoc outputChannel) throws IOException JavaDoc, ClosedConnectionException;
123
124
125     /**
126      * read all received byte buffers. In the case the delimiter has been
127      * found, the behavior is equals to the readRecordByDelimiter method.
128      * In this case the method returns true. <br>
129      * If the delimiter hasn't been reached, behavior is equals to the readAvailable
130      * method. In this case the method returns false;
131      *
132      * @param delimiter the delimiter to use
133      * @param encoding the encoding of the delimiter
134      * @param outputChannel the output channel to write the available bytes
135      * @return true, if the delimiter has been found
136      * @throws ClosedConnectionException If the underlying socket is already closed
137      * @throws IOException If some other I/O error occurs
138      */

139     public boolean readAvailableByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, WritableByteChannel JavaDoc outputChannel) throws IOException JavaDoc, ClosedConnectionException;
140
141     
142     
143     /**
144      * read a ByteBuffer by using a delimiter
145      * To avoid memory leaks the {@link INonBlockingConnection#readByteBufferByDelimiter(String, int)} method is generally preferable
146      * <br>
147      * For performance reasons, the ByteBuffer readByteBuffer method is
148      * generally preferable to get bytes
149      *
150      * @param delimiter the delimiter
151      * @return the ByteBuffer
152      * @throws IOException If some other I/O error occurs
153      * @throws BufferUnderflowException if the delimiter has not been found
154      */

155     public ByteBuffer JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
156
157         
158     
159     /**
160      * read a ByteBuffer by using a delimiter
161      *
162      * For performance reasons, the ByteBuffer readByteBuffer method is
163      * generally preferable to get bytes
164      *
165      * @param delimiter the delimiter
166      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
167      * @return the ByteBuffer
168      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasnít been found * @throws ClosedConnectionException If the underlying socket is already closed
169      * @throws IOException If some other I/O error occurs
170      * @throws BufferUnderflowException if the delimiter has not been found
171      */

172     public ByteBuffer JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException, BufferUnderflowException JavaDoc;
173
174
175
176     
177     /**
178      * read a ByteBuffer by using a length defintion
179      *
180      * For performance reasons, the ByteBuffer readByteBuffer method is
181      * generally preferable to get bytes
182      *
183      * @param length the amount of bytes to read
184      * @return the ByteBuffer
185      * @throws ClosedConnectionException If the underlying socket is already closed
186      * @throws BufferUnderflowException if the buffer's limit has been reached
187      * @throws IOException If some other I/O error occurs
188      */

189     public ByteBuffer JavaDoc[] readByteBufferByLength(int length) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
190
191     
192     /**
193      * read a byte array by using a delimiter
194      * To avoid memory leaks the {@link INonBlockingConnection#readBytesByDelimiter(String, int)} method is generally preferable
195      * <br>
196      * For performance reasons, the ByteBuffer readByteBuffer method is
197      * generally preferable to get bytes
198      *
199      * @param delimiter the delimiter
200      * @return the read bytes
201      * @throws ClosedConnectionException If the underlying socket is already closed
202      * @throws BufferUnderflowException if the delimiter has not been found
203      * @throws IOException If some other I/O error occurs
204      */

205     public byte[] readBytesByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
206
207     
208
209     /**
210      * read a byte array by using a delimiter
211      *
212      * For performance reasons, the ByteBuffer readByteBuffer method is
213      * generally preferable to get bytes
214      *
215      * @param delimiter the delimiter
216      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
217      * @return the read bytes
218      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasnít been found * @throws ClosedConnectionException If the underlying socket is already closed
219      * @throws BufferUnderflowException if the delimiter has not been found
220      * @throws IOException If some other I/O error occurs
221      */

222     public byte[] readBytesByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException, BufferUnderflowException JavaDoc;
223     
224
225     
226     
227     /**
228      * read bytes by using a length defintion
229      *
230      * For performance reasons, the ByteBuffer readByteBuffer method is
231      * generally preferable to get bytes
232      *
233      * @param length the amount of bytes to read
234      * @return the read bytes
235      * @throws ClosedConnectionException If the underlying socket is already closed
236      * @throws BufferUnderflowException if the buffer's limit has been reached
237      * @throws IOException If some other I/O error occurs
238      */

239     public byte[] readBytesByLength(int length) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
240
241
242     
243     /**
244      * read a string by using a delimiter and the connection default encoding
245      * To avoid memory leaks the {@link INonBlockingConnection#readStringByDelimiter(String, int)} method is generally preferable
246      *
247      * @param delimiter the delimiter
248      * @return the string
249      * @throws ClosedConnectionException If the underlying socket is already closed
250      * @throws IOException If some other I/O error occurs
251      * @throws BufferUnderflowException if the delimiter has not been found
252      * @throws UnsupportedEncodingException if the default encoding is not supported
253      */

254     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc;
255
256     
257     
258     /**
259      * read a string by using a delimiter and the connection default encoding
260      *
261      * @param delimiter the delimiter
262      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
263      * @return the string
264      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasnít been found
265      * @throws ClosedConnectionException If the underlying socket is already closed
266      * @throws IOException If some other I/O error occurs
267      * @throws BufferUnderflowException if the delimiter has not been found
268      * @throws UnsupportedEncodingException if the default encoding is not supported
269      */

270     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc, MaxReadSizeExceededException;
271
272     
273     
274     /**
275      * read a string by using a length definition and the connection default encoding
276      *
277      * @param length the amount of bytes to read
278      * @return the string
279      * @throws ClosedConnectionException If the underlying socket is already closed
280      * @throws BufferUnderflowException if the buffer's limit has been reached
281      * @throws IOException If some other I/O error occurs
282      * @throws UnsupportedEncodingException if the given encoding is not supported
283      */

284     public String JavaDoc readStringByLength(int length) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc;
285
286     
287     /**
288      * read a string by using a delimiter
289      * To avoid memory leaks the {@link INonBlockingConnection#readStringByDelimiter(String, String, int)} method is generally preferable
290      *
291      * @param delimiter the delimiter
292      * @param encoding the encodin to use
293      * @return the string
294      * @throws IOException If some other I/O error occurs
295      * @throws BufferUnderflowException if the buffer's limit has been reached
296      * @throws UnsupportedEncodingException If the given encoding is not supported
297      */

298     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc;
299
300
301     
302     /**
303      * read a string by using a delimiter
304      *
305      * @param delimiter the delimiter
306      * @param encoding the encodin to use
307      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
308      * @return the string
309      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasnít been found * @throws ClosedConnectionException If the underlying socket is already closed
310      * @throws IOException If some other I/O error occurs
311      * @throws BufferUnderflowException if the buffer's limit has been reached
312      * @throws UnsupportedEncodingException If the given encoding is not supported
313      */

314     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc, MaxReadSizeExceededException;
315
316     
317     
318     
319     /**
320      * read a string by using a length definition
321      *
322      * @param length the amount of bytes to read
323      * @param encoding the encodin to use
324      * @return the string
325      * @throws ClosedConnectionException If the underlying socket is already closed
326      * @throws BufferUnderflowException if the buffer's limit has been reached
327      * @throws IOException If some other I/O error occurs
328      * @throws UnsupportedEncodingException if the given encoding is not supported
329      */

330     public String JavaDoc readStringByLength(int length, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc, UnsupportedEncodingException JavaDoc;
331
332     
333     /**
334      * read an int
335      *
336      * @return the int value
337      * @throws ClosedConnectionException If the underlying socket is already closed
338      * @throws BufferUnderflowException if the buffer's limit has been reached
339      * @throws IOException If some other I/O error occurs
340      */

341     public int readInt() throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
342
343     
344     /**
345      * read a long
346      *
347      * @return the long value
348      * @throws ClosedConnectionException If the underlying socket is already closed
349      * @throws BufferUnderflowException if the buffer's limit has been reached
350      * @throws IOException If some other I/O error occurs
351      */

352     public long readLong() throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
353
354     
355     /**
356      * read a double
357      *
358      * @return the double value
359      * @throws ClosedConnectionException If the underlying socket is already closed
360      * @throws BufferUnderflowException if the buffer's limit has been reached
361      * @throws IOException If some other I/O error occurs
362      */

363     public double readDouble() throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
364     
365     
366     /**
367      * read a byte
368      *
369      * @return the byte value
370      * @throws ClosedConnectionException If the underlying socket is already closed
371      * @throws BufferUnderflowException if the buffer's limit has been reached
372      * @throws IOException If some other I/O error occurs
373      */

374     public byte readByte() throws IOException JavaDoc, ClosedConnectionException, BufferUnderflowException JavaDoc;
375         
376     
377     /**
378      * set the send delay time. WData to write will be buffered
379      * internally and be written to the underlying subsystem
380      * based on the given write rate.
381      * The write methods will <b>not</b> block for this time. <br>
382      *
383      * By default the write transfer rate is set with UNLIMITED <br><br>
384      *
385      * Reduced write transfer is only supported for FlushMode.ASYNC. see
386      * {@link INonBlockingConnection#setFlushmode(org.xsocket.stream.IConnection.FlushMode)}
387      *
388      * @param bytesPerSecond the transfer rate of the outgoing data
389      * @throws ClosedConnectionException If the underlying socket is already closed
390      * @throws IOException If some other I/O error occurs
391      */

392     public void setWriteTransferRate(int bytesPerSecond) throws ClosedConnectionException, IOException JavaDoc;
393     
394     
395     /**
396      * flush the send buffer. The method call returns immediately.
397      * The outgoing data will be flushed into the underlying
398      * os-specific send buffer asynchronously in the background
399      *
400      * @throws IOException If some other I/O error occurs
401      * @throws ClosedConnectionException if the underlying channel is closed
402      */

403     public void flush() throws ClosedConnectionException, IOException JavaDoc;
404         
405     
406
407     /**
408      * sends a byte buffer to the remote endpoint. In case of <i>activated autoflush</i>
409      * (for default see {@link IConnection#INITIAL_AUTOFLUSH}) and <i>flushmode SYNC</i>
410      * (for default see {@link INonBlockingConnection#INITIAL_FLUSH_MODE} the behaviour is
411      * according to the {@link WritableByteChannel} specification. <br> In case of
412      * user managed flushing (autoflush is off) the passed over buffers will
413      * only be queued internally and written after flushing the connection.
414      *
415      * @see IConnection#setAutoflush(boolean)
416      * @see INonBlockingConnection#setFlushmode(org.xsocket.stream.IConnection.FlushMode)
417      *
418      * @param buffer the bytes to send
419      * @return the number of send bytes
420      * @throws IOException If some other I/O error occurs
421      * @throws ClosedConnectionException if the underlying channel is closed
422      */

423     public int write(ByteBuffer JavaDoc buffer) throws ClosedConnectionException, IOException JavaDoc;
424     
425
426     /**
427      * sends an array of byte buffer to the remote endpoint. In case of <i>activated autoflush</i>
428      * (for default see {@link IConnection#INITIAL_AUTOFLUSH}) and <i>flushmode SYNC</i>
429      * (for default see {@link INonBlockingConnection#INITIAL_FLUSH_MODE} the behaviour is
430      * according to the {@link WritableByteChannel} specification. <br> In case of
431      * user managed flushing (autoflush is off) the passed over buffers will
432      * only be queued internally and written after flushing the connection.
433      *
434      * @see IConnection#setAutoflush(boolean)
435      * @see INonBlockingConnection#setFlushmode(org.xsocket.stream.IConnection.FlushMode)
436      *
437      * @param buffers the bytes to send
438      * @return the number of send bytes
439      * @throws IOException If some other I/O error occurs
440      * @throws ClosedConnectionException if the underlying channel is closed
441      */

442     public long write(ByteBuffer JavaDoc[] buffers) throws ClosedConnectionException, IOException JavaDoc;
443  
444     
445     
446     /**
447      * set the flush mode <br><br> By setting the flushmode with ASYNC (default is SYNC)
448      * the data will be transferred to the underlying connection in a asynchronous way.
449      * In most cases there are high performance improvements. If the {@link IConnection#write(ByteBuffer)}
450      * or {@link IConnection#write(ByteBuffer[])} method will be used, the flushmode
451      * {@link FlushMode#ASYNC} could have side-effects. Because the buffer will be
452      * written asynchronous, it could occur, that the passed-over buffers are not already
453      * written by returning from the write call.
454      *
455      * @param flushMode {@link FlushMode#ASYNC} if flush should be performed asynchronous,
456      * {@link FlushMode#SYNC} if flush should be perform synchronous
457      */

458     public void setFlushmode(FlushMode flushMode);
459     
460     /**
461      * return the flushmode
462      * @return the flushmode
463      */

464     public FlushMode getFlushmode();
465     
466     
467     /**
468      * sets the value of a option
469      *
470      * @param name the name of the option
471      * @param value the value of the option
472      * @return the IConnection
473      * @throws IOException In an I/O error occurs
474      */

475     public INonBlockingConnection setOption(String JavaDoc name, Object JavaDoc value) throws IOException JavaDoc;
476
477 }
478
Popular Tags