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
049package jj2000.j2k.io;
050
051import java.io.EOFException;
052import java.io.IOException;
053
054/**
055 * This interface defines the input of binary data from streams and/or files.
056 *
057 * <P>Byte level input (i.e., for byte, int, long, float, etc.) should
058 * always be byte aligned. For example, a request to read an
059 * <tt>int</tt> should always realign the input at the byte level.
060 *
061 * <P>The implementation of this interface should clearly define if
062 * multi-byte input data is read in little- or big-endian byte
063 * ordering (least significant byte first or most significant byte
064 * first, respectively).
065 *
066 * @see EndianType
067 * */
068public interface BinaryDataInput {
069
070    /**
071     * Should read a signed byte (i.e., 8 bit) from the input.
072     * reading, the input should be realigned at the byte level.
073     *
074     * @return The next byte-aligned signed byte (8 bit) from the
075     * input.
076     *
077     * @exception EOFException If the end-of file was reached before
078     * getting all the necessary data.
079     *
080     * @exception IOException If an I/O error ocurred.
081     *
082     *
083     * */
084    public byte readByte() throws EOFException, IOException;
085
086    /**
087     * Should read an unsigned byte (i.e., 8 bit) from the input. It is
088     * returned as an <tt>int</tt> since Java does not have an
089     * unsigned byte type. Prior to reading, the input should be
090     * realigned at the byte level.
091     *
092     * @return The next byte-aligned unsigned byte (8 bit) from the
093     * input, as an <tt>int</tt>.
094     *
095     * @exception EOFException If the end-of file was reached before
096     * getting all the necessary data.
097     *
098     * @exception IOException If an I/O error ocurred.
099     *
100     *
101     *
102     */
103    public int readUnsignedByte() throws EOFException, IOException;
104
105    /**
106     * Should read a signed short (i.e., 16 bit) from the input. Prior to
107     * reading, the input should be realigned at the byte level.
108     *
109     * @return The next byte-aligned signed short (16 bit) from the
110     * input.
111     *
112     * @exception EOFException If the end-of file was reached before
113     * getting all the necessary data.
114     *
115     * @exception IOException If an I/O error ocurred.
116     *
117     *
118     *
119     */
120    public short readShort() throws EOFException, IOException;
121
122    /**
123     * Should read an unsigned short (i.e., 16 bit) from the input. It is
124     * returned as an <tt>int</tt> since Java does not have an
125     * unsigned short type. Prior to reading, the input should be
126     * realigned at the byte level.
127     *
128     * @return The next byte-aligned unsigned short (16 bit) from the
129     * input, as an <tt>int</tt>.
130     *
131     * @exception EOFException If the end-of file was reached before
132     * getting all the necessary data.
133     *
134     * @exception IOException If an I/O error ocurred.
135     *
136     *
137     *
138     */
139    public int readUnsignedShort() throws EOFException, IOException;
140
141    /**
142     * Should read a signed int (i.e., 32 bit) from the input. Prior to
143     * reading, the input should be realigned at the byte level.
144     *
145     * @return The next byte-aligned signed int (32 bit) from the
146     * input.
147     *
148     * @exception EOFException If the end-of file was reached before
149     * getting all the necessary data.
150     *
151     * @exception IOException If an I/O error ocurred.
152     *
153     *
154     *
155     */
156    public int readInt() throws EOFException, IOException;
157
158    /**
159     * Should read an unsigned int (i.e., 32 bit) from the input. It is
160     * returned as a <tt>long</tt> since Java does not have an
161     * unsigned short type. Prior to reading, the input should be
162     * realigned at the byte level.
163     *
164     * @return The next byte-aligned unsigned int (32 bit) from the
165     * input, as a <tt>long</tt>.
166     *
167     * @exception EOFException If the end-of file was reached before
168     * getting all the necessary data.
169     *
170     * @exception IOException If an I/O error ocurred.
171     *
172     *
173     *
174     */
175    public long readUnsignedInt() throws EOFException, IOException;
176
177    /**
178     * Should read a signed long (i.e., 64 bit) from the input. Prior to
179     * reading, the input should be realigned at the byte level.
180     *
181     * @return The next byte-aligned signed long (64 bit) from the
182     * input.
183     *
184     * @exception EOFException If the end-of file was reached before
185     * getting all the necessary data.
186     *
187     * @exception IOException If an I/O error ocurred.
188     *
189     *
190     *
191     */
192    public long readLong() throws EOFException, IOException;
193
194    /**
195     * Should read an IEEE single precision (i.e., 32 bit)
196     * floating-point number from the input. Prior to reading, the
197     * input should be realigned at the byte level.
198     *
199     * @return The next byte-aligned IEEE float (32 bit) from the
200     * input.
201     *
202     * @exception EOFException If the end-of file was reached before
203     * getting all the necessary data.
204     *
205     * @exception IOException If an I/O error ocurred.
206     *
207     *
208     *
209     */
210    public float readFloat() throws EOFException, IOException;
211
212    /**
213     * Should read an IEEE double precision (i.e., 64 bit)
214     * floating-point number from the input. Prior to reading, the
215     * input should be realigned at the byte level.
216     *
217     * @return The next byte-aligned IEEE double (64 bit) from the
218     * input.
219     *
220     * @exception EOFException If the end-of file was reached before
221     * getting all the necessary data.
222     *
223     * @exception IOException If an I/O error ocurred.
224     *
225     *
226     *
227     */
228    public double readDouble() throws EOFException, IOException;
229
230    /**
231     * Returns the endianess (i.e., byte ordering) of the implementing
232     * class. Note that an implementing class may implement only one
233     * type of endianness or both, which would be decided at creatiuon
234     * time.
235     *
236     * @return Either <tt>EndianType.BIG_ENDIAN</tt> or
237     * <tt>EndianType.LITTLE_ENDIAN</tt>
238     *
239     * @see EndianType
240     *
241     *
242     *
243     */
244    public int getByteOrdering();
245
246    /**
247     * Skips <tt>n</tt> bytes from the input. Prior to skipping, the
248     * input should be realigned at the byte level.
249     *
250     * @param n The number of bytes to skip
251     *
252     * @exception EOFException If the end-of file was reached before
253     * all the bytes could be skipped.
254     *
255     * @exception IOException If an I/O error ocurred.
256     *
257     *
258     *
259     */
260    public int skipBytes(int n)throws EOFException, IOException;
261
262}