Generator.java

  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;

  19. import java.io.IOException;
  20. import java.util.List;

  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;

  28. /** Generation interface for CCSDS messages.
  29.  * @author Luc Maisonobe
  30.  * @since 11.0
  31.  */
  32. public interface Generator extends AutoCloseable {

  34.     /** Get the name of the output (for error messages).
  35.      * @return name of the output
  36.      */
  37.     String getOutputName();

  39.     /** Get the generated file format.
  40.      * @return generated file format
  41.      */
  42.     FileFormat getFormat();

  44.     /**
  45.      *  Used to format dates and doubles to string.
  46.      * @return formatter
  47.      */
  48.     Formatter getFormatter();

  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;

  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;

  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;

  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;

  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;

  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;

  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;

  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;

  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;

  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.     }

  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;

  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;

  156.     /** Finish current line.
  157.      * @throws IOException if an I/O error occurs.
  158.      */
  159.     void newLine() throws IOException;

  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;

  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;

  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;

  179.     /** Exit last section.
  180.      * @return section name
  181.      * @throws IOException if an I/O error occurs.
  182.      */
  183.     String exitSection() throws IOException;

  185.     /** Close the generator.
  186.      * @throws IOException if an I/O error occurs.
  187.      */
  188.     void close() throws IOException;

  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);

  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);

  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);

  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);

  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);

  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);

  241. }
Created with JaCoCo 0.8.12.202403310830