ParameterDriversList.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.utils;

  19. import java.util.ArrayList;
  20. import java.util.Collections;
  21. import java.util.Comparator;
  22. import java.util.Iterator;
  23. import java.util.List;

  25. import org.orekit.time.AbsoluteDate;
  26. import org.orekit.utils.TimeSpanMap.Span;


  29. /** Class managing several {@link ParameterDriver parameter drivers},
  30.  * taking care of duplicated names.
  31.  * <p>
  32.  * Once parameter drivers sharing the same name have been added to
  33.  * an instance of this class, they are permanently bound together and
  34.  * also bound to the {@link #getDrivers() delegating driver} that
  35.  * manages them. This means that if drivers {@code d1}, {@code d2}...
  36.  * {@code dn} are added to the list and both correspond to parameter
  37.  * name "P", then {@link #getDrivers()} will return a list containing
  38.  * a delegating driver {@code delegateD} for the same name "P".
  39.  * Afterwards, whenever either {@link ParameterDriver#setValue(double)}
  40.  * or {@link ParameterDriver#setReferenceDate(AbsoluteDate)} is called
  41.  * on any of the {@code n+1} instances {@code d1}, {@code d2}... {@code dn}
  42.  * or {@code delegateD}, the call will be automatically forwarded to the
  43.  * {@code n} remaining instances, hence ensuring they remain consistent
  44.  * with each other.
  45.  * </p>
  46.  * @author Luc Maisonobe
  47.  * @author Mélina Vanel
  48.  * @since 8.0
  49.  */
  50. public class ParameterDriversList {

  52.     /** Managed drivers. */
  53.     private final List<DelegatingDriver> delegating;

  55.     /** Creates an empty list.
  56.      */
  57.     public ParameterDriversList() {
  58.         this.delegating = new ArrayList<>();
  59.     }

  61.     /** Add a driver.
  62.      * <p>
  63.      * If the driver is already present, it will not be added.
  64.      * If another driver managing the same parameter is present,
  65.      * both drivers will be managed together, existing drivers
  66.      * being set to the value of the last driver added (i.e.
  67.      * each addition overrides the parameter value).
  68.      * </p>
  69.      * <p>
  70.      * Warning if a driver is added and a driver with the same name
  71.      * was already added before, they should have the same validity
  72.      * periods to avoid surprises. Whatever, all driver having
  73.      * same name will have their valueSpanMap, nameSpanMap and validity period
  74.      * overwritten with the last driver added attributes.
  75.      * </p>
  76.      * @param driver driver to add
  77.      */
  78.     public void add(final ParameterDriver driver) {

  80.         final DelegatingDriver existingHere = findByName(driver.getName());
  81.         final DelegatingDriver alreadyBound = getAssociatedDelegatingDriver(driver);

  83.         if (existingHere != null) {
  84.             if (alreadyBound != null) {
  85.                 // merge the two delegating drivers
  86.                 existingHere.merge(alreadyBound);
  87.             } else {
  88.                 // this is a new driver for an already managed parameter
  89.                 existingHere.add(driver);
  90.             }
  91.         } else {
  92.             if (alreadyBound != null) {
  93.                 // the driver is new here, but already bound to other drivers in other lists
  94.                 delegating.add(alreadyBound);
  95.                 alreadyBound.addOwner(this);
  96.             } else {
  97.                 // this is the first driver we have for this parameter name
  98.                 delegating.add(new DelegatingDriver(this, driver));
  99.             }
  100.         }

  102.     }

  104.     /** Get a {@link DelegatingDriver delegating driver} bound to a driver.
  105.      * @param driver driver to check
  106.      * @return a {@link DelegatingDriver delegating driver} bound to a driver, or
  107.      * null if this driver is not associated with any {@link DelegatingDriver delegating driver}
  108.      * @since 9.1
  109.      */
  110.     private DelegatingDriver getAssociatedDelegatingDriver(final ParameterDriver driver) {
  111.         for (final ParameterObserver observer : driver.getObservers()) {
  112.             if (observer instanceof ChangesForwarder) {
  113.                 return ((ChangesForwarder) observer).getDelegatingDriver();
  114.             }
  115.         }
  116.         return null;
  117.     }

  119.     /** Replace a {@link DelegatingDriver delegating driver}.
  120.      * @param oldDelegating delegating driver to replace
  121.      * @param newDelegating new delegating driver to use
  122.      * @since 10.1
  123.      */
  124.     private void replaceDelegating(final DelegatingDriver oldDelegating, final DelegatingDriver newDelegating) {
  125.         for (int i = 0; i < delegating.size(); ++i) {
  126.             if (delegating.get(i) == oldDelegating) {
  127.                 delegating.set(i, newDelegating);
  128.             }
  129.         }
  130.     }

  132.     /** Find  a {@link DelegatingDriver delegating driver} by name.
  133.      * @param name name to check
  134.      * @return a {@link DelegatingDriver delegating driver} managing this parameter name
  135.      * @since 9.1
  136.      */
  137.     public DelegatingDriver findByName(final String name) {
  138.         for (final DelegatingDriver d : delegating) {
  139.             if (d.getName().equals(name)) {
  140.                 return d;
  141.             }
  142.         }
  143.         return null;
  144.     }

  146.     /** Find  a {@link DelegatingDriver delegating driver} by name.
  147.      * @param name name to check
  148.      * @return a {@link DelegatingDriver delegating driver} managing this parameter name
  149.      * @since 9.1
  150.      */
  151.     public String findDelegatingSpanNameBySpanName(final String name) {
  152.         for (final DelegatingDriver d : delegating) {
  153.             for (Span<String> span = d.getNamesSpanMap().getFirstSpan(); span != null; span = span.next()) {
  154.                 if (span.getData().equals(name)) {
  155.                     return span.getData();
  156.                 }
  157.             }
  158.         }
  159.         return null;
  160.     }


  163.     /** Sort the parameters lexicographically.
  164.      */
  165.     public void sort() {
  166.         delegating.sort(Comparator.comparing(ParameterDriver::getName));
  167.     }

  169.     /** Filter parameters to keep only one type of selection status.
  170.      * @param selected if true, only {@link ParameterDriver#isSelected()
  171.      * selected} parameters will be kept, the other ones will be removed
  172.      */
  173.     public void filter(final boolean selected) {
  174.         for (final Iterator<DelegatingDriver> iterator = delegating.iterator(); iterator.hasNext();) {
  175.             final DelegatingDriver delegatingDriver = iterator.next();
  176.             if (delegatingDriver.isSelected() != selected) {
  177.                 iterator.remove();
  178.                 delegatingDriver.removeOwner(this);
  179.             }
  180.         }
  181.     }

  183.     /** Get the number of parameters with different names.
  184.      * @return number of parameters with different names
  185.      */
  186.     public int getNbParams() {
  187.         return delegating.size();
  188.     }

  190.     /** Get the number of values to estimate for parameters with different names.
  191.      * @return number of values to estimate for parameters with different names
  192.      */
  193.     public int getNbValuesToEstimate() {
  194.         int nbValuesToEstimate = 0;
  195.         for (DelegatingDriver driver : delegating) {
  196.             nbValuesToEstimate += driver.getNbOfValues();
  197.         }
  198.         return nbValuesToEstimate;
  199.     }

  201.     /** Get delegating drivers for all parameters.
  202.      * <p>
  203.      * The delegating drivers are <em>not</em> the same as
  204.      * the drivers added to the list, but they delegate to them.
  205.      * </p>
  206.      * <p>
  207.      * All delegating drivers manage parameters with different names.
  208.      * </p>
  209.      * @return unmodifiable view of the list of delegating drivers
  210.      */
  211.     public List<DelegatingDriver> getDrivers() {
  212.         return Collections.unmodifiableList(delegating);
  213.     }

  215.     /** Specialized driver delegating to several other managing
  216.      * the same parameter name.
  217.      */
  218.     public static class DelegatingDriver extends ParameterDriver {

  220.         /** Lists owning this delegating driver. */
  221.         private final List<ParameterDriversList> owners;

  223.         /** Observer for propagating changes between all drivers. */
  224.         private ChangesForwarder forwarder;

  226.         /** Simple constructor.
  227.          * @param owner list owning this delegating driver
  228.          * @param driver first driver in the series
  229.          */
  230.         DelegatingDriver(final ParameterDriversList owner, final ParameterDriver driver) {
  231.             super(driver.getName(), driver.getNamesSpanMap(),
  232.                   driver.getValueSpanMap(), driver.getReferenceValue(),
  233.                   driver.getScale(), driver.getMinValue(), driver.getMaxValue());

  235.             owners = new ArrayList<>();
  236.             addOwner(owner);

  238.             setValueSpanMap(driver);
  239.             setReferenceDate(driver.getReferenceDate());
  240.             setSelected(driver.isSelected());

  242.             // set up a change forwarder observing both the raw driver and the delegating driver
  243.             this.forwarder = new ChangesForwarder(this, driver);
  244.             addObserver(forwarder);
  245.             driver.addObserver(forwarder);

  247.         }

  249.         /** Add an owner for this delegating driver.
  250.          * @param owner owner to add
  251.          */
  252.         void addOwner(final ParameterDriversList owner) {
  253.             owners.add(owner);
  254.         }

  256.         /** Remove one owner of this driver.
  257.          * @param owner owner to remove delegating driver from
  258.          * @since 10.1
  259.          */
  260.         private void removeOwner(final ParameterDriversList owner) {
  261.             for (final Iterator<ParameterDriversList> iterator = owners.iterator(); iterator.hasNext();) {
  262.                 if (iterator.next() == owner) {
  263.                     iterator.remove();
  264.                 }
  265.             }
  266.         }

  268.         /** Add a driver. Warning, by doing this operation
  269.          * all the delegated drivers present in the parameterDriverList
  270.          * will be overwritten with the attributes of the driver given
  271.          * in argument.
  272.          * <p>
  273.          * </p>
  274.          * Warning if a driver is added and a driver with the same name
  275.          * was already added before, they should have the same validity
  276.          * Period (that is to say that the {@link
  277.          * ParameterDriver#addSpans(AbsoluteDate, AbsoluteDate, double)}
  278.          * and {@link ParameterDriver#addSpanAtDate(AbsoluteDate)} methods
  279.          * should have been called with the same arguments for all drivers
  280.          * having the same name) to avoid surprises. Whatever, all driver having
  281.          * same name will have their valueSpanMap, nameSpanMap and validity period
  282.          * overwritten with the last driver added attributes.
  283.          * @param driver driver to add
  284.          */
  285.         private void add(final ParameterDriver driver) {

  287.             setValueSpanMap(driver);
  288.             setReferenceDate(driver.getReferenceDate());

  290.             // if any of the drivers is selected, all must be selected
  291.             if (isSelected()) {
  292.                 driver.setSelected(true);
  293.             } else {
  294.                 setSelected(driver.isSelected());
  295.             }

  297.             driver.addObserver(forwarder);
  298.             forwarder.add(driver);

  300.         }

  302.         /** Merge another instance.
  303.          * <p>
  304.          * After merging, the other instance is merely empty and preserved
  305.          * only as a child of the current instance. Changes are therefore
  306.          * still forwarded to it, but it is itself not responsible anymore
  307.          * for forwarding change.
  308.          * <p>
  309.          * </p>
  310.          * Warning if a driver is added and a driver with the same name
  311.          * was already added before, they should have the same validity
  312.          * periods (that is to say that the {@link
  313.          * ParameterDriver#addSpans(AbsoluteDate, AbsoluteDate, double)}
  314.          * and {@link ParameterDriver#addSpanAtDate(AbsoluteDate)} methods
  315.          * should have been called with same arguments for all drivers
  316.          * having the same name) to avoid surprises. Whatever, all driver having
  317.          * same name will have their valueSpanMap, nameSpanMap and validity period
  318.          * overwritten with the last driver added attributes.
  319.          * </p>
  320.          * @param other instance to merge
  321.          */
  322.         private void merge(final DelegatingDriver other) {

  324.             if (other.forwarder == forwarder) {
  325.                 // we are attempting to merge an instance with either itself
  326.                 // or an already embedded one, just ignore the request
  327.                 return;
  328.             }

  330.             // synchronize parameter
  331.             setValueSpanMap(other);
  332.             //setValue(other.getValue());
  333.             setReferenceDate(other.getReferenceDate());
  334.             if (isSelected()) {
  335.                 other.setSelected(true);
  336.             } else {
  337.                 setSelected(other.isSelected());
  338.             }

  340.             // move around drivers
  341.             for (final ParameterDriver otherDriver : other.forwarder.getDrivers()) {
  342.                 // as drivers are added one at a time and always refer back to a single
  343.                 // DelegatingDriver (through the ChangesForwarder), they cannot be
  344.                 // referenced by two different DelegatingDriver. We can blindly move
  345.                 // around all drivers, there cannot be any duplicates
  346.                 forwarder.add(otherDriver);
  347.                 otherDriver.replaceObserver(other.forwarder, forwarder);
  348.             }

  350.             // forwarding is now delegated to current instance
  351.             other.replaceObserver(other.forwarder, forwarder);
  352.             other.forwarder = forwarder;

  354.             // replace merged instance with current instance in former owners
  355.             for (final ParameterDriversList otherOwner : other.owners) {
  356.                 owners.add(otherOwner);
  357.                 otherOwner.replaceDelegating(other, this);
  358.             }

  360.         }

  362.         /** Get the raw drivers to which this one delegates.
  363.          * <p>
  364.          * These raw drivers all manage the same parameter name.
  365.          * </p>
  366.          * @return raw drivers to which this one delegates
  367.          */
  368.         public List<ParameterDriver> getRawDrivers() {
  369.             return Collections.unmodifiableList(forwarder.getDrivers());
  370.         }

  372.     }

  374.     /** Local observer for propagating changes, avoiding infinite recursion. */
  375.     private static class ChangesForwarder implements ParameterObserver {

  377.         /** DelegatingDriver we are associated with. */
  378.         private final DelegatingDriver delegating;

  380.         /** Drivers synchronized together by the instance. */
  381.         private final List<ParameterDriver> drivers;

  383.         /** Root of the current update chain. */
  384.         private ParameterDriver root;

  386.         /** Depth of the current update chain. */
  387.         private int depth;

  389.         /** Simple constructor.
  390.          * @param delegating delegatingDriver we are associated with
  391.          * @param driver first driver in the series
  392.          */
  393.         ChangesForwarder(final DelegatingDriver delegating, final ParameterDriver driver) {
  394.             this.delegating = delegating;
  395.             this.drivers    = new ArrayList<>();
  396.             drivers.add(driver);
  397.         }

  399.         /** Get the {@link DelegatingDriver} associated with this instance.
  400.          * @return {@link DelegatingDriver} associated with this instance
  401.          * @since 9.1
  402.          */
  403.         DelegatingDriver getDelegatingDriver() {
  404.             return delegating;
  405.         }

  407.         /** Add a driver to the list synchronized together by the instance.
  408.          * @param driver driver to add
  409.          * @since 10.1
  410.          */
  411.         void add(final ParameterDriver driver) {
  412.             drivers.add(driver);
  413.         }

  415.         /** Get the drivers synchronized together by the instance.
  416.          * @return drivers synchronized together by the instance.
  417.          * @since 10.1
  418.          */
  419.         public List<ParameterDriver> getDrivers() {
  420.             return drivers;
  421.         }

  423.         /** {@inheritDoc} */
  424.         @Override
  425.         public void valueSpanMapChanged(final TimeSpanMap<Double> previousValueSpanMap, final ParameterDriver driver) {
  426.             updateAll(driver, d -> d.setValueSpanMap(driver));
  427.         }

  429.         /** {@inheritDoc} */
  430.         @Override
  431.         public void valueChanged(final double previousValue, final ParameterDriver driver, final AbsoluteDate date) {
  432.             updateAll(driver, d -> d.setValue(driver.getValue(date), date));
  433.         }

  435.         /** {@inheritDoc} */
  436.         @Override
  437.         public void referenceDateChanged(final AbsoluteDate previousReferenceDate, final ParameterDriver driver) {
  438.             updateAll(driver, d -> d.setReferenceDate(driver.getReferenceDate()));
  439.         }

  441.         /** {@inheritDoc} */
  442.         @Override
  443.         public void nameChanged(final String previousName, final ParameterDriver driver) {
  444.             updateAll(driver, d -> d.setName(driver.getName()));
  445.         }

  447.         /** {@inheritDoc} */
  448.         @Override
  449.         public void selectionChanged(final boolean previousSelection, final ParameterDriver driver) {
  450.             updateAll(driver, d -> d.setSelected(driver.isSelected()));
  451.         }

  453.         /** {@inheritDoc} */
  454.         @Override
  455.         public void estimationTypeChanged(final boolean previousSelection, final ParameterDriver driver) {
  456.             updateAll(driver, d -> d.setContinuousEstimation(driver.isContinuousEstimation()));
  457.         }

  459.         /** {@inheritDoc} */
  460.         @Override
  461.         public void referenceValueChanged(final double previousReferenceValue, final ParameterDriver driver) {
  462.             updateAll(driver, d -> d.setReferenceValue(driver.getReferenceValue()));
  463.         }

  465.         /** {@inheritDoc} */
  466.         @Override
  467.         public void minValueChanged(final double previousMinValue, final ParameterDriver driver) {
  468.             updateAll(driver, d -> d.setMinValue(driver.getMinValue()));
  469.         }

  471.         /** {@inheritDoc} */
  472.         @Override
  473.         public void maxValueChanged(final double previousMaxValue, final ParameterDriver driver) {
  474.             updateAll(driver, d -> d.setMaxValue(driver.getMaxValue()));
  475.         }

  477.         /** {@inheritDoc} */
  478.         @Override
  479.         public void scaleChanged(final double previousScale, final ParameterDriver driver) {
  480.             updateAll(driver, d -> d.setScale(driver.getScale()));
  481.         }

  483.         /** Update all bound parameters.
  484.          * @param driver driver triggering the update
  485.          * @param updater updater to use
  486.          */
  487.         private void updateAll(final ParameterDriver driver, final Updater updater) {

  489.             final boolean firstCall = depth++ == 0;
  490.             if (firstCall) {
  491.                 root = driver;
  492.             }

  494.             if (driver == getDelegatingDriver()) {
  495.                 // propagate change downwards, which will trigger recursive calls
  496.                 for (final ParameterDriver d : drivers) {
  497.                     if (d != root) {
  498.                         updater.update(d);
  499.                     }
  500.                 }
  501.             } else if (firstCall) {
  502.                 // first call started from an underlying driver, propagate change upwards
  503.                 updater.update(getDelegatingDriver());
  504.             }

  506.             if (--depth == 0) {
  507.                 // this is the end of the root call
  508.                 root = null;
  509.             }

  511.         }

  513.     }

  515.     /** Interface for updating parameters. */
  516.     @FunctionalInterface
  517.     private interface Updater {
  518.         /** Update a driver.
  519.          * @param driver driver to update
  520.          */
  521.         void update(ParameterDriver driver);
  522.     }

  524. }
Created with JaCoCo 0.8.12.202403310830