001: /*
002: * $RCSfile: BinaryDataInput.java,v $
003: * $Revision: 1.1 $
004: * $Date: 2005/02/11 05:02:15 $
005: * $State: Exp $
006: *
007: * Interface: BinaryDataInput
008: *
009: * Description: Stream like interface for binary
010: * input from a stream or file.
011: *
012: *
013: *
014: * COPYRIGHT:
015: *
016: * This software module was originally developed by Raphaël Grosbois and
017: * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
018: * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
019: * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
020: * Centre France S.A) in the course of development of the JPEG2000
021: * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
022: * software module is an implementation of a part of the JPEG 2000
023: * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
024: * Systems AB and Canon Research Centre France S.A (collectively JJ2000
025: * Partners) agree not to assert against ISO/IEC and users of the JPEG
026: * 2000 Standard (Users) any of their rights under the copyright, not
027: * including other intellectual property rights, for this software module
028: * with respect to the usage by ISO/IEC and Users of this software module
029: * or modifications thereof for use in hardware or software products
030: * claiming conformance to the JPEG 2000 Standard. Those intending to use
031: * this software module in hardware or software products are advised that
032: * their use may infringe existing patents. The original developers of
033: * this software module, JJ2000 Partners and ISO/IEC assume no liability
034: * for use of this software module or modifications thereof. No license
035: * or right to this software module is granted for non JPEG 2000 Standard
036: * conforming products. JJ2000 Partners have full right to use this
037: * software module for his/her own purpose, assign or donate this
038: * software module to any third party and to inhibit third parties from
039: * using this software module for non JPEG 2000 Standard conforming
040: * products. This copyright notice must be included in all copies or
041: * derivative works of this software module.
042: *
043: * Copyright (c) 1999/2000 JJ2000 Partners.
044: *
045: *
046: *
047: */
048:
049: package jj2000.j2k.io;
050:
051: import java.io.*;
052:
053: /**
054: * This interface defines the input of binary data from streams and/or files.
055: *
056: * <P>Byte level input (i.e., for byte, int, long, float, etc.) should
057: * always be byte aligned. For example, a request to read an
058: * <tt>int</tt> should always realign the input at the byte level.
059: *
060: * <P>The implementation of this interface should clearly define if
061: * multi-byte input data is read in little- or big-endian byte
062: * ordering (least significant byte first or most significant byte
063: * first, respectively).
064: *
065: * @see EndianType
066: * */
067: public interface BinaryDataInput {
068:
069: /**
070: * Should read a signed byte (i.e., 8 bit) from the input.
071: * reading, the input should be realigned at the byte level.
072: *
073: * @return The next byte-aligned signed byte (8 bit) from the
074: * input.
075: *
076: * @exception EOFException If the end-of file was reached before
077: * getting all the necessary data.
078: *
079: * @exception IOException If an I/O error ocurred.
080: *
081: *
082: * */
083: public byte readByte() throws EOFException, IOException;
084:
085: /**
086: * Should read an unsigned byte (i.e., 8 bit) from the input. It is
087: * returned as an <tt>int</tt> since Java does not have an
088: * unsigned byte type. Prior to reading, the input should be
089: * realigned at the byte level.
090: *
091: * @return The next byte-aligned unsigned byte (8 bit) from the
092: * input, as an <tt>int</tt>.
093: *
094: * @exception EOFException If the end-of file was reached before
095: * getting all the necessary data.
096: *
097: * @exception IOException If an I/O error ocurred.
098: *
099: *
100: *
101: */
102: public int readUnsignedByte() throws EOFException, IOException;
103:
104: /**
105: * Should read a signed short (i.e., 16 bit) from the input. Prior to
106: * reading, the input should be realigned at the byte level.
107: *
108: * @return The next byte-aligned signed short (16 bit) from the
109: * input.
110: *
111: * @exception EOFException If the end-of file was reached before
112: * getting all the necessary data.
113: *
114: * @exception IOException If an I/O error ocurred.
115: *
116: *
117: *
118: */
119: public short readShort() throws EOFException, IOException;
120:
121: /**
122: * Should read an unsigned short (i.e., 16 bit) from the input. It is
123: * returned as an <tt>int</tt> since Java does not have an
124: * unsigned short type. Prior to reading, the input should be
125: * realigned at the byte level.
126: *
127: * @return The next byte-aligned unsigned short (16 bit) from the
128: * input, as an <tt>int</tt>.
129: *
130: * @exception EOFException If the end-of file was reached before
131: * getting all the necessary data.
132: *
133: * @exception IOException If an I/O error ocurred.
134: *
135: *
136: *
137: */
138: public int readUnsignedShort() throws EOFException, IOException;
139:
140: /**
141: * Should read a signed int (i.e., 32 bit) from the input. Prior to
142: * reading, the input should be realigned at the byte level.
143: *
144: * @return The next byte-aligned signed int (32 bit) from the
145: * input.
146: *
147: * @exception EOFException If the end-of file was reached before
148: * getting all the necessary data.
149: *
150: * @exception IOException If an I/O error ocurred.
151: *
152: *
153: *
154: */
155: public int readInt() throws EOFException, IOException;
156:
157: /**
158: * Should read an unsigned int (i.e., 32 bit) from the input. It is
159: * returned as a <tt>long</tt> since Java does not have an
160: * unsigned short type. Prior to reading, the input should be
161: * realigned at the byte level.
162: *
163: * @return The next byte-aligned unsigned int (32 bit) from the
164: * input, as a <tt>long</tt>.
165: *
166: * @exception EOFException If the end-of file was reached before
167: * getting all the necessary data.
168: *
169: * @exception IOException If an I/O error ocurred.
170: *
171: *
172: *
173: */
174: public long readUnsignedInt() throws EOFException, IOException;
175:
176: /**
177: * Should read a signed long (i.e., 64 bit) from the input. Prior to
178: * reading, the input should be realigned at the byte level.
179: *
180: * @return The next byte-aligned signed long (64 bit) from the
181: * input.
182: *
183: * @exception EOFException If the end-of file was reached before
184: * getting all the necessary data.
185: *
186: * @exception IOException If an I/O error ocurred.
187: *
188: *
189: *
190: */
191: public long readLong() throws EOFException, IOException;
192:
193: /**
194: * Should read an IEEE single precision (i.e., 32 bit)
195: * floating-point number from the input. Prior to reading, the
196: * input should be realigned at the byte level.
197: *
198: * @return The next byte-aligned IEEE float (32 bit) from the
199: * input.
200: *
201: * @exception EOFException If the end-of file was reached before
202: * getting all the necessary data.
203: *
204: * @exception IOException If an I/O error ocurred.
205: *
206: *
207: *
208: */
209: public float readFloat() throws EOFException, IOException;
210:
211: /**
212: * Should read an IEEE double precision (i.e., 64 bit)
213: * floating-point number from the input. Prior to reading, the
214: * input should be realigned at the byte level.
215: *
216: * @return The next byte-aligned IEEE double (64 bit) from the
217: * input.
218: *
219: * @exception EOFException If the end-of file was reached before
220: * getting all the necessary data.
221: *
222: * @exception IOException If an I/O error ocurred.
223: *
224: *
225: *
226: */
227: public double readDouble() throws EOFException, IOException;
228:
229: /**
230: * Returns the endianess (i.e., byte ordering) of the implementing
231: * class. Note that an implementing class may implement only one
232: * type of endianness or both, which would be decided at creatiuon
233: * time.
234: *
235: * @return Either <tt>EndianType.BIG_ENDIAN</tt> or
236: * <tt>EndianType.LITTLE_ENDIAN</tt>
237: *
238: * @see EndianType
239: *
240: *
241: *
242: */
243: public int getByteOrdering();
244:
245: /**
246: * Skips <tt>n</tt> bytes from the input. Prior to skipping, the
247: * input should be realigned at the byte level.
248: *
249: * @param n The number of bytes to skip
250: *
251: * @exception EOFException If the end-of file was reached before
252: * all the bytes could be skipped.
253: *
254: * @exception IOException If an I/O error ocurred.
255: *
256: *
257: *
258: */
259: public int skipBytes(int n) throws EOFException, IOException;
260:
261: }
|