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 ;
25 import java.io.UnsupportedEncodingException ;
26 import java.nio.BufferUnderflowException ;
27 import java.nio.ByteBuffer ;
28 import java.nio.channels.WritableByteChannel ;
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 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 str) throws IOException , ClosedConnectionException, BufferUnderflowException ;
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 str, int maxLength) throws IOException , ClosedConnectionException, BufferUnderflowException , 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 [] readAvailable() throws IOException , 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 delimiter, WritableByteChannel outputChannel) throws IOException , 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 delimiter, String encoding, WritableByteChannel outputChannel) throws IOException , 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 [] readByteBufferByDelimiter(String delimiter) throws IOException , ClosedConnectionException, BufferUnderflowException ;
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 [] readByteBufferByDelimiter(String delimiter, int maxLength) throws IOException , ClosedConnectionException, MaxReadSizeExceededException, BufferUnderflowException ;
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 [] readByteBufferByLength(int length) throws IOException , ClosedConnectionException, BufferUnderflowException ;
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 delimiter) throws IOException , ClosedConnectionException, BufferUnderflowException ;
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 delimiter, int maxLength) throws IOException , ClosedConnectionException, MaxReadSizeExceededException, BufferUnderflowException ;
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 , ClosedConnectionException, BufferUnderflowException ;
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 readStringByDelimiter(String delimiter) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException ;
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 readStringByDelimiter(String delimiter, int maxLength) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException , 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 readStringByLength(int length) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException ;
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 readStringByDelimiter(String delimiter, String encoding) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException ;
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 readStringByDelimiter(String delimiter, String encoding, int maxLength) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException , 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 readStringByLength(int length, String encoding) throws IOException , ClosedConnectionException, BufferUnderflowException , UnsupportedEncodingException ;
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 , ClosedConnectionException, BufferUnderflowException ;
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 , ClosedConnectionException, BufferUnderflowException ;
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 , ClosedConnectionException, BufferUnderflowException ;
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 , ClosedConnectionException, BufferUnderflowException ;
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 ;
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 ;
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 buffer) throws ClosedConnectionException, IOException ;
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 [] buffers) throws ClosedConnectionException, IOException ;
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 name, Object value) throws IOException ;
476
477 }
478

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags