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.parsing;
18  
19  import java.util.List;
20  import java.util.function.Function;
21  
22  import org.orekit.data.DataContext;
23  import org.orekit.files.ccsds.ndm.NdmConstituent;
24  import org.orekit.files.ccsds.ndm.ParsedUnitsBehavior;
25  import org.orekit.files.ccsds.section.Header;
26  import org.orekit.files.ccsds.utils.lexical.ParseToken;
27  import org.orekit.utils.IERSConventions;
28  
29  /** Parser for CCSDS messages.
30   * <p>
31   * Note than starting with Orekit 11.0, CCSDS message parsers are
32   * mutable objects that gather the data being parsed, until the
33   * message is complete and the {@link #parseMessage(org.orekit.data.DataSource)
34   * parseMessage} method has returned. This implies that parsers
35   * should <em>not</em> be used in a multi-thread context. The recommended
36   * way to use parsers is to either dedicate one parser for each message
37   * and drop it afterwards, or to use a single-thread loop.
38   * </p>
39   * @param <H> type of the header
40   * @param <T> type of the file
41   * @param <P> type of the parser
42   * @author Luc Maisonobe
43   * @since 11.0
44   */
45  public abstract class AbstractConstituentParser<H extends Header, T extends NdmConstituent<H, ?>, P extends AbstractConstituentParser<H, T, ?>>
46      extends AbstractMessageParser<T> {
47  
48      /** IERS Conventions. */
49      private final  IERSConventions conventions;
50  
51      /** Indicator for simple or accurate EOP interpolation. */
52      private final  boolean simpleEOP;
53  
54      /** Data context used for obtain frames and time scales. */
55      private final DataContext dataContext;
56  
57      /** Behavior adopted for units that have been parsed from a CCSDS message. */
58      private final ParsedUnitsBehavior parsedUnitsBehavior;
59  
60      /** Complete constructor.
61       * @param root root element for XML files
62       * @param formatVersionKey key for format version
63       * @param conventions IERS Conventions
64       * @param simpleEOP if true, tidal effects are ignored when interpolating EOP
65       * @param dataContext used to retrieve frames and time scales
66       * @param parsedUnitsBehavior behavior to adopt for handling parsed units
67       * @param filters filters to apply to parse tokens
68       * @since 12.0
69       */
70      protected AbstractConstituentParser(final String root,
71                                          final String formatVersionKey,
72                                          final IERSConventions conventions,
73                                          final boolean simpleEOP,
74                                          final DataContext dataContext,
75                                          final ParsedUnitsBehavior parsedUnitsBehavior,
76                                          final Function<ParseToken, List<ParseToken>>[] filters) {
77          super(root, formatVersionKey, filters);
78          this.conventions         = conventions;
79          this.simpleEOP           = simpleEOP;
80          this.dataContext         = dataContext;
81          this.parsedUnitsBehavior = parsedUnitsBehavior;
82      }
83  
84      /** Get the behavior to adopt for handling parsed units.
85       * @return behavior to adopt for handling parsed units
86       */
87      public ParsedUnitsBehavior getParsedUnitsBehavior() {
88          return parsedUnitsBehavior;
89      }
90  
91      /** Get IERS conventions.
92       * @return IERS conventions to use while parsing
93       */
94      public IERSConventions getConventions() {
95          return conventions;
96      }
97  
98      /** Get EOP interpolation method.
99       * @return true if tidal effects are ignored when interpolating EOP
100      */
101     public boolean isSimpleEOP() {
102         return simpleEOP;
103     }
104 
105     /** Get the data context used for getting frames, time scales, and celestial bodies.
106      * @return the data context.
107      */
108     public DataContext getDataContext() {
109         return dataContext;
110     }
111 
112     /** Get file header to fill.
113      * @return file header to fill
114      */
115     public abstract H getHeader();
116 
117     /** Prepare header for parsing.
118      * @return true if parser was able to perform the action
119      */
120     public abstract boolean prepareHeader();
121 
122     /** Acknowledge header parsing has started.
123      * @return true if parser was able to perform the action
124      */
125     public abstract boolean inHeader();
126 
127     /** Finalize header after parsing.
128      * @return true if parser was able to perform the action
129      */
130     public abstract boolean finalizeHeader();
131 
132     /** Prepare metadata for parsing.
133      * @return true if parser was able to perform the action
134      */
135     public abstract boolean prepareMetadata();
136 
137     /** Acknowledge metada parsing has started.
138      * @return true if parser was able to perform the action
139      */
140     public abstract boolean inMetadata();
141 
142     /** Finalize metadata after parsing.
143      * @return true if parser was able to perform the action
144      */
145     public abstract boolean finalizeMetadata();
146 
147     /** Prepare data for parsing.
148      * @return true if parser was able to perform the action
149      */
150     public abstract boolean prepareData();
151 
152     /** Acknowledge data parsing has started.
153      * @return true if parser was able to perform the action
154      */
155     public abstract boolean inData();
156 
157     /** Finalize data after parsing.
158      * @return true if parser was able to perform the action
159      */
160     public abstract boolean finalizeData();
161 
162 }