1   /* Copyright 2002-2024 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 forceCalendar if true, the date is forced to calendar format
93       * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
94       * @throws IOException if an I/O error occurs.
95       */
96      void writeEntry(String key, TimeConverter converter, AbsoluteDate date, boolean forceCalendar, boolean mandatory) throws IOException;
97  
98      /** Write a single key/value entry.
99       * @param key   the keyword to write
100      * @param value the value to write
101      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
102      * @throws IOException if an I/O error occurs.
103      */
104     void writeEntry(String key, char value, boolean mandatory) throws IOException;
105 
106     /** Write a single key/value entry.
107      * @param key   the keyword to write
108      * @param value the value to write
109      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
110      * @throws IOException if an I/O error occurs.
111      */
112     void writeEntry(String key, int value, boolean mandatory) throws IOException;
113 
114     /** Write a single key/value entry.
115      * @param key   the keyword to write
116      * @param value the value to write (in SI units)
117      * @param unit output unit
118      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
119      * @throws IOException if an I/O error occurs.
120      */
121     void writeEntry(String key, double value, Unit unit, boolean mandatory) throws IOException;
122 
123     /** Write a single key/value entry.
124      * @param key   the keyword to write
125      * @param value the value to write (in SI units)
126      * @param unit output unit
127      * @param mandatory if true, null values triggers exception, otherwise they are silently ignored
128      * @throws IOException if an I/O error occurs.
129      */
130     void writeEntry(String key, Double value, Unit unit, boolean mandatory) throws IOException;
131 
132     /** Finish current line.
133      * @throws IOException if an I/O error occurs.
134      */
135     void newLine() throws IOException;
136 
137     /** Write raw data.
138      * @param data raw data to write
139      * @throws IOException if an I/O error occurs.
140      */
141     void writeRawData(char data) throws IOException;
142 
143     /** Write raw data.
144      * @param data raw data to write
145      * @throws IOException if an I/O error occurs.
146      */
147     void writeRawData(CharSequence data) throws IOException;
148 
149     /** Enter into a new section.
150      * @param name section name
151      * @throws IOException if an I/O error occurs.
152      */
153     void enterSection(String name) throws IOException;
154 
155     /** Exit last section.
156      * @return section name
157      * @throws IOException if an I/O error occurs.
158      */
159     String exitSection() throws IOException;
160 
161     /** Close the generator.
162      * @throws IOException if an I/O error occurs.
163      */
164     void close() throws IOException;
165 
166     /** Convert a date to string value with high precision.
167      * @param converter converter for dates
168      * @param date date to write
169      * @return date as a string (may be either a relative date or a calendar date)
170      */
171     String dateToString(TimeConverter converter, AbsoluteDate date);
172 
173     /** Convert a date to calendar string value with high precision.
174      * @param converter converter for dates
175      * @param date date to write
176      * @return date as a calendar string
177      * @since 12.0
178      */
179     String dateToCalendarString(TimeConverter converter, AbsoluteDate date);
180 
181     /** Convert a date to string value with high precision.
182      * @param year year
183      * @param month month
184      * @param day day
185      * @param hour hour
186      * @param minute minute
187      * @param seconds seconds
188      * @return date as a string
189      */
190     String dateToString(int year, int month, int day, int hour, int minute, double seconds);
191 
192     /** Convert a double to string value with high precision.
193      * <p>
194      * We don't want to loose internal accuracy when writing doubles
195      * but we also don't want to have ugly representations like STEP = 1.25000000000000000
196      * so we try a few simple formats first and fall back to scientific notation
197      * if it doesn't work.
198      * </p>
199      * @param value value to format
200      * @return formatted value, with all original value accuracy preserved, or null
201      * if value is null or {@code Double.NaN}
202      */
203     String doubleToString(double value);
204 
205     /** Convert a list of units to a bracketed string.
206      * @param units lists to output (may be null or empty)
207      * @return bracketed string (null if units list is null or empty)
208      */
209     String unitsListToString(List<Unit> units);
210 
211     /** Convert a SI unit name to a CCSDS name.
212      * @param siName si unit name
213      * @return CCSDS name for the unit
214      */
215     String siToCcsdsName(String siName);
216 
217 }