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.*;
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 * */
067public 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}