Package org.orekit.files.ccsds.ndm

Class ParserBuilder

  • public class ParserBuilder
extends AbstractBuilder<ParserBuilder>
    Builder for all CCSDS Message files parsers.

    This builder can be used for building all CCSDS Messages parsers types. It is particularly useful in multi-threaded context as parsers cannot be shared between threads and thus several independent parsers must be built in this case.

    Since:
    11.0
    Author:
    Luc Maisonobe

    • Method Detail

      • create

        protected ParserBuilder create​(IERSConventions newConventions,
                               double newEquatorialRadius,
                               double newFlattening,
                               DataContext newDataContext,
                               AbsoluteDate newMissionReferenceDate,
                               RangeUnitsConverter newRangeUnitsConverter)
        Build an instance.
        Specified by:
        create in class AbstractBuilder<ParserBuilder>
        Parameters:
        newConventions - IERS Conventions
        newEquatorialRadius - central body equatorial radius
        newFlattening - central body flattening
        newDataContext - used to retrieve frames, time scales, etc.
        newMissionReferenceDate - reference date for Mission Elapsed Time or Mission Relative Time time systems
        newRangeUnitsConverter - converter for Range Units
        Returns:
        new instance

      • withSimpleEOP

        public ParserBuilder withSimpleEOP​(boolean newSimpleEOP)
        Set up flag for ignoring tidal effects when interpolating EOP.
        Parameters:
        newSimpleEOP - true if tidal effects are ignored when interpolating EOP
        Returns:
        a new builder with updated configuration (the instance is not changed)

      • isSimpleEOP

        public boolean isSimpleEOP()
        Check if tidal effects are ignored when interpolating EOP.
        Returns:
        true if tidal effects are ignored when interpolating EOP

      • withMu

        public ParserBuilder withMu​(double newMu)
        Set up the gravitational coefficient.
        Parameters:
        newMu - gravitational coefficient
        Returns:
        a new builder with updated configuration (the instance is not changed)

      • getMu

        public double getMu()
        Get the gravitational coefficient.
        Returns:
        gravitational coefficient

      • withDefaultMass

        public ParserBuilder withDefaultMass​(double newDefaultMass)
        Set up the default mass.

        The default mass is used only by OpmParser.

        Parameters:
        newDefaultMass - default mass
        Returns:
        a new builder with updated configuration (the instance is not changed)

      • getDefaultMass

        public double getDefaultMass()
        Get the default mass.
        Returns:
        default mass

      • withDefaultInterpolationDegree

        public ParserBuilder withDefaultInterpolationDegree​(int newDefaultInterpolationDegree)
        Set up the default interpolation degree.

        The default interpolation degree is used only by AemParser and OemParser.

        Parameters:
        newDefaultInterpolationDegree - default interpolation degree
        Returns:
        a new builder with updated configuration (the instance is not changed)

      • getDefaultInterpolationDegree

        public int getDefaultInterpolationDegree()
        Get the default interpolation degree.
        Returns:
        default interpolation degree

      • withParsedUnitsBehavior

        public ParserBuilder withParsedUnitsBehavior​(ParsedUnitsBehavior newParsedUnitsBehavior)
        Set up the behavior to adopt for handling parsed units.
        Parameters:
        newParsedUnitsBehavior - behavior to adopt for handling parsed units
        Returns:
        a new builder with updated configuration (the instance is not changed)

      • getParsedUnitsBehavior

        public ParsedUnitsBehavior getParsedUnitsBehavior()
        Get the behavior to adopt for handling parsed units.
        Returns:
        behavior to adopt for handling parsed units

      • withFilter

        public ParserBuilder withFilter​(Function<ParseToken,​List<ParseToken>> filter)
        Add a filter for parsed tokens.

        This filter allows to change parsed tokens. This method can be called several times, once for each filter to set up. The filters are always applied in the order they were set. There are several use cases for this feature.

        The first use case is to allow parsing malformed CCSDS messages with some known discrepancies that can be fixed. One real life example (the one that motivated the development of this feature) is OMM files in XML format that add an empty OBJECT_ID. This could be fixed by setting a filter as follows: 

        
 Omm omm = new ParserBuilder().
           withFilter(token -> {
                          if ("OBJECT_ID".equals(token.getName()) &&
                              (token.getRawContent() == null || token.getRawContent().isEmpty())) {
                              // replace null/empty entries with "unknown"
                              return Collections.singletonList(new ParseToken(token.getType(), token.getName(),
                                                                              "unknown", token.getUnits(),
                                                                              token.getLineNumber(), token.getFileName()));
                          } else {
                              return Collections.singletonList(token);
                          }
                     }).
           buildOmmParser().
           parseMessage(message);

        A second use case is to remove unwanted data. For example in order to remove all user-defined data one could use: 

        
 Omm omm = new ParserBuilder().
           withFilter(token -> {
                          if (token.getName().startsWith("USER_DEFINED")) {
                              return Collections.emptyList();
                          } else {
                              return Collections.singletonList(token);
                          }
                     }).
           buildOmmmParser().
           parseMessage(message);

        A third use case is to add data not originally present in the file. For example in order to add a generated ODM V3 message id to an ODM V2 message that lacks it, one could do: 

        
 final String myMessageId = ...; // this could be computed from a counter, or a SHA256 digest, or some metadata
 Omm omm = new ParserBuilder()
           withFilter(token -> {
                          if ("CCSDS_OMM_VERS".equals(token.getName())) {
                              // enforce ODM V3
                              return Collections.singletonList(new ParseToken(token.getType(), token.getName(),
                                                                              "3.0", token.getUnits(),
                                                                              token.getLineNumber(), token.getFileName()));
                          } else {
                              return Collections.singletonList(token);
                          }
                      }).
           withFilter(token -> {
                          if ("ORIGINATOR".equals(token.getName())) {
                              // add generated message ID after ORIGINATOR entry
                              return Arrays.asList(token,
                                                   new ParseToken(TokenType.ENTRY, "MESSAGE_ID",
                                                                  myMessageId, null,
                                                                  -1, token.getFileName()));
                          } else {
                              return Collections.singletonList(token);
                          }
                      }).
           buildOmmmParser().
           parseMessage(message);
        Parameters:
        filter - token filter to add
        Returns:
        a new builder with updated configuration (the instance is not changed)
        Since:
        12.0

      • getFilters

        public Function<ParseToken,​List<ParseToken>>[] getFilters()
        Get the filters to apply to parse tokens.
        Returns:
        filters to apply to parse tokens
        Since:
        12.0