1 package nom.tam.util;
2
3 /*
4 * #%L
5 * nom.tam FITS library
6 * %%
7 * Copyright (C) 1996 - 2024 nom-tam-fits
8 * %%
9 * This is free and unencumbered software released into the public domain.
10 *
11 * Anyone is free to copy, modify, publish, use, compile, sell, or
12 * distribute this software, either in source code form or as a compiled
13 * binary, for any purpose, commercial or non-commercial, and by any
14 * means.
15 *
16 * In jurisdictions that recognize copyright laws, the author or authors
17 * of this software dedicate any and all copyright interest in the
18 * software to the public domain. We make this dedication for the benefit
19 * of the public at large and to the detriment of our heirs and
20 * successors. We intend this dedication to be an overt act of
21 * relinquishment in perpetuity of all present and future rights to this
22 * software under copyright law.
23 *
24 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
25 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
27 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
28 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
29 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
30 * OTHER DEALINGS IN THE SOFTWARE.
31 * #L%
32 */
33
34 import java.io.EOFException;
35 import java.io.IOException;
36
37 /**
38 * @deprecated Use {@link FitsDecoder} instead which provides a similar function but in a more consistent way and with a
39 * less misleading name. This is a rusty rail implementation for of an older abandoned class only,
40 * unsafe for general use. For reading non-FITS encoding you may also use {@link InputDecoder} as a base
41 * for implementing efficient custom decoding of binary inputs in general.
42 *
43 * @see FitsDecoder
44 */
45 @Deprecated
46 public abstract class BufferDecoder extends FitsDecoder {
47
48 private BufferPointer p;
49
50 /**
51 * Instantiates a new decoder for FITS data types.
52 *
53 * @param p Unused, but the position and length fields are set/reset as to pretend that half of the buffer is
54 * perpetually available for reading. However, at no point will there be any data actually in the
55 * buffer of this object, and you should by all means avoid directly loading data from the stream into
56 * this dead-end buffer, other than the hopefully untiggered existing implementation of
57 * <code>checkBuffer(int)</code> (and it's safest if you don't override or ever call
58 * <code>checkBuffer(int)</code> from your code!).
59 */
60 @Deprecated
61 public BufferDecoder(BufferPointer p) {
62 super();
63
64 this.p = p;
65
66 pretendHalfPopulated();
67
68 setInput(new InputReader() {
69 private byte[] b1 = new byte[1];
70
71 @Override
72 public int read() throws IOException {
73 int n = BufferDecoder.this.read(b1, 0, 1);
74 if (n < 0) {
75 return n;
76 }
77 return b1[0];
78 }
79
80 @Override
81 public int read(byte[] b, int from, int length) throws IOException {
82 return BufferDecoder.this.read(b, from, length);
83 }
84 });
85 }
86
87 /**
88 * We'll always pretend the buffer to be half populated at pos=0, in order to avoid triggering a read from the input
89 * into the unused buffer of BufferPointer, or a write to the output from that buffer... If the pointer has no
90 * buffer, length will be 0 also.
91 */
92 private void pretendHalfPopulated() {
93 p.pos = 0;
94 p.length = p.buffer == null ? 0 : p.buffer.length >>> 1;
95 }
96
97 @Deprecated
98 @Override
99 boolean makeAvailable(int needBytes) throws IOException {
100 pretendHalfPopulated();
101 boolean result = super.makeAvailable(needBytes);
102 return result;
103 }
104
105 /**
106 * @deprecated No longer used internally, kept only for back-compatibility since it used to be a needed
107 * abstract method. It's safest if you never override or call this method from your
108 * code!
109 *
110 * @param needBytes the number of byte we need available to decode the next element
111 *
112 * @throws IOException if the data could not be made available due to an IO error of the underlying input.
113 */
114 @Deprecated
115 protected void checkBuffer(int needBytes) throws IOException {
116 }
117
118 @Deprecated
119 @Override
120 protected int read(byte[] buf, int offset, int length) throws IOException {
121 throw new UnsupportedOperationException(
122 "You need to override this with an implementation that reads from the desired input.");
123 }
124
125 /**
126 * @deprecated No longer used internally, kept only for back-compatibility since it used to be a needed
127 * abstract method.
128 *
129 * @param e the <code>EOFException</code> thrown by one of the read calls.
130 * @param start the index of the first array element we wanted to fill
131 * @param index the array index of the element during which the exception was thrown
132 * @param elementSize the number of bytes per element we were processing
133 *
134 * @return the numer of bytes successfully processed from the input before the exception occurred.
135 *
136 * @throws EOFException if the input had no more data to process
137 */
138 @Deprecated
139 protected int eofCheck(EOFException e, int start, int index, int elementSize) throws EOFException {
140 return (int) super.eofCheck(e, (index - start), -1) * elementSize;
141 }
142
143 /**
144 * See the contract of {@link ArrayDataInput#readLArray(Object)}.
145 *
146 * @param o an array, to be populated
147 *
148 * @return the actual number of bytes read from the input, or -1 if already at the
149 * end-of-file.
150 *
151 * @throws IllegalArgumentException if the argument is not an array or if it contains an element that is not
152 * supported for decoding.
153 * @throws IOException if there was an IO error reading from the input
154 */
155 @Deprecated
156 protected long readLArray(Object o) throws IOException {
157 try {
158 return super.readArray(o);
159 } catch (IllegalArgumentException e) {
160 throw new IOException(e);
161 }
162 }
163
164 }