KickJava   Java API By Example, From Geeks To Geeks.

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 JavaDoc;
26 import java.io.UnsupportedEncodingException JavaDoc;
27 import java.net.SocketTimeoutException JavaDoc;
28 import java.nio.ByteBuffer 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 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 JavaDoc readStringByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc readStringByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, SocketTimeoutException JavaDoc, 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 JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, SocketTimeoutException JavaDoc, 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 JavaDoc readStringByLength(int length) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc readStringByLength(int length, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc, 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 JavaDoc[] readByteBufferByLength(int length) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc, 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 JavaDoc str) throws IOException JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc str, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException, SocketTimeoutException JavaDoc;
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 JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc, ClosedConnectionException, SocketTimeoutException JavaDoc;
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 JavaDoc message, String JavaDoc encoding) throws ClosedConnectionException, IOException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc message) throws ClosedConnectionException, IOException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc buffer) throws ClosedConnectionException, IOException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc[] buffers) throws ClosedConnectionException, IOException JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc, SocketTimeoutException JavaDoc;
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 JavaDoc name, Object JavaDoc value) throws IOException JavaDoc;
473 }
474
Popular Tags