1   /* Copyright 2002-2025 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.Formatter;
26  import org.orekit.utils.units.Unit;
27  
28  /** Generation interface for CCSDS messages.
29   * @author Luc Maisonobe
30   * @since 11.0
31   */
32  public interface Generator extends AutoCloseable {
33  
34      /** Get the name of the output (for error messages).
35       * @return name of the output
36       */
37      String getOutputName();
38  
39      /** Get the generated file format.
40       * @return generated file format
41       */
42      FileFormat getFormat();
43  
44      /**
45       *  Used to format dates and doubles to string.
46       * @return formatter
47       */
48      Formatter getFormatter();
49  
50      /** Start CCSDS message.
51       * @param messageTypeKey key for message type
52       * @param root root element for XML files
53       * @param version format version
54       * @throws IOException if an I/O error occurs.
55       */
56      void startMessage(String root, String messageTypeKey, double version) throws IOException;
57  
58      /** End CCSDS message.
59       * @param root root element for XML files
60       * @throws IOException if an I/O error occurs.
61       */
62      void endMessage(String root) throws IOException;
63  
64      /** Write comment lines.
65       * @param comments comments to write
66       * @throws IOException if an I/O error occurs.
67       */
68      void writeComments(List<String> comments) throws IOException;
69  
70      /** Write a single key/value entry.
71       * @param key   the keyword to write
72       * @param value the value to write
73       * @param unit output unit (may be null)
74       * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
75       * @throws IOException if an I/O error occurs.
76       */
77      void writeEntry(String key, String value, Unit unit, boolean mandatory) throws IOException;
78  
79      /** Write a single key/value entry.
80       * @param key   the keyword to write
81       * @param value the value to write
82       * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
83       * @throws IOException if an I/O error occurs.
84       */
85      void writeEntry(String key, List<String> value, boolean mandatory) throws IOException;
86  
87      /** Write a single key/value entry.
88       * @param key   the keyword to write
89       * @param value the value to write
90       * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
91       * @throws IOException if an I/O error occurs.
92       */
93      void writeEntry(String key, Enum<?> value, boolean mandatory) throws IOException;
94  
95      /** Write a single key/value entry.
96       * @param key   the keyword to write
97       * @param converter converter to use for dates
98       * @param date the date to write
99       * @param forceCalendar if true, the date is forced to calendar format
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, TimeConverter converter, AbsoluteDate date, boolean forceCalendar, 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, char value, boolean mandatory) throws IOException;
112 
113     /**
114      * Write a single key/value entry.
115      *
116      * <p>Note that the {@code mandatory} flag has no effect and a value is always written
117      * because the whole domain of {@code value} is treated as valid. Use {@link
118      * #writeEntry(String, Integer, boolean)} for integer values that may not be present.
119      *
120      * @param key   the keyword to write
121      * @param value the value to write
122      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored.
123      * @throws IOException if an I/O error occurs.
124      * @see #writeEntry(String, Integer, boolean)
125      */
126     void writeEntry(String key, int value, boolean mandatory) throws IOException;
127 
128     /** Write a single key/value entry.
129      * @param key   the keyword to write
130      * @param value the value to write
131      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
132      * @throws IOException if an I/O error occurs.
133      */
134     default void writeEntry(String key, Integer value, boolean mandatory) throws IOException {
135         writeEntry(key, value == null ? null : value.toString(), null, mandatory);
136     }
137 
138     /** Write a single key/value entry.
139      * @param key   the keyword to write
140      * @param value the value to write (in SI units)
141      * @param unit output unit
142      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
143      * @throws IOException if an I/O error occurs.
144      */
145     void writeEntry(String key, double value, Unit unit, boolean mandatory) throws IOException;
146 
147     /** Write a single key/value entry.
148      * @param key   the keyword to write
149      * @param value the value to write (in SI units)
150      * @param unit output unit
151      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
152      * @throws IOException if an I/O error occurs.
153      */
154     void writeEntry(String key, Double value, Unit unit, boolean mandatory) throws IOException;
155 
156     /** Finish current line.
157      * @throws IOException if an I/O error occurs.
158      */
159     void newLine() throws IOException;
160 
161     /** Write raw data.
162      * @param data raw data to write
163      * @throws IOException if an I/O error occurs.
164      */
165     void writeRawData(char data) throws IOException;
166 
167     /** Write raw data.
168      * @param data raw data to write
169      * @throws IOException if an I/O error occurs.
170      */
171     void writeRawData(CharSequence data) throws IOException;
172 
173     /** Enter into a new section.
174      * @param name section name
175      * @throws IOException if an I/O error occurs.
176      */
177     void enterSection(String name) throws IOException;
178 
179     /** Exit last section.
180      * @return section name
181      * @throws IOException if an I/O error occurs.
182      */
183     String exitSection() throws IOException;
184 
185     /** Close the generator.
186      * @throws IOException if an I/O error occurs.
187      */
188     void close() throws IOException;
189 
190     /** Convert a date to string value with high precision.
191      * @param converter converter for dates
192      * @param date date to write
193      * @return date as a string (may be either a relative date or a calendar date)
194      */
195     String dateToString(TimeConverter converter, AbsoluteDate date);
196 
197     /** Convert a date to calendar string value with high precision.
198      * @param converter converter for dates
199      * @param date date to write
200      * @return date as a calendar string
201      * @since 12.0
202      */
203     String dateToCalendarString(TimeConverter converter, AbsoluteDate date);
204 
205     /** Convert a date to string value with high precision.
206      * @param year year
207      * @param month month
208      * @param day day
209      * @param hour hour
210      * @param minute minute
211      * @param seconds seconds
212      * @return date as a string
213      */
214     String dateToString(int year, int month, int day, int hour, int minute, double seconds);
215 
216     /** Convert a double to string value with high precision.
217      * <p>
218      * We don't want to loose internal accuracy when writing doubles
219      * but we also don't want to have ugly representations like STEP = 1.25000000000000000
220      * so we try a few simple formats first and fall back to scientific notation
221      * if it doesn't work.
222      * </p>
223      * @param value value to format
224      * @return formatted value, with all original value accuracy preserved, or null
225      * if value is null or {@code Double.NaN}
226      */
227     String doubleToString(double value);
228 
229     /** Convert a list of units to a bracketed string.
230      * @param units lists to output (may be null or empty)
231      * @return bracketed string (null if units list is null or empty)
232      */
233     String unitsListToString(List<Unit> units);
234 
235     /** Convert a SI unit name to a CCSDS name.
236      * @param siName si unit name
237      * @return CCSDS name for the unit
238      */
239     String siToCcsdsName(String siName);
240 
241 }