1 package nom.tam.util;
2
3 import java.io.DataInput;
4 import java.io.EOFException;
5
6 /*
7 * #%L
8 * nom.tam FITS library
9 * %%
10 * Copyright (C) 2004 - 2024 nom-tam-fits
11 * %%
12 * This is free and unencumbered software released into the public domain.
13 *
14 * Anyone is free to copy, modify, publish, use, compile, sell, or
15 * distribute this software, either in source code form or as a compiled
16 * binary, for any purpose, commercial or non-commercial, and by any
17 * means.
18 *
19 * In jurisdictions that recognize copyright laws, the author or authors
20 * of this software dedicate any and all copyright interest in the
21 * software to the public domain. We make this dedication for the benefit
22 * of the public at large and to the detriment of our heirs and
23 * successors. We intend this dedication to be an overt act of
24 * relinquishment in perpetuity of all present and future rights to this
25 * software under copyright law.
26 *
27 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
28 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
29 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
30 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
31 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
32 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
33 * OTHER DEALINGS IN THE SOFTWARE.
34 * #L%
35 */
36
37 import java.io.IOException;
38
39 /**
40 * Interface for reading array data from inputs.
41 */
42 public interface ArrayDataInput extends InputReader, DataInput, FitsIO {
43
44 /**
45 * See the general contract of the <code>mark</code> method of <code>InputStream</code>.
46 *
47 * @param readlimit the maximum limit of bytes that can be read before the mark position becomes invalid.
48 *
49 * @see java.io.BufferedInputStream#reset()
50 *
51 * @throws IOException if the operation failed
52 */
53 void mark(int readlimit) throws IOException;
54
55 /**
56 * See the general contract of the <code>markSupported</code> method of <code>InputStream</code>.
57 *
58 * @return true if this stream instance supports the mark and reset methods; false otherwise.
59 */
60 default boolean markSupported() {
61 return true;
62 }
63
64 /**
65 * Read an array of byte's. The call generally follows the contract of {@link InputReader#read(byte[], int, int)},
66 * for the full length of the array, starting from the first element (index 0).
67 *
68 * @return number of bytes read, or -1 if at the end of the file.
69 *
70 * @see #readFully(byte[])
71 *
72 * @param buf array of byte's.
73 *
74 * @throws EOFException if already at the end of file.
75 * @throws IOException if one of the underlying read operations failed
76 */
77 int read(byte[] buf) throws EOFException, IOException;
78
79 /**
80 * Read an array of boolean's.
81 *
82 * @return number of bytes read.
83 *
84 * @param buf array of boolean's.
85 *
86 * @throws EOFException if already at the end of file.
87 * @throws IOException if one of the underlying read operations failed
88 */
89 default int read(boolean[] buf) throws EOFException, IOException {
90 return read(buf, 0, buf.length);
91 }
92
93 /**
94 * Read a segment of an array of boolean's.
95 *
96 * @return number of bytes read.
97 *
98 * @param buf array of boolean's.
99 * @param offset start index in the array
100 * @param size number of array elements to read
101 *
102 * @throws EOFException if already at the end of file.
103 * @throws IOException if one of the underlying read operations failed
104 */
105 int read(boolean[] buf, int offset, int size) throws EOFException, IOException;
106
107 /**
108 * Read an array of booleans, possibly including legal <code>null</code> values.
109 *
110 * @return number of bytes read.
111 *
112 * @param buf array of boolean's.
113 *
114 * @throws EOFException if already at the end of file.
115 * @throws IOException if one of the underlying read operations failed
116 *
117 * @since 1.16
118 */
119 default int read(Boolean[] buf) throws EOFException, IOException {
120 return read(buf, 0, buf.length);
121 }
122
123 /**
124 * Reads into an array of booleans, possibly including legal <code>null</code> values. The method has a default
125 * implementation, calls {@link #readBoolean()} element by element. Classes that implement this interface might want
126 * to replace that with a more efficient block read implementation and/or to add the desired translation for
127 * <code>null</code> values.
128 *
129 * @return number of bytes read.
130 *
131 * @param buf array of boolean's.
132 * @param offset start index in the array
133 * @param size number of array elements to read
134 *
135 * @throws EOFException if already at the end of file.
136 * @throws IOException if one of the underlying read operations failed
137 *
138 * @since 1.16
139 */
140 default int read(Boolean[] buf, int offset, int size) throws EOFException, IOException {
141 int to = offset + size;
142 for (int i = offset; i < to; i++) {
143 buf[i] = readBoolean();
144 }
145 return size;
146 }
147
148 /**
149 * Read an array of char's.
150 *
151 * @return number of bytes read.
152 *
153 * @param buf array of char's.
154 *
155 * @throws EOFException if already at the end of file.
156 * @throws IOException if one of the underlying read operations failed
157 */
158 default int read(char[] buf) throws EOFException, IOException {
159 return read(buf, 0, buf.length);
160 }
161
162 /**
163 * Read a segment of an array of char's.
164 *
165 * @return number of bytes read.
166 *
167 * @param buf array of char's.
168 * @param offset start index in the array
169 * @param size number of array elements to read
170 *
171 * @throws EOFException if already at the end of file.
172 * @throws IOException if one of the underlying read operations failed
173 */
174 int read(char[] buf, int offset, int size) throws EOFException, IOException;
175
176 /**
177 * Read an array of double's.
178 *
179 * @return number of bytes read.
180 *
181 * @param buf array of double's.
182 *
183 * @throws EOFException if already at the end of file.
184 * @throws IOException if one of the underlying read operations failed
185 */
186 default int read(double[] buf) throws EOFException, IOException {
187 return read(buf, 0, buf.length);
188 }
189
190 /**
191 * Read a segment of an array of double's.
192 *
193 * @return number of bytes read, or -1 if at the end of file/stream
194 *
195 * @param buf array of double's.
196 * @param offset start index in the array
197 * @param size number of array elements to read
198 *
199 * @throws EOFException if already at the end of file.
200 * @throws IOException if one of the underlying read operations failed
201 */
202 int read(double[] buf, int offset, int size) throws EOFException, IOException;
203
204 /**
205 * Read an array of float's.
206 *
207 * @return number of bytes read.
208 *
209 * @param buf array of float's.
210 *
211 * @throws EOFException if already at the end of file.
212 * @throws IOException if one of the underlying read operations failed
213 */
214 default int read(float[] buf) throws EOFException, IOException {
215 return read(buf, 0, buf.length);
216 }
217
218 /**
219 * Read a segment of an array of float's.
220 *
221 * @return number of bytes read.
222 *
223 * @param buf array of float's.
224 * @param offset start index in the array
225 * @param size number of array elements to read
226 *
227 * @throws EOFException if already at the end of file.
228 * @throws IOException if one of the underlying read operations failed
229 */
230 int read(float[] buf, int offset, int size) throws EOFException, IOException;
231
232 /**
233 * Read an array of int's.
234 *
235 * @return number of bytes read.
236 *
237 * @param buf array of int's.
238 *
239 * @throws EOFException if already at the end of file.
240 * @throws IOException if one of the underlying read operations failed
241 */
242 default int read(int[] buf) throws EOFException, IOException {
243 return read(buf, 0, buf.length);
244 }
245
246 /**
247 * Read a segment of an array of int's.
248 *
249 * @return number of bytes read.
250 *
251 * @param buf array of int's.
252 * @param offset start index in the array
253 * @param size number of array elements to read
254 *
255 * @throws EOFException if already at the end of file.
256 * @throws IOException if one of the underlying read operations failed
257 */
258 int read(int[] buf, int offset, int size) throws EOFException, IOException;
259
260 /**
261 * Read a segment of an array of long's.
262 *
263 * @return number of bytes read.
264 *
265 * @param buf array of long's.
266 *
267 * @throws EOFException if already at the end of file.
268 * @throws IOException if one of the underlying read operations failed
269 */
270 default int read(long[] buf) throws EOFException, IOException {
271 return read(buf, 0, buf.length);
272 }
273
274 /**
275 * Read a segment of an array of long's.
276 *
277 * @return number of bytes read.
278 *
279 * @param buf array of long's.
280 * @param offset start index in the array
281 * @param size number of array elements to read
282 *
283 * @throws EOFException if already at the end of file.
284 * @throws IOException if one of the underlying read operations failed
285 */
286 int read(long[] buf, int offset, int size) throws EOFException, IOException;
287
288 /**
289 * Read an array of short's.
290 *
291 * @return number of bytes read.
292 *
293 * @param buf array of short's.
294 *
295 * @throws EOFException if already at the end of file.
296 * @throws IOException if one of the underlying read operations failed
297 */
298 default int read(short[] buf) throws EOFException, IOException {
299 return read(buf, 0, buf.length);
300 }
301
302 /**
303 * Read a segment of an array of short's.
304 *
305 * @return number of bytes read.
306 *
307 * @param buf array of short's.
308 * @param offset start index in the array
309 * @param size number of array elements to read
310 *
311 * @throws EOFException if already at the end of file.
312 * @throws IOException if one of the underlying read operations failed
313 */
314 int read(short[] buf, int offset, int size) throws EOFException, IOException;
315
316 /**
317 * @deprecated Use {@link #readLArray(Object)} instead.
318 *
319 * @param o a Java array object, including heterogeneous arrays of arrays. If
320 * <code>null</code>, nothing will be read from the output.
321 *
322 * @return the number of bytes read from the input.
323 *
324 * @throws EOFException if already at the end of file.
325 * @throws IOException if there was an IO error, other than the end-of-file, while reading from the
326 * input
327 * @throws IllegalArgumentException if the supplied object is not a Java array or if it contains Java types that
328 * are not supported by the decoder.
329 */
330 @Deprecated
331 default int readArray(Object o) throws EOFException, IOException, IllegalArgumentException {
332 return (int) readLArray(o);
333 }
334
335 /**
336 * Reads a Java array from the input, translating it from its binary representation to Java data format. The
337 * argument may be a generic Java array, including multi-dimensional arrays and heterogeneous arrays of arrays. The
338 * implementation may not populate the supplied object fully. The caller may use the return value to check against
339 * the expected number of bytes to determine whether or not the argument was fully poupulated or not.
340 *
341 * @param o a Java array object, including heterogeneous arrays of arrays. If
342 * <code>null</code>, nothing will be read from the output.
343 *
344 * @return the number of bytes read from the input.
345 *
346 * @throws EOFException if already at the end of file.
347 * @throws IOException if there was an IO error, other than the end-of-file, while reading from the
348 * input
349 * @throws IllegalArgumentException if the supplied object is not a Java array or if it contains Java types that are
350 * not supported by the decoder.
351 *
352 * @see #readArrayFully(Object)
353 */
354 long readLArray(Object o) throws EOFException, IOException, IllegalArgumentException;
355
356 /**
357 * Reads a Java array from the input, populating all elements, or else throwing and {@link java.io.EOFException}.
358 *
359 * @param o a Java array object, including heterogeneous arrays of arrays. If
360 * <code>null</code>, nothing will be read from the output.
361 *
362 * @throws EOFException if already at the end of file.
363 * @throws IOException if there was an IO error.
364 * @throws IllegalArgumentException if the supplied object is not a Java array or if it contains Java types that are
365 * not supported by the decoder.
366 *
367 * @see #readLArray(Object)
368 * @see #readImage(Object)
369 *
370 * @since 1.16
371 */
372 default void readArrayFully(Object o) throws EOFException, IOException, IllegalArgumentException {
373 if (readLArray(o) != FitsEncoder.computeSize(o)) {
374 throw new EOFException("Incomplete array read (assuming default FITS format).");
375 }
376 }
377
378 /**
379 * Like {@link #readArrayFully(Object)} but strictly for numerical types only.
380 *
381 * @param o An any-dimensional array containing only numerical types
382 *
383 * @throws EOFException if already at the end of file.
384 * @throws IllegalArgumentException if the argument is not an array or if it contains an element that is not
385 * supported.
386 * @throws IOException if there was an IO error, uncluding end-of-file ({@link EOFException}, before
387 * all components of the supplied array were populated from the input.
388 *
389 * @see #readArrayFully(Object)
390 *
391 * @since 1.18
392 */
393 default void readImage(Object o) throws IOException, IllegalArgumentException {
394 readArrayFully(o);
395 }
396
397 /**
398 * See the general contract of the <code>reset</code> method of <code>InputStream</code>.
399 * <p>
400 * If <code>markpos</code> is <code>-1</code> (no mark has been set or the mark has been invalidated), an
401 * <code>IOException</code> is thrown. Otherwise, <code>pos</code> is set equal to <code>markpos</code>.
402 *
403 * @exception IOException if this stream has not been marked or, if the mark has been invalidated, or the stream has
404 * been closed by invoking its {@link #close()} method, or an I/O error occurs.
405 *
406 * @see java.io.BufferedInputStream#mark(int)
407 */
408 void reset() throws IOException;
409
410 /**
411 * Skip the number of bytes. This differs from the skip method in that it will throw an EOF if a forward skip cannot
412 * be fully accomplished... (However that isn't supposed to happen with a random access file, so there is probably
413 * no operational difference).
414 *
415 * @param distance the number of bytes to skip. Negative arguments are generally allowed, and subclass
416 * implementations may support it or else return 0 when a negative distance is specified.
417 *
418 * @return the number of bytes actually skipped
419 *
420 * @throws EOFException if the end (or beginning) of the stream was reached before skipping the required number of
421 * bytes. This does not happen typically with forward skips on random access files, where
422 * positioning beyond the EOF is generally allowed for writing.
423 * @throws IOException if the underlying stream failed
424 *
425 * @see java.io.InputStream#skip(long)
426 * @see #skipAllBytes(long)
427 */
428 long skip(long distance) throws EOFException, IOException;
429
430 /**
431 * Skips a number of bytes from the input. This differs from the {@link #skip(long)} method in that it will throw an
432 * EOF if the skip cannot be fully accomplished as requested...
433 *
434 * @param toSkip the number of bytes to skip forward. Subclass implementations may support negative valued
435 * arguments for a backward skip also.
436 *
437 * @throws EOFException if the end (or beginning) of the stream was reached before skipping the required number of
438 * bytes. This does not happen typically with forward skips on random access files, where
439 * positioning beyond the EOF is generally allowed for writing.
440 * @throws IOException if there was an underlying IO failure.
441 *
442 * @see #skip(long)
443 */
444 void skipAllBytes(long toSkip) throws EOFException, IOException;
445
446 /**
447 * @deprecated This call is handled by {@link #skipAllBytes(long)}, without the need for a separate
448 * implementation. Skips a number of bytes from the input. See
449 * {@link #skipAllBytes(long)}.
450 *
451 * @param toSkip the number of bytes to skip forward. Subclass implementations may support negative
452 * valued arguments for a backward skip also.
453 *
454 * @throws EOFException if the end (or beginning) of the stream was reached before skipping the required number
455 * of bytes. This does not happen typically with forward skips on random access files,
456 * where positioning beyond the EOF is generally allowed for writing.
457 * @throws IOException if there was an underlying IO failure.
458 */
459 @Deprecated
460 default void skipAllBytes(int toSkip) throws EOFException, IOException {
461 skipAllBytes((long) toSkip);
462 }
463
464 @Override
465 void readFully(byte[] b, int off, int len) throws IOException;
466
467 }