1 package nom.tam.fits;
2
3 /*
4 * #%L
5 * nom.tam FITS library
6 * %%
7 * Copyright (C) 2004 - 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.IOException;
35
36 import nom.tam.util.ArrayDataInput;
37 import nom.tam.util.ArrayDataOutput;
38
39 /**
40 * I/O interface for various FITS file elements.
41 */
42 public interface FitsElement {
43
44 /**
45 * Returns the byte offset at which this element starts ina file. If the
46 * element was not obtained from an input, then 0 is returned.
47 *
48 * @return the byte at which this element begins. This is only available if
49 * the data is originally read from a random access medium.
50 * Otherwise 0 is returned.
51 */
52 long getFileOffset();
53
54 /**
55 * Returns the size of this elements in the FITS representation. This may
56 * include padding if the element (such as a header or data segment) is
57 * expected to complete a FITS block of 2880 bytes.
58 *
59 * @return The size of this element in bytes, or 0 if the element is empty
60 * or invalid.
61 */
62 long getSize();
63
64 /**
65 * Read a FITS element from the input, starting at the current position.
66 * Ater the read, the implementations should leave the input position
67 * aligned to the start of the next FITS block.
68 *
69 * @param in
70 * The input data stream
71 * @throws FitsException
72 * if the read was unsuccessful.
73 * @throws IOException
74 * if the read was unsuccessful.
75 */
76 void read(ArrayDataInput in) throws FitsException, IOException;
77
78 /**
79 * Reset the input stream to point to the beginning of this element
80 *
81 * @return True if the reset succeeded.
82 */
83 boolean reset();
84
85 /**
86 * Rewrite the contents of the element in place. The data must have been
87 * originally read from a random access device, and the size of the element
88 * may not have changed.
89 *
90 * @throws FitsException
91 * if the rewrite was unsuccessful.
92 * @throws IOException
93 * if the rewrite was unsuccessful.
94 */
95 void rewrite() throws FitsException, IOException;
96
97 /**
98 * Checks if we can write this element back to its source. An element can
99 * only be written back if it is associated to a random accessible input and
100 * the current size FITS within the old block size.
101 *
102 * @return <code>true</code> if this element can be rewritten?
103 */
104 boolean rewriteable();
105
106 /**
107 * Writes the contents of the element to a data sink, adding padding as
108 * necessary if the element (such as a header or data segment) is expected
109 * to complete the FITS block of 2880 bytes.
110 *
111 * @param out
112 * The data sink.
113 * @throws FitsException
114 * if the write was unsuccessful.
115 */
116 void write(ArrayDataOutput out) throws FitsException;
117 }