1 /* Copyright 2002-2021 CS GROUP
2 * Licensed to CS GROUP (CS) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * CS licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.orekit.files.ccsds.utils.generation;
18
19 import java.io.IOException;
20 import java.util.List;
21
22 import org.orekit.files.ccsds.definitions.TimeConverter;
23 import org.orekit.files.ccsds.utils.FileFormat;
24 import org.orekit.time.AbsoluteDate;
25 import org.orekit.utils.units.Unit;
26
27 /** Generation interface for CCSDS messages.
28 * @author Luc Maisonobe
29 * @since 11.0
30 */
31 public interface Generator extends AutoCloseable {
32
33 /** Get the name of the output (for error messages).
34 * @return name of the output
35 */
36 String getOutputName();
37
38 /** Get the generated file format.
39 * @return generated file format
40 */
41 FileFormat getFormat();
42
43 /** Start CCSDS message.
44 * @param messageTypeKey key for message type
45 * @param root root element for XML files
46 * @param version format version
47 * @throws IOException if an I/O error occurs.
48 */
49 void startMessage(String root, String messageTypeKey, double version) throws IOException;
50
51 /** End CCSDS message.
52 * @param root root element for XML files
53 * @throws IOException if an I/O error occurs.
54 */
55 void endMessage(String root) throws IOException;
56
57 /** Write comment lines.
58 * @param comments comments to write
59 * @throws IOException if an I/O error occurs.
60 */
61 void writeComments(List<String> comments) throws IOException;
62
63 /** Write a single key/value entry.
64 * @param key the keyword to write
65 * @param value the value to write
66 * @param unit output unit (may be null)
67 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
68 * @throws IOException if an I/O error occurs.
69 */
70 void writeEntry(String key, String value, Unit unit, boolean mandatory) throws IOException;
71
72 /** Write a single key/value entry.
73 * @param key the keyword to write
74 * @param value the value to write
75 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
76 * @throws IOException if an I/O error occurs.
77 */
78 void writeEntry(String key, List<String> value, boolean mandatory) throws IOException;
79
80 /** Write a single key/value entry.
81 * @param key the keyword to write
82 * @param value the value to write
83 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
84 * @throws IOException if an I/O error occurs.
85 */
86 void writeEntry(String key, Enum<?> value, boolean mandatory) throws IOException;
87
88 /** Write a single key/value entry.
89 * @param key the keyword to write
90 * @param converter converter to use for dates
91 * @param date the date to write
92 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
93 * @throws IOException if an I/O error occurs.
94 */
95 void writeEntry(String key, TimeConverter converter, AbsoluteDate date, boolean mandatory) throws IOException;
96
97 /** Write a single key/value entry.
98 * @param key the keyword to write
99 * @param value the value to write
100 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
101 * @throws IOException if an I/O error occurs.
102 */
103 void writeEntry(String key, char value, boolean mandatory) throws IOException;
104
105 /** Write a single key/value entry.
106 * @param key the keyword to write
107 * @param value the value to write
108 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
109 * @throws IOException if an I/O error occurs.
110 */
111 void writeEntry(String key, int value, boolean mandatory) throws IOException;
112
113 /** Write a single key/value entry.
114 * @param key the keyword to write
115 * @param value the value to write (in SI units)
116 * @param unit output unit
117 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
118 * @throws IOException if an I/O error occurs.
119 */
120 void writeEntry(String key, double value, Unit unit, boolean mandatory) throws IOException;
121
122 /** Write a single key/value entry.
123 * @param key the keyword to write
124 * @param value the value to write (in SI units)
125 * @param unit output unit
126 * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
127 * @throws IOException if an I/O error occurs.
128 */
129 void writeEntry(String key, Double value, Unit unit, boolean mandatory) throws IOException;
130
131 /** Finish current line.
132 * @throws IOException if an I/O error occurs.
133 */
134 void newLine() throws IOException;
135
136 /** Write raw data.
137 * @param data raw data to write
138 * @throws IOException if an I/O error occurs.
139 */
140 void writeRawData(char data) throws IOException;
141
142 /** Write raw data.
143 * @param data raw data to write
144 * @throws IOException if an I/O error occurs.
145 */
146 void writeRawData(CharSequence data) throws IOException;
147
148 /** Enter into a new section.
149 * @param name section name
150 * @throws IOException if an I/O error occurs.
151 */
152 void enterSection(String name) throws IOException;
153
154 /** Exit last section.
155 * @return section name
156 * @throws IOException if an I/O error occurs.
157 */
158 String exitSection() throws IOException;
159
160 /** Close the generator.
161 * @throws IOException if an I/O error occurs.
162 */
163 void close() throws IOException;
164
165 /** Convert a date to string value with high precision.
166 * @param converter converter for dates
167 * @param date date to write
168 * @return date as a string
169 */
170 String dateToString(TimeConverter converter, AbsoluteDate date);
171
172 /** Convert a date to string value with high precision.
173 * @param year year
174 * @param month month
175 * @param day day
176 * @param hour hour
177 * @param minute minute
178 * @param seconds seconds
179 * @return date as a string
180 */
181 String dateToString(int year, int month, int day, int hour, int minute, double seconds);
182
183 /** Convert a double to string value with high precision.
184 * <p>
185 * We don't want to loose internal accuracy when writing doubles
186 * but we also don't want to have ugly representations like STEP = 1.25000000000000000
187 * so we try a few simple formats first and fall back to scientific notation
188 * if it doesn't work.
189 * </p>
190 * @param value value to format
191 * @return formatted value, with all original value accuracy preserved, or null
192 * if value is null or {@code Double.NaN}
193 */
194 String doubleToString(double value);
195
196 /** Convert a list of units to a bracketed string.
197 * @param units lists to output (may be null or empty)
198 * @return bracketed string (null if units list is null or empty)
199 */
200 String unitsListToString(List<Unit> units);
201
202 /** Convert a SI unit name to a CCSDS name.
203 * @param siName si unit name
204 * @return CCSDS name for the unit
205 */
206 String siToCcsdsName(String siName);
207
208 }