ParameterDriversList.java

  1. /* Copyright 2002-2022 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;


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

  50.     /** Managed drivers. */
  51.     private final List<DelegatingDriver> delegating;

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

  59.     /** Add a driver.
  60.      * <p>
  61.      * If the driver is already present, it will not be added.
  62.      * If another driver managing the same parameter is present,
  63.      * both drivers will be managed together, existing drivers
  64.      * being set to the value of the last driver added (i.e.
  65.      * each addition overrides the parameter value).
  66.      * </p>
  67.      * @param driver driver to add
  68.      */
  69.     public void add(final ParameterDriver driver) {

  71.         final DelegatingDriver existingHere = findByName(driver.getName());
  72.         final DelegatingDriver alreadyBound = getAssociatedDelegatingDriver(driver);

  74.         if (existingHere != null) {
  75.             if (alreadyBound != null) {
  76.                 // merge the two delegating drivers
  77.                 existingHere.merge(alreadyBound);
  78.             } else {
  79.                 // this is a new driver for an already managed parameter
  80.                 existingHere.add(driver);
  81.             }
  82.         } else {
  83.             if (alreadyBound != null) {
  84.                 // the driver is new here, but already bound to other drivers in other lists
  85.                 delegating.add(alreadyBound);
  86.                 alreadyBound.addOwner(this);
  87.             } else {
  88.                 // this is the first driver we have for this parameter name
  89.                 delegating.add(new DelegatingDriver(this, driver));
  90.             }
  91.         }

  93.     }

  95.     /** Get a {@link DelegatingDriver delegating driver} bound to a driver.
  96.      * @param driver driver to check
  97.      * @return a {@link DelegatingDriver delegating driver} bound to a driver, or
  98.      * null if this driver is not associated with any {@link DelegatingDriver delegating driver}
  99.      * @since 9.1
  100.      */
  101.     private DelegatingDriver getAssociatedDelegatingDriver(final ParameterDriver driver) {
  102.         for (final ParameterObserver observer : driver.getObservers()) {
  103.             if (observer instanceof ChangesForwarder) {
  104.                 return ((ChangesForwarder) observer).getDelegatingDriver();
  105.             }
  106.         }
  107.         return null;
  108.     }

  110.     /** Replace a {@link DelegatingDriver delegating driver}.
  111.      * @param oldDelegating delegating driver to replace
  112.      * @param newDelegating new delegating driver to use
  113.      * @since 10.1
  114.      */
  115.     private void replaceDelegating(final DelegatingDriver oldDelegating, final DelegatingDriver newDelegating) {
  116.         for (int i = 0; i < delegating.size(); ++i) {
  117.             if (delegating.get(i) == oldDelegating) {
  118.                 delegating.set(i, newDelegating);
  119.             }
  120.         }
  121.     }

  123.     /** Find  a {@link DelegatingDriver delegating driver} by name.
  124.      * @param name name to check
  125.      * @return a {@link DelegatingDriver delegating driver} managing this parameter name
  126.      * @since 9.1
  127.      */
  128.     public DelegatingDriver findByName(final String name) {
  129.         for (final DelegatingDriver d : delegating) {
  130.             if (d.getName().equals(name)) {
  131.                 return d;
  132.             }
  133.         }
  134.         return null;
  135.     }

  137.     /** Sort the parameters lexicographically.
  138.      */
  139.     public void sort() {
  140.         Collections.sort(delegating, new Comparator<DelegatingDriver>() {
  141.             /** {@inheritDoc} */
  142.             @Override
  143.             public int compare(final DelegatingDriver d1, final DelegatingDriver d2) {
  144.                 return d1.getName().compareTo(d2.getName());
  145.             }
  146.         });
  147.     }

  149.     /** Filter parameters to keep only one type of selection status.
  150.      * @param selected if true, only {@link ParameterDriver#isSelected()
  151.      * selected} parameters will be kept, the other ones will be removed
  152.      */
  153.     public void filter(final boolean selected) {
  154.         for (final Iterator<DelegatingDriver> iterator = delegating.iterator(); iterator.hasNext();) {
  155.             final DelegatingDriver delegatingDriver = iterator.next();
  156.             if (delegatingDriver.isSelected() != selected) {
  157.                 iterator.remove();
  158.                 delegatingDriver.removeOwner(this);
  159.             }
  160.         }
  161.     }

  163.     /** Get the number of parameters with different names.
  164.      * @return number of parameters with different names
  165.      */
  166.     public int getNbParams() {
  167.         return delegating.size();
  168.     }

  170.     /** Get delegating drivers for all parameters.
  171.      * <p>
  172.      * The delegating drivers are <em>not</em> the same as
  173.      * the drivers added to the list, but they delegate to them.
  174.      * </p>
  175.      * <p>
  176.      * All delegating drivers manage parameters with different names.
  177.      * </p>
  178.      * @return unmodifiable view of the list of delegating drivers
  179.      */
  180.     public List<DelegatingDriver> getDrivers() {
  181.         return Collections.unmodifiableList(delegating);
  182.     }

  184.     /** Specialized driver delegating to several other managing
  185.      * the same parameter name.
  186.      */
  187.     public static class DelegatingDriver extends ParameterDriver {

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

  192.         /** Observer for propagating changes between all drivers. */
  193.         private ChangesForwarder forwarder;

  195.         /** Simple constructor.
  196.          * @param owner list owning this delegating driver
  197.          * @param driver first driver in the series
  198.          */
  199.         DelegatingDriver(final ParameterDriversList owner, final ParameterDriver driver) {
  200.             super(driver.getName(), driver.getReferenceValue(),
  201.                   driver.getScale(), driver.getMinValue(), driver.getMaxValue());

  203.             owners = new ArrayList<>();
  204.             addOwner(owner);

  206.             setValue(driver.getValue());
  207.             setReferenceDate(driver.getReferenceDate());
  208.             setSelected(driver.isSelected());

  210.             // set up a change forwarder observing both the raw driver and the delegating driver
  211.             this.forwarder = new ChangesForwarder(this, driver);
  212.             addObserver(forwarder);
  213.             driver.addObserver(forwarder);

  215.         }

  217.         /** Add an owner for this delegating driver.
  218.          * @param owner owner to add
  219.          */
  220.         void addOwner(final ParameterDriversList owner) {
  221.             owners.add(owner);
  222.         }

  224.         /** Remove one owner of this driver.
  225.          * @param owner owner to remove delegating driver from
  226.          * @since 10.1
  227.          */
  228.         private void removeOwner(final ParameterDriversList owner) {
  229.             for (final Iterator<ParameterDriversList> iterator = owners.iterator(); iterator.hasNext();) {
  230.                 if (iterator.next() == owner) {
  231.                     iterator.remove();
  232.                 }
  233.             }
  234.         }

  236.         /** Add a driver.
  237.          * @param driver driver to add
  238.          */
  239.         private void add(final ParameterDriver driver) {

  241.             setValue(driver.getValue());
  242.             setReferenceDate(driver.getReferenceDate());

  244.             // if any of the drivers is selected, all must be selected
  245.             if (isSelected()) {
  246.                 driver.setSelected(true);
  247.             } else {
  248.                 setSelected(driver.isSelected());
  249.             }

  251.             driver.addObserver(forwarder);
  252.             forwarder.add(driver);

  254.         }

  256.         /** Merge another instance.
  257.          * <p>
  258.          * After merging, the other instance is merely empty and preserved
  259.          * only as a child of the current instance. Changes are therefore
  260.          * still forwarded to it, but it is itself not responsible anymore
  261.          * for forwarding change.
  262.          * </p>
  263.          * @param other instance to merge
  264.          */
  265.         private void merge(final DelegatingDriver other) {

  267.             if (other.forwarder == forwarder) {
  268.                 // we are attempting to merge an instance with either itself
  269.                 // or an already embedded one, just ignore the request
  270.                 return;
  271.             }

  273.             // synchronize parameter
  274.             setValue(other.getValue());
  275.             setReferenceDate(other.getReferenceDate());
  276.             if (isSelected()) {
  277.                 other.setSelected(true);
  278.             } else {
  279.                 setSelected(other.isSelected());
  280.             }

  282.             // move around drivers
  283.             for (final ParameterDriver otherDriver : other.forwarder.getDrivers()) {
  284.                 // as drivers are added one at a time and always refer back to a single
  285.                 // DelegatingDriver (through the ChangesForwarder), they cannot be
  286.                 // referenced by two different DelegatingDriver. We can blindly move
  287.                 // around all drivers, there cannot be any duplicates
  288.                 forwarder.add(otherDriver);
  289.                 otherDriver.replaceObserver(other.forwarder, forwarder);
  290.             }

  292.             // forwarding is now delegated to current instance
  293.             other.replaceObserver(other.forwarder, forwarder);
  294.             other.forwarder = forwarder;

  296.             // replace merged instance with current instance in former owners
  297.             for (final ParameterDriversList otherOwner : other.owners) {
  298.                 owners.add(otherOwner);
  299.                 otherOwner.replaceDelegating(other, this);
  300.             }

  302.         }

  304.         /** Get the raw drivers to which this one delegates.
  305.          * <p>
  306.          * These raw drivers all manage the same parameter name.
  307.          * </p>
  308.          * @return raw drivers to which this one delegates
  309.          */
  310.         public List<ParameterDriver> getRawDrivers() {
  311.             return Collections.unmodifiableList(forwarder.getDrivers());
  312.         }

  314.     }

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

  319.         /** DelegatingDriver we are associated with. */
  320.         private final DelegatingDriver delegating;

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

  325.         /** Root of the current update chain. */
  326.         private ParameterDriver root;

  328.         /** Depth of the current update chain. */
  329.         private int depth;

  331.         /** Simple constructor.
  332.          * @param delegating delegatingDriver we are associated with
  333.          * @param driver first driver in the series
  334.          */
  335.         ChangesForwarder(final DelegatingDriver delegating, final ParameterDriver driver) {
  336.             this.delegating = delegating;
  337.             this.drivers    = new ArrayList<>();
  338.             drivers.add(driver);
  339.         }

  341.         /** Get the {@link DelegatingDriver} associated with this instance.
  342.          * @return {@link DelegatingDriver} associated with this instance
  343.          * @since 9.1
  344.          */
  345.         DelegatingDriver getDelegatingDriver() {
  346.             return delegating;
  347.         }

  349.         /** Add a driver to the list synchronized together by the instance.
  350.          * @param driver driver to add
  351.          * @since 10.1
  352.          */
  353.         void add(final ParameterDriver driver) {
  354.             drivers.add(driver);
  355.         }

  357.         /** Get the drivers synchronized together by the instance.
  358.          * @return drivers synchronized together by the instance.
  359.          * @since 10.1
  360.          */
  361.         public List<ParameterDriver> getDrivers() {
  362.             return drivers;
  363.         }

  365.         /** {@inheritDoc} */
  366.         @Override
  367.         public void valueChanged(final double previousValue, final ParameterDriver driver) {
  368.             updateAll(driver, d -> d.setValue(driver.getValue()));
  369.         }

  371.         /** {@inheritDoc} */
  372.         @Override
  373.         public void referenceDateChanged(final AbsoluteDate previousReferenceDate, final ParameterDriver driver) {
  374.             updateAll(driver, d -> d.setReferenceDate(driver.getReferenceDate()));
  375.         }

  377.         /** {@inheritDoc} */
  378.         @Override
  379.         public void nameChanged(final String previousName, final ParameterDriver driver) {
  380.             updateAll(driver, d -> d.setName(driver.getName()));
  381.         }

  383.         /** {@inheritDoc} */
  384.         @Override
  385.         public void selectionChanged(final boolean previousSelection, final ParameterDriver driver) {
  386.             updateAll(driver, d -> d.setSelected(driver.isSelected()));
  387.         }

  389.         /** {@inheritDoc} */
  390.         @Override
  391.         public void referenceValueChanged(final double previousReferenceValue, final ParameterDriver driver) {
  392.             updateAll(driver, d -> d.setReferenceValue(driver.getReferenceValue()));
  393.         }

  395.         /** {@inheritDoc} */
  396.         @Override
  397.         public void minValueChanged(final double previousMinValue, final ParameterDriver driver) {
  398.             updateAll(driver, d -> d.setMinValue(driver.getMinValue()));
  399.         }

  401.         /** {@inheritDoc} */
  402.         @Override
  403.         public void maxValueChanged(final double previousMaxValue, final ParameterDriver driver) {
  404.             updateAll(driver, d -> d.setMaxValue(driver.getMaxValue()));
  405.         }

  407.         /** {@inheritDoc} */
  408.         @Override
  409.         public void scaleChanged(final double previousScale, final ParameterDriver driver) {
  410.             updateAll(driver, d -> d.setScale(driver.getScale()));
  411.         }

  413.         /** Update all bound parameters.
  414.          * @param driver driver triggering the update
  415.          * @param updater updater to use
  416.          */
  417.         private void updateAll(final ParameterDriver driver, final Updater updater) {

  419.             final boolean firstCall = depth++ == 0;
  420.             if (firstCall) {
  421.                 root = driver;
  422.             }

  424.             if (driver == getDelegatingDriver()) {
  425.                 // propagate change downwards, which will trigger recursive calls
  426.                 for (final ParameterDriver d : drivers) {
  427.                     if (d != root) {
  428.                         updater.update(d);
  429.                     }
  430.                 }
  431.             } else if (firstCall) {
  432.                 // first call started from an underlying driver, propagate change upwards
  433.                 updater.update(getDelegatingDriver());
  434.             }

  436.             if (--depth == 0) {
  437.                 // this is the end of the root call
  438.                 root = null;
  439.             }

  441.         }

  443.     }

  445.     /** Interface for updating parameters. */
  446.     @FunctionalInterface
  447.     private interface Updater {
  448.         /** Update a driver.
  449.          * @param driver driver to update
  450.          */
  451.         void update(ParameterDriver driver);
  452.     }

  454. }
Created with JaCoCo 0.8.7.202105040129