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 default void getValuesFromHeader(IHeaderAccess header) {
96 getValuesFromHeader(header.getHeader());
97 }
98
99 /**
100 * initialize the column based options of the compression algorithm from the binary table.
101 *
102 * @param header the header of the hdu
103 * @param binaryTable the table of the hdu
104 * @param size the column size
105 *
106 * @throws FitsException if the column could not be initialized
107 *
108 * @deprecated Use {@link #initializeColumns(Header, BinaryTable, int)} instead
109 */
110 default void initializeColumns(IHeaderAccess header, BinaryTable binaryTable, int size) throws FitsException {
111 initializeColumns(header.getHeader(), binaryTable, size);
112 }
113
114 /**
115 * extract the option values that are represented by headers from the hdu header.
116 *
117 * @param header the header to extract the option values.
118 *
119 * @throws HeaderCardException if there was an issue accessing the header
120 */
121 void getValuesFromHeader(Header header) throws HeaderCardException;
122
123 /**
124 * initialize the column based options of the compression algorithm from the binary table.
125 *
126 * @param header the header of the hdu
127 * @param binaryTable the table of the hdu
128 * @param size the column size
129 *
130 * @throws HeaderCardException if there was an issue accessing the header
131 * @throws FitsException if the column could not be initialized
132 */
133 void initializeColumns(Header header, BinaryTable binaryTable, int size) throws HeaderCardException, FitsException;
134
135 /**
136 * initialize the column based parameter to the specified column length.
137 *
138 * @param length the column length.
139 */
140 void initializeColumns(int length);
141
142 /**
143 * set the option values, that are column based, into the columns at the specified index.
144 *
145 * @param index the index in the columns to set.
146 */
147 void setValuesInColumn(int index);
148
149 /**
150 * @deprecated Old, inconsistent method naming. Use {@link #setValuesInColumn(int)} instead. set the option
151 * values, that are column based, into the columns at the specified index.
152 *
153 * @param index the index in the columns to set.
154 */
155 @Deprecated
156 default void setValueInColumn(int index) {
157 setValuesInColumn(index);
158 }
159
160 /**
161 * set the options values, that are hdu based, into the header.
162 *
163 * @param header the header to set the option value
164 *
165 * @throws HeaderCardException if the header could not be set.
166 *
167 * @deprecated Use {@link #setValuesInHeader(Header)} instead
168 */
169 default void setValuesInHeader(IHeaderAccess header) throws HeaderCardException {
170 setValuesInHeader(header == null ? null : header.getHeader());
171 }
172
173 /**
174 * set the options values, that are hdu based, into the header.
175 *
176 * @param header the header to set the option value
177 *
178 * @throws HeaderCardException if the header could not be set.
179 */
180 void setValuesInHeader(Header header) throws HeaderCardException;
181 }