001: /*
002: * Copyright (c) 2007, intarsys consulting GmbH
003: *
004: * Redistribution and use in source and binary forms, with or without
005: * modification, are permitted provided that the following conditions are met:
006: *
007: * - Redistributions of source code must retain the above copyright notice,
008: * this list of conditions and the following disclaimer.
009: *
010: * - Redistributions in binary form must reproduce the above copyright notice,
011: * this list of conditions and the following disclaimer in the documentation
012: * and/or other materials provided with the distribution.
013: *
014: * - Neither the name of intarsys nor the names of its contributors may be used
015: * to endorse or promote products derived from this software without specific
016: * prior written permission.
017: *
018: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
019: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
020: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
021: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
022: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
023: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
024: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
025: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
026: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
027: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
028: * POSSIBILITY OF SUCH DAMAGE.
029: */
030: package de.intarsys.tools.randomaccess;
031:
032: import java.io.IOException;
033: import java.io.InputStream;
034: import java.io.OutputStream;
035: import java.io.RandomAccessFile;
036:
037: /**
038: * An interface for an object that can randomly access bytes in a data stream.
039: * <p>
040: * This is an abstraction of {@link RandomAccessFile} to support other data
041: * storage objects (like byte arrays and so on).
042: */
043: public interface IRandomAccess {
044: /**
045: * Sets the offset, measured from the beginning of the data container at
046: * which the next read or write occurs. The offset may be set beyond the end
047: * of the data container. Setting the offset beyond the end of the data
048: * container does not change the data container length. The length will
049: * change only by writing after the offset has been set beyond the end of
050: * the data container.
051: *
052: * @param offset
053: * the offset position, measured in bytes from the beginning of
054: * the data container
055: * @exception IOException
056: * if <code>offset</code> is less than <code>0</code> or
057: * if an I/O error occurs.
058: */
059: public void seek(long offset) throws IOException;
060:
061: /**
062: * Sets the offset, measured from the current offset at which the next read
063: * or write occurs. The offset may be set beyond the end of the data
064: * container. Setting the offset beyond the end of the data container does
065: * not change the data container length. The length will change only by
066: * writing after the offset has been set beyond the end of the data
067: * container.
068: *
069: * @param delta
070: * the ammount of bytes by wich to change the current offset
071: * position
072: *
073: * @exception IOException
074: * if the resulting <code>offset</code> is less than
075: * <code>0</code> or if an I/O error occurs.
076: */
077: public void seekBy(long delta) throws IOException;
078:
079: /**
080: * Reads a byte of data from this data container. The byte is returned as an
081: * integer in the range 0 to 255 (<code>0x00-0x0ff</code>). This method
082: * blocks if no input is yet available.
083: * <p>
084: * This method behaves in exactly the same way as the
085: * {@link InputStream#read()} method of <code>InputStream</code>.
086: *
087: * @return the next byte of data, or <code>-1</code> if the end of the
088: * data container has been reached.
089: * @exception IOException
090: * if an I/O error occurs. Not thrown if the end of the data
091: * container has been reached.
092: */
093: public int read() throws IOException;
094:
095: /**
096: * Returns the current offset in this data container.
097: *
098: * @return the offset from the beginning of the data container, in bytes, at
099: * which the next read or write occurs.
100: * @exception IOException
101: * if an I/O error occurs.
102: */
103: public long getOffset() throws IOException;
104:
105: /**
106: * Returns the length of this data container.
107: *
108: * @return the length of this data container, measured in bytes.
109: * @exception IOException
110: * if an I/O error occurs.
111: */
112: public long getLength() throws IOException;
113:
114: /**
115: * Assign the length. All bytes after length are truncated. If the real
116: * length is currently less than newLength, the data structure will be
117: * enlarged.
118: *
119: * @param newLength
120: * @throws IOException
121: */
122: public void setLength(long newLength) throws IOException;
123:
124: /**
125: * Reads up to <code>buffer.length</code> bytes of data from this data
126: * container into an array of bytes. This method blocks until at least one
127: * byte of input is available.
128: * <p>
129: * This method behaves in the exactly the same way as the
130: * {@link InputStream#read(byte[])} method of <code>InputStream</code>.
131: *
132: * @param buffer
133: * the buffer into which the data is read.
134: * @return the total number of bytes read into the buffer, or
135: * <code>-1</code> if there is no more data because the end of
136: * this data container has been reached.
137: * @exception IOException
138: * if an I/O error occurs.
139: */
140: public int read(byte[] buffer) throws IOException;
141:
142: /**
143: * Reads up to <code>len</code> bytes of data from this data container
144: * into an array of bytes. This method blocks until at least one byte of
145: * input is available.
146: * <p>
147: *
148: * @param b
149: * the buffer into which the data is read.
150: * @param off
151: * the start offset of the data.
152: * @param len
153: * the maximum number of bytes read.
154: * @return the total number of bytes read into the buffer, or
155: * <code>-1</code> if there is no more data because the end of the
156: * file has been reached.
157: * @exception IOException
158: * if an I/O error occurs.
159: */
160: public int read(byte[] buffer, int start, int numBytes)
161: throws IOException;
162:
163: /**
164: * Closes this random access data container and releases any system
165: * resources associated with the stream. A closed random access data
166: * container cannot perform input or output operations and cannot be
167: * reopened.
168: *
169: * @exception IOException
170: * if an I/O error occurs.
171: */
172: public void close() throws IOException;
173:
174: /**
175: * Force changes to be made persistent.
176: *
177: * @throws IOException
178: */
179: public void flush() throws IOException;
180:
181: /**
182: * <code>true</code> if this is a read only data container.
183: *
184: * @return <code>true</code> if this is a read only data container.
185: */
186: public boolean isReadOnly();
187:
188: /**
189: * Writes the specified byte . The write starts at the current offset.
190: *
191: * @param b
192: * the <code>byte</code> to be written.
193: * @exception IOException
194: * if an I/O error occurs.
195: */
196: public void write(int b) throws IOException;
197:
198: /**
199: * Writes <code>b.length</code> bytes from the specified byte array,
200: * starting at the current offset.
201: *
202: * @param b
203: * the data.
204: * @exception IOException
205: * if an I/O error occurs.
206: */
207: public void write(byte[] buffer) throws IOException;
208:
209: /**
210: * Writes <code>len</code> bytes from the specified byte array starting at
211: * <code>start</code>.
212: *
213: * @param buffer
214: * the data.
215: * @param start
216: * the start offset in the data.
217: * @param numBytes
218: * the number of bytes to write.
219: * @exception IOException
220: * if an I/O error occurs.
221: */
222: public abstract void write(byte[] buffer, int start, int numBytes)
223: throws IOException;
224:
225: /**
226: * A {@link InputStream} view on the data structure.
227: *
228: * @return A {@link InputStream} view on the data structure.
229: */
230: public abstract InputStream asInputStream();
231:
232: /**
233: * A {@link OutputStream} view on the data structure.
234: *
235: * @return A {@link OutputStream} view on the data structure.
236: */
237: public abstract OutputStream asOutputStream();
238:
239: /**
240: * Mark the current offset into the data in a stack like manner.
241: */
242: public abstract void mark() throws IOException;
243:
244: /**
245: * Reset to the last position on the mark-stack.
246: */
247: public abstract void reset() throws IOException;
248: }
|