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


1 // $Id: IBlockingConnection.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
23 package org.xsocket.stream;
24
25 import java.io.IOException ;
26 import java.io.UnsupportedEncodingException ;
27 import java.net.SocketTimeoutException ;
28 import java.nio.ByteBuffer ;
29
30 import org.xsocket.ClosedConnectionException;
31 import org.xsocket.MaxReadSizeExceededException;
32
33
34 /**
35  * A connection which uses the underlying channel in a blocking manner. Every I/O operation
36  * will block until it completes. <br><br>
37  *
38  * @author grro@xsocket.org
39  */
40 public interface IBlockingConnection extends IConnection {
41
42     public static final long INITIAL_RECEIVE_TIMEOUT = 1 * 60 * 1000;
43     
44     
45     /**
46      * set the timeout for calling read methods in millis
47      *
48      * @param timeout the timeout in millis
49      */
50     public void setReceiveTimeoutMillis(long timeout);
51     
52
53     /**
54      * receive a string. the method will block, until the delimiter has been read.
55      * For the encoding the default encoding of the connection will be used.
56      * To avoid memory leaks the {@link IBlockingConnection#readStringByDelimiter(String, int)} method is generally preferable
57      *
58      * @param delimiter the delimiter
59      * @return the string
60      *
61      * @throws ClosedConnectionException If the underlying socket is already closed
62      * @throws IOException If some other I/O error occurs
63      * @throws SocketTimeoutException If the receive timeout has been reached
64      * @throws UnsupportedEncodingException if the default encoding is not supported
65      */
66     public String readStringByDelimiter(String delimiter) throws IOException , ClosedConnectionException, UnsupportedEncodingException , SocketTimeoutException ;
67
68     
69
70     
71     /**
72      * receive a string. the method will block, until the delimiter has been read.
73      * For the encoding the default encoding of the connection will be used
74      *
75      * @param delimiter the delimiter
76      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
77      * @return the string
78      *
79      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
80      * @throws ClosedConnectionException If the underlying socket is already closed
81      * @throws IOException If some other I/O error occurs
82      * @throws SocketTimeoutException If the receive timeout has been reached
83      * @throws UnsupportedEncodingException if the default encoding is not supported
84      */
85     public String readStringByDelimiter(String delimiter, int maxLength) throws IOException , ClosedConnectionException, UnsupportedEncodingException , SocketTimeoutException , MaxReadSizeExceededException;
86
87
88     
89     /**
90      * receive a string. the method will block, until the delimiter has been read
91      * To avoid memory leaks the {@link IBlockingConnection#readStringByDelimiter(String, String)} method is generally preferable
92      *
93      * @param delimiter the delimiter
94      * @param encoding the encoding to use
95      * @return the string
96      *
97      * @throws SocketTimeoutException If the receive timeout has been reached
98      * @throws IOException If some other I/O error occurs
99      * @throws UnsupportedEncodingException If the given encoding is not supported
100      */
101     public String readStringByDelimiter(String delimiter, String encoding) throws IOException , ClosedConnectionException, UnsupportedEncodingException , SocketTimeoutException ;
102
103
104
105     
106     /**
107      * receive a string. the method will block, until the delimiter has been read
108      *
109      * @param delimiter the delimiter
110      * @param encoding the encoding to use
111      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
112      * @return the string
113      *
114      * @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
115      * @throws SocketTimeoutException If the receive timeout has been reached
116      * @throws IOException If some other I/O error occurs
117      * @throws UnsupportedEncodingException If the given encoding is not supported
118      */
119     public String readStringByDelimiter(String delimiter, String encoding, int maxLength) throws IOException , ClosedConnectionException, UnsupportedEncodingException , SocketTimeoutException , MaxReadSizeExceededException;
120
121     
122     
123     
124     /**
125      * receive a string. the method will block, until the required amount of bytes has been received
126      *
127      * @param length the number of bytes to read
128      *@return the received string
129      * @throws SocketTimeoutException If the receive timeout has been reached
130      * @throws ClosedConnectionException If the underlying socket is already closed
131      * @throws IOException If some other I/O error occurs
132      */
133     public String readStringByLength(int length) throws IOException , ClosedConnectionException, SocketTimeoutException ;
134
135     
136     /**
137      * receive a string. the method will block, until the required amount of bytes has been received
138      *
139      * For performance reasons, the ByteBuffer receiveRecord method is generally preferable to get bytes
140      *
141      * @param length the number of bytes to read
142      * @param encoding the encoding
143      * @return the received string
144      * @throws SocketTimeoutException If the receive timeout has been reached
145      * @throws ClosedConnectionException If the underlying socket is already closed
146      * @throws IOException If some other I/O error occurs
147      */
148     public String readStringByLength(int length, String encoding) throws IOException , ClosedConnectionException, SocketTimeoutException ;
149
150
151
152     /**
153      * receive a ByteBuffer. the method will block, until the delimiter has been read.
154      * To avoid memory leaks the {@link IBlockingConnection#readByteBufferByDelimiter(String, int)} method is generally preferable
155      * <br>
156      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
157      *
158      * @param delimiter the delimiter
159      * @return the ByteBuffer
160      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
161      * @throws SocketTimeoutException If the receive timeout has been reached
162      * @throws ClosedConnectionException If the underlying socket is already closed
163      * @throws IOException If some other I/O error occurs
164      */
165     public ByteBuffer [] readByteBufferByDelimiter(String delimiter) throws IOException , ClosedConnectionException, SocketTimeoutException ;
166
167     
168
169
170     /**
171      * receive a ByteBuffer. the method will block, until the delimiter has been read.
172      *
173      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
174      *
175      * @param delimiter the delimiter
176      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
177      * @return the ByteBuffer
178      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
179      * @throws SocketTimeoutException If the receive timeout has been reached
180      * @throws ClosedConnectionException If the underlying socket is already closed
181      * @throws IOException If some other I/O error occurs
182      */
183     public ByteBuffer [] readByteBufferByDelimiter(String delimiter, int maxLength) throws IOException , ClosedConnectionException, SocketTimeoutException , MaxReadSizeExceededException;
184
185     
186     
187     /**
188      * receive a ByteBuffer. the method will block, until the required amount of bytes has been received
189      *
190      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
191      *
192      * @param length the number of bytes to read
193      * @return the received ByteBuffer
194      * @throws SocketTimeoutException If the receive timeout has been reached
195      * @throws ClosedConnectionException If the underlying socket is already closed
196      * @throws IOException If some other I/O error occurs
197      */
198     public ByteBuffer [] readByteBufferByLength(int length) throws IOException , ClosedConnectionException, SocketTimeoutException ;
199
200
201     
202     /**
203      * receive a byte array. the method will block, until the delimiter has been read.
204      * To avoid memory leaks the {@link IBlockingConnection#readBytesByDelimiter(String, int)} method is generally preferable
205      * <br>
206      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
207      *
208      * @param delimiter the delimiter
209      * @return the read bytes
210      * @throws SocketTimeoutException If the receive timeout has been reached
211      * @throws ClosedConnectionException If the underlying socket is already closed
212      * @throws IOException If some other I/O error occurs
213      */
214     public byte[] readBytesByDelimiter(String delimiter) throws IOException , ClosedConnectionException, SocketTimeoutException ;
215
216     
217     
218     /**
219      * receive a byte array. the method will block, until the delimiter has been read.
220      *
221      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
222      *
223      * @param delimiter the delimiter
224      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
225      * @return the read bytes
226      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
227      * @throws SocketTimeoutException If the receive timeout has been reached
228      * @throws ClosedConnectionException If the underlying socket is already closed
229      * @throws IOException If some other I/O error occurs
230      */
231     public byte[] readBytesByDelimiter(String delimiter, int maxLength) throws IOException , ClosedConnectionException, SocketTimeoutException , MaxReadSizeExceededException;
232     
233     
234     
235     
236     /**
237      * Returns the index of the first occurrence of the given string.
238      *
239      * @param str any string
240      * @return if the string argument occurs as a substring within this object, then the
241      * index of the first character of the first such substring is returned;
242      * @throws ClosedConnectionException If the underlying socket is already closed
243      * @throws IOException If some other I/O error occurs
244      * @throws SocketTimeoutException If the receive timeout has been reached
245      */
246     public int getIndexOf(String str) throws IOException , ClosedConnectionException, SocketTimeoutException ;
247
248     
249     /**
250      * Returns the index of the first occurrence of the given string.
251      *
252      * @param str any string
253      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
254      * @return if the string argument occurs as a substring within this object, then the
255      * index of the first character of the first such substring is returned;
256      * @throws ClosedConnectionException If the underlying socket is already closed
257      * @throws IOException If some other I/O error occurs
258      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
259      * @throws SocketTimeoutException If the receive timeout has been reached
260      */
261     public int getIndexOf(String str, int maxLength) throws IOException , ClosedConnectionException, MaxReadSizeExceededException, SocketTimeoutException ;
262     
263
264     
265     
266     /**
267      * receive a byte array. the method will block, until the required amount of bytes has been received
268      *
269      * For performance reasons, the ByteBuffer receiveByteBuffer method is generally preferable to get bytes
270      *
271      * @param length the number of bytes to read
272      * @return the received byte array
273      * @throws SocketTimeoutException If the receive timeout has been reached
274      * @throws ClosedConnectionException If the underlying socket is already closed
275      * @throws IOException If some other I/O error occurs
276      */
277     public byte[] readBytesByLength(int length) throws IOException , ClosedConnectionException, SocketTimeoutException ;
278
279
280     
281     /**
282      * receive an int. the method will block, until data is available
283      *
284      * @return the received int
285      * @throws SocketTimeoutException If the receive timeout has been reached
286      * @throws ClosedConnectionException If the underlying socket is already closed
287      * @throws IOException If some other I/O error occurs
288      */
289     public int readInt() throws IOException , ClosedConnectionException, SocketTimeoutException ;
290
291     
292     /**
293      * receive a long. the method will block, until data is available
294      *
295      * @return the received long
296      * @throws SocketTimeoutException If the receive timeout has been reached
297      * @throws ClosedConnectionException If the underlying socket is already closed
298      * @throws IOException If some other I/O error occurs
299      */
300     public long readLong() throws IOException , ClosedConnectionException, SocketTimeoutException ;
301
302     
303     /**
304      * receive a double. the method will block, until data is available
305      *
306      * @return the received double
307      * @throws SocketTimeoutException If the receive timeout has been reached
308      * @throws ClosedConnectionException If the underlying socket is already closed
309      * @throws IOException If some other I/O error occurs
310      */
311     public double readDouble() throws IOException , ClosedConnectionException, SocketTimeoutException ;
312     
313     
314
315     /**
316      * receive a byte. the method will block, until data is available
317      *
318      * @return the received byte
319      * @throws SocketTimeoutException If the receive timeout has been reached
320      * @throws ClosedConnectionException If the underlying socket is already closed
321      * @throws IOException If some other I/O error occurs
322      */
323     public byte readByte() throws IOException , ClosedConnectionException, SocketTimeoutException ;
324     
325     
326     /**
327      * sends a message to the remote endpoint
328      *
329      * @param message the message to send
330      * @param encoding the encoding which should be used th encode the chars into byte (e.g. 'US-ASCII' or 'UTF-8')
331      * @return the number of send bytes
332      * @throws IOException If some other I/O error occurs
333      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
334      * @throws ClosedConnectionException if the underlying channel is closed
335      */
336     public int write(String message, String encoding) throws ClosedConnectionException, IOException , SocketTimeoutException ;
337
338     
339     /**
340      * sends a message to the remote endpoint by using the connection default encoding
341      *
342      * @param message the message to send
343      * @return the number of send bytes
344      * @throws IOException If some other I/O error occurs
345      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
346      * @throws ClosedConnectionException if the underlying channel is closed
347      */
348     public int write(String message) throws ClosedConnectionException, IOException , SocketTimeoutException ;
349
350     
351     /**
352      * sends a byte to the remote endpoint
353      *
354      * @param b the byte to send
355      * @return the number of send bytes
356      * @throws IOException If some other I/O error occurs
357      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
358      * @throws ClosedConnectionException if the underlying channel is closed
359      */
360     public int write(byte b) throws ClosedConnectionException, IOException , SocketTimeoutException ;
361
362     
363     /**
364      * sends bytes to the remote endpoint
365      *
366      * @param bytes the bytes to send
367      * @return the number of send bytes
368      * @throws IOException If some other I/O error occurs
369      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
370      * @throws ClosedConnectionException if the underlying channel is closed
371      */
372     public int write(byte... bytes) throws ClosedConnectionException, IOException , SocketTimeoutException ;
373     
374
375     /**
376      * sends bytes to the remote endpoint
377      *
378      * @param bytes the bytes to send
379      * @param offset The offset of the subarray to be used; must be non-negative and no larger than array.length. The new buffer's position will be set to this value.
380      * @param length The length of the subarray to be used; must be non-negative and no larger than array.length - offset. The new buffer's limit will be set to offset + length.
381      * @return the number of send bytes
382      * @throws IOException If some other I/O error occurs
383      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
384      * @throws ClosedConnectionException if the underlying channel is closed
385      */
386     public int write(byte[] bytes, int offset, int length) throws ClosedConnectionException, IOException , SocketTimeoutException ;
387
388
389     /**
390      * sends a byte buffer to the remote endpoint
391      *
392      * @param buffer the bytes to send
393      * @return the number of send bytes
394      * @throws IOException If some other I/O error occurs
395      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
396      * @throws ClosedConnectionException if the underlying channel is closed
397      */
398     public int write(ByteBuffer buffer) throws ClosedConnectionException, IOException , SocketTimeoutException ;
399     
400     
401     /**
402      * sends an array of byte buffer to the remote endpoint
403      *
404      * @param buffers the bytes to send
405      * @return the number of send bytes
406      * @throws IOException If some other I/O error occurs
407      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
408      * @throws ClosedConnectionException if the underlying channel is closed
409      */
410     public long write(ByteBuffer [] buffers) throws ClosedConnectionException, IOException , SocketTimeoutException ;
411
412
413     /**
414      * sends an int to the remote endpoint
415      *
416      * @param i the int value to send
417      * @return the number of send bytes
418      * @throws IOException If some other I/O error occurs
419      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
420      * @throws ClosedConnectionException if the underlying channel is closed
421      */
422     public int write(int i) throws ClosedConnectionException, IOException , SocketTimeoutException ;
423
424
425     /**
426      * sends a long to the remote endpoint
427      *
428      * @param l the int value to send
429      * @return the number of send bytes
430      * @throws IOException If some other I/O error occurs
431      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
432      * @throws ClosedConnectionException if the underlying channel is closed
433      */
434     public int write(long l) throws ClosedConnectionException, IOException , SocketTimeoutException ;
435
436     
437     /**
438      * sends a double to the remote endpoint
439      *
440      * @param d the int value to send
441      * @return the number of send bytes
442      * @throws IOException If some other I/O error occurs
443      * @throws SocketTimeoutException If the receive timeout has been reached (will only been thrown if autoflush = true)
444      * @throws ClosedConnectionException if the underlying channel is closed
445      */
446     public int write(double d) throws ClosedConnectionException, IOException , SocketTimeoutException ;
447
448
449     
450     /**
451      * flush the send buffer. The method call will block until
452      * the outgoing data has been flushed into the underlying
453      * os-specific send buffer.
454      *
455      * @throws IOException If some other I/O error occurs
456      * @throws SocketTimeoutException If the timeout has been reached
457      * @throws ClosedConnectionException if the underlying channel is closed
458      */
459     public void flush() throws ClosedConnectionException, IOException , SocketTimeoutException ;
460     
461     
462     
463
464     /**
465      * sets the value of a option
466      *
467      * @param name the name of the option
468      * @param value the value of the option
469      * @return the IConnection
470      * @throws IOException In an I/O error occurs
471      */
472     public IBlockingConnection setOption(String name, Object value) throws IOException ;
473 }
474

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags