1 package nom.tam.fits.compression.provider.param.api;
2
3 import nom.tam.fits.BinaryTable;
4 import nom.tam.fits.BinaryTableHDU;
5 import nom.tam.fits.FitsException;
6 import nom.tam.fits.Header;
7 import nom.tam.fits.HeaderCardException;
8 import nom.tam.fits.compression.algorithm.api.ICompressOption;
9 import nom.tam.fits.compression.provider.param.base.CompressParameters;
10
11 /*
12 * #%L
13 * nom.tam FITS library
14 * %%
15 * Copyright (C) 1996 - 2024 nom-tam-fits
16 * %%
17 * This is free and unencumbered software released into the public domain.
18 *
19 * Anyone is free to copy, modify, publish, use, compile, sell, or
20 * distribute this software, either in source code form or as a compiled
21 * binary, for any purpose, commercial or non-commercial, and by any
22 * means.
23 *
24 * In jurisdictions that recognize copyright laws, the author or authors
25 * of this software dedicate any and all copyright interest in the
26 * software to the public domain. We make this dedication for the benefit
27 * of the public at large and to the detriment of our heirs and
28 * successors. We intend this dedication to be an overt act of
29 * relinquishment in perpetuity of all present and future rights to this
30 * software under copyright law.
31 *
32 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
33 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
34 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
35 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
36 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
37 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
38 * OTHER DEALINGS IN THE SOFTWARE.
39 * #L%
40 */
41
42 /**
43 * <p>
44 * (<i>for internal use</i>) Group of parameters that must be synchronized with the hdu meta data for a specific
45 * compression algorithm.
46 * </p>
47 * <p>
48 * NOTE, this interface is meant for internal use only. Implementing it externally to this library might not result in
49 * the desired behavior. If you feed the need to implement compression parameters externally to what is privided by this
50 * library, you are advised to extend the abstract {@link CompressParameters} class or of of its known subclasses
51 * instead
52 * </p>
53 */
54 public interface ICompressParameters {
55
56 /**
57 * Add the columns that hold the metadata for the parameters that are column based to the dhu.
58 *
59 * @param hdu the hdu to add the column
60 *
61 * @throws FitsException if the column could not be added.
62 */
63 void addColumnsToTable(BinaryTableHDU hdu) throws FitsException;
64
65 /**
66 * create a copy of this parameter for another option (normally a copy of the current option).
67 *
68 * @param option the new option for the copied parameter
69 *
70 * @return this (builder pattern)
71 */
72 ICompressParameters copy(ICompressOption option);
73
74 /**
75 * Initialize parameters for the given tile index
76 *
77 * @param index the 0-based tile index
78 */
79 void setTileIndex(int index);
80
81 /**
82 * extract the option data from the column and set it in the option.
83 *
84 * @param index the index in the column.
85 */
86 void getValuesFromColumn(int index);
87
88 /**
89 * extract the option values that are represented by headers from the hdu header.
90 *
91 * @param header the header to extract the option values.
92 *
93 * @deprecated Use {@link #getValuesFromHeader(Header)} instead.
94 */
95 @Deprecated
96 default void getValuesFromHeader(IHeaderAccess header) {
97 getValuesFromHeader(header.getHeader());
98 }
99
100 /**
101 * initialize the column based options of the compression algorithm from the binary table.
102 *
103 * @param header the header of the hdu
104 * @param binaryTable the table of the hdu
105 * @param size the column size
106 *
107 * @throws FitsException if the column could not be initialized
108 *
109 * @deprecated Use {@link #initializeColumns(Header, BinaryTable, int)} instead
110 */
111 @Deprecated
112 default void initializeColumns(IHeaderAccess header, BinaryTable binaryTable, int size) throws FitsException {
113 initializeColumns(header.getHeader(), binaryTable, size);
114 }
115
116 /**
117 * extract the option values that are represented by headers from the hdu header.
118 *
119 * @param header the header to extract the option values.
120 *
121 * @throws HeaderCardException if there was an issue accessing the header
122 */
123 void getValuesFromHeader(Header header) throws HeaderCardException;
124
125 /**
126 * initialize the column based options of the compression algorithm from the binary table.
127 *
128 * @param header the header of the hdu
129 * @param binaryTable the table of the hdu
130 * @param size the column size
131 *
132 * @throws HeaderCardException if there was an issue accessing the header
133 * @throws FitsException if the column could not be initialized
134 */
135 void initializeColumns(Header header, BinaryTable binaryTable, int size) throws HeaderCardException, FitsException;
136
137 /**
138 * initialize the column based parameter to the specified column length.
139 *
140 * @param length the column length.
141 */
142 void initializeColumns(int length);
143
144 /**
145 * set the option values, that are column based, into the columns at the specified index.
146 *
147 * @param index the index in the columns to set.
148 */
149 void setValuesInColumn(int index);
150
151 /**
152 * @deprecated Old, inconsistent method naming. Use {@link #setValuesInColumn(int)} instead. set the option
153 * values, that are column based, into the columns at the specified index.
154 *
155 * @param index the index in the columns to set.
156 */
157 @Deprecated
158 default void setValueInColumn(int index) {
159 setValuesInColumn(index);
160 }
161
162 /**
163 * set the options values, that are hdu based, into the header.
164 *
165 * @param header the header to set the option value
166 *
167 * @throws HeaderCardException if the header could not be set.
168 *
169 * @deprecated Use {@link #setValuesInHeader(Header)} instead
170 */
171 @Deprecated
172 default void setValuesInHeader(IHeaderAccess header) throws HeaderCardException {
173 setValuesInHeader(header == null ? null : header.getHeader());
174 }
175
176 /**
177 * set the options values, that are hdu based, into the header.
178 *
179 * @param header the header to set the option value
180 *
181 * @throws HeaderCardException if the header could not be set.
182 */
183 void setValuesInHeader(Header header) throws HeaderCardException;
184 }