KickJava   Java API By Example, From Geeks To Geeks.

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


1 // $Id: IConnection.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.Closeable JavaDoc;
26 import java.io.Flushable JavaDoc;
27 import java.io.IOException JavaDoc;
28 import java.io.UnsupportedEncodingException JavaDoc;
29 import java.net.InetAddress JavaDoc;
30 import java.nio.ByteBuffer JavaDoc;
31 import java.nio.channels.GatheringByteChannel JavaDoc;
32 import java.nio.channels.ReadableByteChannel JavaDoc;
33 import java.nio.channels.WritableByteChannel JavaDoc;
34 import java.util.Map JavaDoc;
35
36 import org.xsocket.ClosedConnectionException;
37 import org.xsocket.IDataSink;
38 import org.xsocket.IDataSource;
39 import org.xsocket.MaxReadSizeExceededException;
40
41
42
43 /**
44  * A connection (session) between two endpoints. It encapsulates the underlying socket channel. <br><br>
45  *
46  * @author grro@xsocket.org
47  */

48 public interface IConnection extends IDataSource, IDataSink, GatheringByteChannel JavaDoc, ReadableByteChannel JavaDoc, WritableByteChannel JavaDoc, Flushable JavaDoc, Closeable JavaDoc {
49     
50     public static final String JavaDoc INITIAL_DEFAULT_ENCODING = "UTF-8";
51     public static final boolean INITIAL_AUTOFLUSH = true;
52     
53     public static final String JavaDoc SO_SNDBUF = "SOL_SOCKET.SO_SNDBUF";
54     public static final String JavaDoc SO_RCVBUF = "SOL_SOCKET.SO_RCVBUF";
55     public static final String JavaDoc SO_REUSEADDR = "SOL_SOCKET.SO_REUSEADDR";
56     public static final String JavaDoc SO_KEEPALIVE = "SOL_SOCKET.SO_KEEPALIVE";
57     public static final String JavaDoc SO_LINGER = "SOL_SOCKET.SO_LINGER";
58     public static final String JavaDoc TCP_NODELAY = "IPPROTO_TCP.TCP_NODELAY";
59     
60     
61     public enum FlushMode { SYNC, ASYNC };
62
63
64     /**
65      * returns the id
66      *
67      * @return id
68      */

69     public String JavaDoc getId();
70         
71     
72     /**
73      * returns, if the connection is open. <br><br>
74      *
75      * Please note, that a connection could be closed, but reading of already
76      * received (and internally buffered) data wouldn't fail. See also
77      * {@link IDataHandler#onData(INonBlockingConnection)}
78      *
79      *
80      * @return true if the connection is open
81      */

82     public boolean isOpen();
83     
84     
85     /**
86      * flush the send buffer.
87      *
88      * @throws IOException If some other I/O error occurs
89      * @throws ClosedConnectionException if the underlying channel is closed
90      */

91     public void flush() throws ClosedConnectionException, IOException JavaDoc;
92     
93
94     
95     /**
96      * returns the local port
97      *
98      * @return the local port
99      */

100     public int getLocalPort();
101     
102     
103
104     /**
105      * returns the local address
106      *
107      * @return the local IP address or InetAddress.anyLocalAddress() if the socket is not bound yet.
108      */

109     public InetAddress JavaDoc getLocalAddress();
110     
111
112     
113
114     /**
115      * returns the remote address
116      *
117      * @return the remote address
118      */

119     public InetAddress JavaDoc getRemoteAddress();
120     
121
122     /**
123      * returns the port of the remote endpoint
124      *
125      * @return the remote port
126      */

127     public int getRemotePort();
128     
129     
130     /**
131      * sets the default encoding for this connection (used by string related methods like readString...)
132      *
133      * @param encoding the default encoding
134      */

135     public void setDefaultEncoding(String JavaDoc encoding);
136     
137     
138     /**
139      * suspend reading data from the underlying subsystem
140      *
141      * @throws IOException If some other I/O error occurs
142      */

143     public void suspendRead() throws IOException JavaDoc;
144     
145
146     /**
147      * resume reading data from the underlying subsystem
148      *
149      * @throws IOException If some other I/O error occurs
150      */

151     public void resumeRead() throws IOException JavaDoc;
152     
153     
154     /**
155      * gets the default encoding for this connection (used by string related methods like readString...)
156      *
157      * @return the default encoding
158      */

159     public String JavaDoc getDefaultEncoding();
160     
161
162
163     /**
164      * set autoflush. If autoflush is activated, each write call
165      * will cause a flush. <br><br>
166      *
167      * By default the autoflush is deactivated
168      *
169      * @param autoflush true if autoflush should be activated
170      */

171     public void setAutoflush(boolean autoflush);
172         
173
174     
175     /**
176      * get autoflush
177      * @return true, if autoflush is activated
178      */

179     public boolean getAutoflush();
180     
181     
182
183     
184     /**
185      * returns the idle timeout in sec.
186      *
187      * @return idle timeout in sec
188      */

189     public int getIdleTimeoutSec();
190     
191     
192
193     
194     
195     
196     /**
197      * sets the idle timeout in sec
198      *
199      * @param timeoutInSec idle timeout in sec
200      */

201     public void setIdleTimeoutSec(int timeoutInSec);
202     
203     
204     
205     /**
206      * gets the connection timeout
207      *
208      * @return connection timeout
209      */

210     public int getConnectionTimeoutSec();
211     
212     
213     /**
214      * sets the max time for a connections. By
215      * exceeding this time the connection will be
216      * terminated
217      *
218      * @param timeoutSec the connection timeout in sec
219      */

220     public void setConnectionTimeoutSec(int timeoutSec);
221     
222
223
224     /**
225      * returns the size of the data which have already been written, but not
226      * yet transferred to the underlying socket.
227      *
228      * @return the size of the pending data to write
229      */

230     public int getPendingWriteDataSize();
231     
232     
233     
234     /**
235      * ad hoc activation of a secured mode (SSL). By perfoming of this
236      * method all remaining data to send will be flushed.
237      * After this all data will be sent and received in the secured mode
238      *
239      * @throws IOException If some other I/O error occurs
240      */

241     public void activateSecuredMode() throws IOException JavaDoc;
242     
243     
244     /**
245      * sends a message to the remote endpoint
246      *
247      * @param message the message to send
248      * @param encoding the encoding which should be used th encode the chars into byte (e.g. 'US-ASCII' or 'UTF-8')
249      * @return the number of send bytes
250      * @throws IOException If some other I/O error occurs
251      * @throws ClosedConnectionException if the underlying channel is closed
252      */

253     public int write(String JavaDoc message, String JavaDoc encoding) throws ClosedConnectionException, IOException JavaDoc;
254
255     
256     /**
257      * sends a message to the remote endpoint by using the connection default encoding
258      *
259      * @param message the message to send
260      * @return the number of send bytes
261      * @throws IOException If some other I/O error occurs
262      * @throws ClosedConnectionException if the underlying channel is closed
263      */

264     public int write(String JavaDoc message) throws ClosedConnectionException, IOException JavaDoc;
265
266     
267     /**
268      * sends a byte to the remote endpoint
269      *
270      * @param b the byte to send
271      * @return the number of send bytes
272      * @throws IOException If some other I/O error occurs
273      * @throws ClosedConnectionException if the underlying channel is closed
274      */

275     public int write(byte b) throws ClosedConnectionException, IOException JavaDoc;
276
277     
278     /**
279      * sends bytes to the remote endpoint
280      *
281      * @param bytes the bytes to send
282      * @return the number of send bytes
283      * @throws IOException If some other I/O error occurs
284      * @throws ClosedConnectionException if the underlying channel is closed
285      */

286     public int write(byte... bytes) throws ClosedConnectionException, IOException JavaDoc;
287     
288
289     /**
290      * sends bytes to the remote endpoint
291      *
292      * @param bytes the bytes to send
293      * @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.
294      * @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.
295      * @return the number of send bytes
296      * @throws IOException If some other I/O error occurs
297      * @throws ClosedConnectionException if the underlying channel is closed
298      */

299     public int write(byte[] bytes, int offset, int length) throws ClosedConnectionException, IOException JavaDoc;
300
301
302     /**
303      * sends a byte buffer to the remote endpoint. In case of activated autoflush
304      * (for default see {@link IConnection#INITIAL_AUTOFLUSH}) the behaviour is
305      * according to the {@link WritableByteChannel} specification. In case of
306      * user managed flushing (autoflush is off) the passed over buffers will
307      * only be queued internally and written after flushing the connection.
308      *
309      * @param buffer the bytes to send
310      * @return the number of send bytes
311      * @throws IOException If some other I/O error occurs
312      * @throws ClosedConnectionException if the underlying channel is closed
313      */

314     public int write(ByteBuffer JavaDoc buffer) throws ClosedConnectionException, IOException JavaDoc;
315     
316     
317     /**
318      * sends an array of byte buffer to the remote endpoint. In case of activated autoflush
319      * (for default see {@link IConnection#INITIAL_AUTOFLUSH}) the behaviour is
320      * according to the {@link WritableByteChannel} specification. In case of
321      * user managed flushing (autoflush is off) the passed over buffers will
322      * only be queued internally and written after flushing the connection.
323      *
324      * @param buffers the bytes to send
325      * @return the number of send bytes
326      * @throws IOException If some other I/O error occurs
327      * @throws ClosedConnectionException if the underlying channel is closed
328      */

329     public long write(ByteBuffer JavaDoc[] buffers) throws ClosedConnectionException, IOException JavaDoc;
330
331
332     /**
333      * sends an int to the remote endpoint
334      *
335      * @param i the int value to send
336      * @return the number of send bytes
337      * @throws IOException If some other I/O error occurs
338      * @throws ClosedConnectionException if the underlying channel is closed
339      */

340     public int write(int i) throws ClosedConnectionException, IOException JavaDoc;
341
342
343     /**
344      * sends a long to the remote endpoint
345      *
346      * @param l the int value to send
347      * @return the number of send bytes
348      * @throws IOException If some other I/O error occurs
349      * @throws ClosedConnectionException if the underlying channel is closed
350      */

351     public int write(long l) throws ClosedConnectionException, IOException JavaDoc;
352
353     
354     /**
355      * sends a double to the remote endpoint
356      *
357      * @param d the int value to send
358      * @return the number of send bytes
359      * @throws IOException If some other I/O error occurs
360      * @throws ClosedConnectionException if the underlying channel is closed
361      */

362     public int write(double d) throws ClosedConnectionException, IOException JavaDoc;
363
364     
365     /**
366      * read a byte
367      *
368      * @return the byte value
369      * @throws ClosedConnectionException If the underlying socket is already closed
370      * @throws IOException If some other I/O error occurs
371      */

372     public byte readByte() throws IOException JavaDoc, ClosedConnectionException;
373     
374     
375     /**
376      * read an int
377      *
378      * @return the int value
379      * @throws ClosedConnectionException If the underlying socket is already closed
380      * @throws IOException If some other I/O error occurs
381      */

382     public int readInt() throws IOException JavaDoc, ClosedConnectionException;
383
384     
385     /**
386      * read a long
387      *
388      * @return the long value
389      * @throws ClosedConnectionException If the underlying socket is already closed
390      * @throws IOException If some other I/O error occurs
391      */

392     public long readLong() throws IOException JavaDoc, ClosedConnectionException;
393
394     
395     /**
396      * read a double
397      *
398      * @return the double value
399      * @throws ClosedConnectionException If the underlying socket is already closed
400      * @throws IOException If some other I/O error occurs
401      */

402     public double readDouble() throws IOException JavaDoc, ClosedConnectionException;
403     
404     
405     /**
406      * read a ByteBuffer by using a delimiter. The default encoing will be used to decode the delimiter
407      * To avoid memory leaks the {@link IConnection#readByteBufferByDelimiter(String, int)} method is generally preferable
408      * <br>
409      * For performance reasons, the ByteBuffer readByteBuffer method is
410      * generally preferable to get bytes
411      *
412      * @param delimiter the delimiter
413      * @return the ByteBuffer
414      * @throws ClosedConnectionException If the underlying socket is already closed
415      * @throws IOException If some other I/O error occurs
416      */

417     public ByteBuffer JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException;
418     
419     
420     
421     /**
422      * read a ByteBuffer by using a delimiter. The default encoing will be used to decode the delimiter
423      *
424      * For performance reasons, the ByteBuffer readByteBuffer method is
425      * generally preferable to get bytes
426      *
427      * @param delimiter the delimiter
428      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
429      * @return the ByteBuffer
430      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
431      * @throws ClosedConnectionException If the underlying socket is already closed
432      * @throws IOException If some other I/O error occurs
433      */

434     public ByteBuffer JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
435
436
437
438     /**
439      * read a ByteBuffer by using a delimiter
440      *
441      * For performance reasons, the ByteBuffer readByteBuffer method is
442      * generally preferable to get bytes
443      *
444      * @param delimiter the delimiter
445      * @param encoding the encoding of the delimiter
446      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
447      * @return the ByteBuffer
448      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
449      * @throws ClosedConnectionException If the underlying socket is already closed
450      * @throws IOException If some other I/O error occurs
451      */

452     public ByteBuffer JavaDoc[] readByteBufferByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
453
454     
455     /**
456      * read a ByteBuffer by using a length defintion
457      *
458      * For performance reasons, the ByteBuffer readByteBuffer method is
459      * generally preferable to get bytes
460      *
461      * @param length the amount of bytes to read
462      * @return the ByteBuffer
463      * @throws ClosedConnectionException If the underlying socket is already closed
464      * @throws IOException If some other I/O error occurs
465      */

466     public ByteBuffer JavaDoc[] readByteBufferByLength(int length) throws IOException JavaDoc, ClosedConnectionException;
467
468
469     /**
470      * read a byte array by using a delimiter. readByteBufferByDelimiter(String, int)
471      * To avoid memory leaks the {@link IConnection#readBytesByDelimiter(String, int)} method is generally preferable
472      * <br>
473      * For performance reasons, the ByteBuffer readByteBuffer method is
474      * generally preferable to get bytes
475      *
476      * @param delimiter the delimiter
477      * @return the read bytes
478      * @throws ClosedConnectionException If the underlying socket is already closed
479      * @throws IOException If some other I/O error occurs
480      */

481     public byte[] readBytesByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException;
482
483
484     
485     /**
486      * read a byte array by using a delimiter. readByteBufferByDelimiter(String, int)
487      *
488      * For performance reasons, the ByteBuffer readByteBuffer method is
489      * generally preferable to get bytes
490      *
491      * @param delimiter the delimiter
492      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
493      * @return the read bytes
494      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
495      * @throws ClosedConnectionException If the underlying socket is already closed
496      * @throws IOException If some other I/O error occurs
497      */

498     public byte[] readBytesByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
499     
500     
501     
502     /**
503      * read a byte array by using a delimiter
504      *
505      * For performance reasons, the ByteBuffer readByteBuffer method is
506      * generally preferable to get bytes
507      *
508      * @param delimiter the delimiter
509      * @param encoding the encoding of the delimiter
510      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
511      * @return the read bytes
512      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
513      * @throws ClosedConnectionException If the underlying socket is already closed
514      * @throws IOException If some other I/O error occurs
515      */

516     public byte[] readBytesByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
517     
518
519     /**
520      * read bytes by using a length defintion
521      *
522      * For performance reasons, the ByteBuffer readByteBuffer method is
523      * generally preferable to get bytes
524      *
525      * @param length the amount of bytes to read
526      * @return the read bytes
527      * @throws ClosedConnectionException If the underlying socket is already closed
528      * @throws IOException If some other I/O error occurs
529      */

530     public byte[] readBytesByLength(int length) throws IOException JavaDoc, ClosedConnectionException;
531
532     
533     
534     /**
535      * read a string by using a delimiter and the connection default encoding
536      * To avoid memory leaks the {@link IConnection#readStringByDelimiter(String, int)} method is generally preferable
537      *
538      * @param delimiter the delimiter
539      * @return the string
540      *
541      * @throws ClosedConnectionException If the underlying socket is already closed
542      * @throws IOException If some other I/O error occurs
543      * @throws UnsupportedEncodingException if the default encoding is not supported
544      */

545     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc;
546
547
548
549     
550     /**
551      * read a string by using a delimiter and the connection default encoding
552      *
553      * @param delimiter the delimiter
554      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
555      * @return the string
556      *
557      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
558      * @throws ClosedConnectionException If the underlying socket is already closed
559      * @throws IOException If some other I/O error occurs
560      * @throws UnsupportedEncodingException if the default encoding is not supported
561      */

562     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, int maxLength) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, MaxReadSizeExceededException;
563
564     
565     
566     /**
567      * read a string by using a length definition and the connection default encoding
568      *
569      * @param length the amount of bytes to read
570      * @return the string
571      * @throws ClosedConnectionException If the underlying socket is already closed
572      * @throws IOException If some other I/O error occurs
573      * @throws UnsupportedEncodingException if the given encoding is not supported
574      */

