001: /*
002: * Copyright (c) xsocket.org, 2006 - 2008. All rights reserved.
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2.1 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: *
018: * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
019: * The latest copy of this software may be found on http://www.xsocket.org/
020: */
021: package org.xsocket.connection;
022:
023: import java.io.Flushable;
024: import java.io.IOException;
025: import java.io.UnsupportedEncodingException;
026: import java.net.SocketTimeoutException;
027: import java.nio.BufferOverflowException;
028: import java.nio.BufferUnderflowException;
029: import java.nio.ByteBuffer;
030: import java.nio.channels.ClosedChannelException;
031: import java.nio.channels.FileChannel;
032: import java.nio.channels.GatheringByteChannel;
033: import java.nio.channels.ReadableByteChannel;
034: import java.nio.channels.WritableByteChannel;
035:
036: import org.xsocket.IDataSink;
037: import org.xsocket.IDataSource;
038: import org.xsocket.MaxReadSizeExceededException;
039:
040: /**
041: * A connection which accesses the underlying channel in a non-blocking manner. Every read I/O operation
042: * will block until it completes. The blocking behavior of write operations will be controlled by the
043: * flush configuration.
044: *
045: * @author grro@xsocket.org
046: */
047: public interface IBlockingConnection extends IConnection, IDataSource,
048: IDataSink, GatheringByteChannel, ReadableByteChannel,
049: WritableByteChannel, Flushable {
050:
051: public static final int DEFAULT_RECEIVE_TIMEOUT = Integer.MAX_VALUE;
052:
053: /**
054: * set autoflush. If autoflush is activated, each write call
055: * will cause a flush. <br><br>
056: *
057: * By default the autoflush is deactivated
058: *
059: * @param autoflush true if autoflush should be activated
060: */
061: public void setAutoflush(boolean autoflush);
062:
063: /**
064: * get autoflush
065: *
066: * @return true, if autoflush is activated
067: */
068: public boolean isAutoflush();
069:
070: /**
071: * flush the send buffer. The method call will block until
072: * the outgoing data has been flushed into the underlying
073: * os-specific send buffer.
074: *
075: * @throws IOException If some other I/O error occurs
076: * @throws SocketTimeoutException If the timeout has been reached
077: * @throws ClosedChannelException if the underlying channel is closed
078: */
079: public void flush() throws ClosedChannelException, IOException,
080: SocketTimeoutException;
081:
082: /**
083: * set the flush mode <br><br> By setting the flush mode with ASYNC (default is SYNC)
084: * the data will be transferred to the underlying connection in a asynchronous way.
085: * In most cases there are high performance improvements. If the {@link IReadWriteableConnection#write(ByteBuffer)}
086: * or {@link IReadWriteableConnection#write(ByteBuffer[])} method will be used, the flush mode
087: * {@link FlushMode#ASYNC} could have side-effects. Because the buffer will be
088: * written asynchronous, it could occur, that the passed-over buffers are not already
089: * written by returning from the write call.
090: *
091: * @param flushMode {@link FlushMode#ASYNC} if flush should be performed asynchronous,
092: * {@link FlushMode#SYNC} if flush should be perform synchronous
093: */
094: public void setFlushmode(FlushMode flushMode);
095:
096: /**
097: * return the flush mode
098: * @return the flush mode
099: */
100: public FlushMode getFlushmode();
101:
102: /**
103: * ad hoc activation of a secured mode (SSL). By performing of this
104: * method all remaining data to send will be flushed.
105: * After this all data will be sent and received in the secured mode
106: *
107: * @throws IOException If some other I/O error occurs
108: */
109: public void activateSecuredMode() throws IOException;
110:
111: /**
112: * returns the size of the data which have already been written, but not
113: * yet transferred to the underlying socket.
114: *
115: * @return the size of the pending data to write
116: */
117: public int getPendingWriteDataSize();
118:
119: /**
120: * set the timeout for calling read methods in millis
121: *
122: * @param timeout the timeout in millis
123: * @throws IOException If some other I/O error occurs
124: */
125: public void setReceiveTimeoutMillis(int timeout) throws IOException;
126:
127: /**
128: * get the timeout for calling read methods in millis
129: *
130: * @return the timeout in millis
131: * @throws IOException If some other I/O error occurs
132: */
133: public int getReceiveTimeoutMillis() throws IOException;
134:
135: /**
136: * suspend reading data from the underlying subsystem
137: *
138: * @throws IOException If some other I/O error occurs
139: */
140: public void suspendRead() throws IOException;
141:
142: /**
143: * resume reading data from the underlying subsystem
144: *
145: * @throws IOException If some other I/O error occurs
146: */
147: public void resumeRead() throws IOException;
148:
149: /**
150: * Resets to the marked write position. If the connection has been marked,
151: * then attempt to reposition it at the mark.
152: *
153: * @return true, if reset was successful
154: */
155: public boolean resetToWriteMark();
156:
157: /**
158: * Resets to the marked read position. If the connection has been marked,
159: * then attempt to reposition it at the mark.
160: *
161: * @return true, if reset was successful
162: */
163: public boolean resetToReadMark();
164:
165: /**
166: * Marks the write position in the connection.
167: */
168: public void markWritePosition();
169:
170: /**
171: * Marks the read position in the connection. Subsequent calls to resetToReadMark() will attempt
172: * to reposition the connection to this point.
173: *
174: */
175: public void markReadPosition();
176:
177: /**
178: * remove the read mark
179: */
180: public void removeReadMark();
181:
182: /**
183: * remove the write mark
184: */
185: public void removeWriteMark();
186:
187: /**
188: * gets the encoding (used by string related methods like write(String) ...)
189: *
190: * @return the encoding
191: */
192: public String getEncoding();
193:
194: /**
195: * sets the encoding (used by string related methods like write(String) ...)
196: *
197: * @param encoding the encoding
198: */
199: public void setEncoding(String encoding);
200:
201: /**
202: * write a message
203: *
204: * @param message the message to write
205: * @param encoding the encoding which should be used th encode the chars into byte (e.g. `US-ASCII` or `UTF-8`)
206: * @return the number of written bytes
207: * @throws BufferOverflowException If the no enough space is available
208: * @throws IOException If some other I/O error occurs
209: */
210: public int write(String message, String encoding)
211: throws IOException, BufferOverflowException;
212:
213: /**
214: * read a ByteBuffer by using a delimiter. The default encoding will be used to decode the delimiter
215: *
216: * For performance reasons, the ByteBuffer readByteBuffer method is
217: * generally preferable to get bytes
218: *
219: * @param delimiter the delimiter
220: * @param encoding the encoding to use
221: * @return the ByteBuffer
222: * @throws BufferUnderflowException If not enough data is available
223: * @throws IOException If some other I/O error occurs
224: */
225: public ByteBuffer[] readByteBufferByDelimiter(String delimiter,
226: String encoding) throws IOException,
227: BufferUnderflowException;
228:
229: /**
230: * read a ByteBuffer by using a delimiter
231: *
232: * For performance reasons, the ByteBuffer readByteBuffer method is
233: * generally preferable to get bytes
234: *
235: * @param delimiter the delimiter
236: * @param encoding the encoding of the delimiter
237: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
238: * @return the ByteBuffer
239: * @throws BufferUnderflowException If not enough data is available
240: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
241: * @throws IOException If some other I/O error occurs
242: */
243: public ByteBuffer[] readByteBufferByDelimiter(String delimiter,
244: String encoding, int maxLength) throws IOException,
245: BufferUnderflowException, MaxReadSizeExceededException;
246:
247: /**
248: * read a byte array by using a delimiter
249: *
250: * For performance reasons, the ByteBuffer readByteBuffer method is
251: * generally preferable to get bytes
252: *
253: * @param delimiter the delimiter
254: * @param encoding the encoding to use
255: * @return the read bytes
256: * @throws BufferUnderflowException If not enough data is available
257: * @throws IOException If some other I/O error occurs
258: */
259: public byte[] readBytesByDelimiter(String delimiter, String encoding)
260: throws IOException, BufferUnderflowException;
261:
262: /**
263: * read a byte array by using a delimiter
264: *
265: * For performance reasons, the ByteBuffer readByteBuffer method is
266: * generally preferable to get bytes
267: *
268: * @param delimiter the delimiter
269: * @param encoding the encoding to use
270: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
271: * @return the read bytes
272: * @throws BufferUnderflowException If not enough data is available
273: * @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
274: * @throws IOException If some other I/O error occurs
275: */
276: public byte[] readBytesByDelimiter(String delimiter,
277: String encoding, int maxLength) throws IOException,
278: BufferUnderflowException, MaxReadSizeExceededException;
279:
280: /**
281: * read a string by using a delimiter
282: *
283: * @param delimiter the delimiter
284: * @param encoding the encoding to use
285: * @return the string
286: * @throws MaxReadSizeExceededException If the max read length has been exceeded and the delimiter hasn’t been found
287: * @throws IOException If some other I/O error occurs
288: * @throws BufferUnderflowException If not enough data is available
289: * @throws UnsupportedEncodingException if the given encoding is not supported
290: */
291: public String readStringByDelimiter(String delimiter,
292: String encoding) throws IOException,
293: BufferUnderflowException, UnsupportedEncodingException,
294: MaxReadSizeExceededException;
295:
296: /**
297: * read a string by using a delimiter
298: *
299: * @param delimiter the delimiter
300: * @param encoding the encoding to use
301: * @param maxLength the max length of bytes that should be read. If the limit is exceeded a MaxReadSizeExceededException will been thrown
302: * @return the string
303: * @throws BufferUnderflowException If not enough data is available
304: * @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
305: * @throws IOException If some other I/O error occurs
306: * @throws UnsupportedEncodingException If the given encoding is not supported
307: */
308: public String readStringByDelimiter(String delimiter,
309: String encoding, int maxLength) throws IOException,
310: BufferUnderflowException, UnsupportedEncodingException,
311: MaxReadSizeExceededException;
312:
313: /**
314: * read a string by using a length definition
315: *
316: * @param length the amount of bytes to read.
317: * @param encoding the encoding to use
318: * @return the string
319: * @throws IOException If some other I/O error occurs
320: * @throws BufferUnderflowException If not enough data is available
321: * @throws UnsupportedEncodingException if the given encoding is not supported
322: * @throws IllegalArgumentException, if the length parameter is negative
323: */
324: public String readStringByLength(int length, String encoding)
325: throws IOException, BufferUnderflowException,
326: UnsupportedEncodingException;
327:
328: /**
329: * transfer the data of the file channel to this data sink
330: *
331: * @param source the source channel
332: * @return the number of transfered bytes
333: * @throws BufferOverflowException If the no enough space is available
334: * @throws IOException If some other I/O error occurs
335: */
336: public long transferFrom(FileChannel source) throws IOException,
337: BufferOverflowException;
338: }
|