575     public String JavaDoc readStringByLength(int length) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc;
576
577
578     /**
579      * read a string by using a delimiter
580      * To avoid memory leaks the {@link IConnection#readStringByDelimiter(String, String, int)} method is generally preferable
581      *
582      * @param delimiter the delimiter
583      * @param encoding the encodin to use
584      * @return the string
585      *
586      * @throws ClosedConnectionException If the underlying socket is already closed
587      * @throws IOException If some other I/O error occurs
588      * @throws UnsupportedEncodingException If the given encoding is not supported
589      */

590     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc;
591
592
593     /**
594      * read a string by using a delimiter
595      *
596      * @param delimiter the delimiter
597      * @param encoding the encodin to use
598      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
599      * @return the string
600      *
601      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
602      * @throws ClosedConnectionException If the underlying socket is already closed
603      * @throws IOException If some other I/O error occurs
604      * @throws UnsupportedEncodingException If the given encoding is not supported
605      */

606     public String JavaDoc readStringByDelimiter(String JavaDoc delimiter, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc, MaxReadSizeExceededException;
607
608     
609     /**
610      * read a string by using a length definition
611      *
612      * @param length the amount of bytes to read
613      * @param encoding the encodin to use
614      * @return the string
615      * @throws ClosedConnectionException If the underlying socket is already closed
616      * @throws IOException If some other I/O error occurs
617      * @throws UnsupportedEncodingException if the given encoding is not supported
618      */

619     public String JavaDoc readStringByLength(int length, String JavaDoc encoding) throws IOException JavaDoc, ClosedConnectionException, UnsupportedEncodingException JavaDoc;
620
621     
622     
623     /**
624      * Returns the index of the first occurrence of the given string. The default encoing will be used to decode the string
625      *
626      * @param str any string
627      * @return if the string argument occurs as a substring within this object, then the
628      * index of the first character of the first such substring is returned;
629      * @throws ClosedConnectionException If the underlying socket is already closed
630      * @throws IOException If some other I/O error occurs
631      */

632     public int getIndexOf(String JavaDoc str) throws IOException JavaDoc, ClosedConnectionException;
633     
634     
635     
636
637     /**
638      * Returns the index of the first occurrence of the given string. The default encoing will be used to decode the string
639      *
640      * @param str any string
641      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
642      * @return if the string argument occurs as a substring within this object, then the
643      * index of the first character of the first such substring is returned;
644      * @throws ClosedConnectionException If the underlying socket is already closed
645      * @throws IOException If some other I/O error occurs
646      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
647      */

648     public int getIndexOf(String JavaDoc str, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
649
650     
651     
652     /**
653      * Returns the index of the first occurrence of the given string.
654      *
655      * @param str any string
656      * @param encoding the encoding of the string
657      * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
658      * @return if the string argument occurs as a substring within this object, then the
659      * index of the first character of the first such substring is returned;
660      * @throws ClosedConnectionException If the underlying socket is already closed
661      * @throws IOException If some other I/O error occurs
662      * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
663      */

664     public int getIndexOf(String JavaDoc str, String JavaDoc encoding, int maxLength) throws IOException JavaDoc, ClosedConnectionException, MaxReadSizeExceededException;
665
666
667     /**
668      * Marks the present write position in the connection. Subsequent calls to resetToReadMark() will attempt
669      * to reposition the connection to this point. The write read become in valid by flushing
670      * the connection. <br><br>
671      *
672      * <b>write mark is only supported for autoflush off.</b> E.g.
673      * <pre>
674      * ...
675      * con.setAutoflush(false);
676      *
677      * con.markWritePosition(); // mark current position
678      * con.write((int) 0); // write "emtpy" length field
679      *
680      * int written = con.write("hello world");
681      * written += con.write(" it’s nice to be here");
682      * ...
683      *
684      * con.resetToWriteMark(); // return to length field position
685      * con.write(written); // and update it
686      *
687      * con.flush(); // flush (marker will be removed implicit)
688 … * </pre>
689      */

690     public void markWritePosition();
691     
692
693     /**
694      * remove the mark the present write position in the connection.
695      */

696     public void removeWriteMark();
697     
698     
699     /**
700      * Resets to the marked write position. If the connection has been marked,
701      * then attempt to reposition it at the mark.
702      *
703      * @return true, if reset was successful
704      */

705     public boolean resetToWriteMark();
706
707     
708     /**
709      * Marks the present read position in the connection. Subsequent calls to resetToReadMark() will attempt
710      * to reposition the connection to this point.
711      *
712      */

713     public void markReadPosition();
714     
715
716     /**
717      * remove the mark the present read position in the connection.
718      */

719     public void removeReadMark();
720     
721     
722     /**
723      * Resets to the marked read position. If the connection has been marked,
724      * then attempt to reposition it at the mark.
725      *
726      * @return true, if reset was successful
727      */

728     public boolean resetToReadMark();
729     
730     
731
732     /**
733      * Attaches the given object to this connection
734      *
735      * @param obj The object to be attached; may be null
736      * @return The previously-attached object, if any, otherwise null
737      */

738     public Object JavaDoc attach(Object JavaDoc obj);
739     
740
741     /**
742      * Retrieves the current attachment.
743      *
744      * @return The object currently attached to this key, or null if there is no attachment
745      */

746     public Object JavaDoc attachment();
747     
748     
749
750     /**
751      * sets the value of a option
752      *
753      * @param name the name of the option
754      * @param value the value of the option
755      * @return the IConnection
756      * @throws IOException In an I/O error occurs
757      */

758     public IConnection setOption(String JavaDoc name, Object JavaDoc value) throws IOException JavaDoc;
759     
760     
761     
762     /**
763      * returns the value of a option
764      *
765      * @param name the name of the option
766      * @return the value of the option
767      * @throws IOException In an I/O error occurs
768      */

769     public Object JavaDoc getOption(String JavaDoc name) throws IOException JavaDoc;
770     
771     
772     
773     /**
774      * Returns an unmodifiable map of the options supported by this endpont.
775      *
776      * The key in the returned map is the name of a option, and its value
777      * is the type of the option value. The returned map will never contain null keys or values.
778      *
779      * @return An unmodifiable map of the options supported by this channel
780      */

781     public Map JavaDoc<String JavaDoc,Class JavaDoc> getOptions();
782 }
783
Popular Tags