ParameterDriversList.java
/* Copyright 2002-2024 CS GROUP
* Licensed to CS GROUP (CS) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* CS licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.orekit.utils;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.Iterator;
import java.util.List;
import org.orekit.time.AbsoluteDate;
import org.orekit.utils.TimeSpanMap.Span;
/** Class managing several {@link ParameterDriver parameter drivers},
* taking care of duplicated names.
* <p>
* Once parameter drivers sharing the same name have been added to
* an instance of this class, they are permanently bound together and
* also bound to the {@link #getDrivers() delegating driver} that
* manages them. This means that if drivers {@code d1}, {@code d2}...
* {@code dn} are added to the list and both correspond to parameter
* name "P", then {@link #getDrivers()} will return a list containing
* a delegating driver {@code delegateD} for the same name "P".
* Afterwards, whenever either {@link ParameterDriver#setValue(double)}
* or {@link ParameterDriver#setReferenceDate(AbsoluteDate)} is called
* on any of the {@code n+1} instances {@code d1}, {@code d2}... {@code dn}
* or {@code delegateD}, the call will be automatically forwarded to the
* {@code n} remaining instances, hence ensuring they remain consistent
* with each other.
* </p>
* @author Luc Maisonobe
* @author Mélina Vanel
* @since 8.0
*/
public class ParameterDriversList {
/** Managed drivers. */
private final List<DelegatingDriver> delegating;
/** Creates an empty list.
*/
public ParameterDriversList() {
this.delegating = new ArrayList<>();
}
/** Add a driver.
* <p>
* If the driver is already present, it will not be added.
* If another driver managing the same parameter is present,
* both drivers will be managed together, existing drivers
* being set to the value of the last driver added (i.e.
* each addition overrides the parameter value).
* </p>
* <p>
* Warning if a driver is added and a driver with the same name
* was already added before, they should have the same validity
* Period to avoid surprises. Whatever, all driver having
* same name will have their valueSpanMap, nameSpanMap and validity period
* overwritten with the last driver added attributes.
* </p>
* @param driver driver to add
*/
public void add(final ParameterDriver driver) {
final DelegatingDriver existingHere = findByName(driver.getName());
final DelegatingDriver alreadyBound = getAssociatedDelegatingDriver(driver);
if (existingHere != null) {
if (alreadyBound != null) {
// merge the two delegating drivers
existingHere.merge(alreadyBound);
} else {
// this is a new driver for an already managed parameter
existingHere.add(driver);
}
} else {
if (alreadyBound != null) {
// the driver is new here, but already bound to other drivers in other lists
delegating.add(alreadyBound);
alreadyBound.addOwner(this);
} else {
// this is the first driver we have for this parameter name
delegating.add(new DelegatingDriver(this, driver));
}
}
}
/** Get a {@link DelegatingDriver delegating driver} bound to a driver.
* @param driver driver to check
* @return a {@link DelegatingDriver delegating driver} bound to a driver, or
* null if this driver is not associated with any {@link DelegatingDriver delegating driver}
* @since 9.1
*/
private DelegatingDriver getAssociatedDelegatingDriver(final ParameterDriver driver) {
for (final ParameterObserver observer : driver.getObservers()) {
if (observer instanceof ChangesForwarder) {
return ((ChangesForwarder) observer).getDelegatingDriver();
}
}
return null;
}
/** Replace a {@link DelegatingDriver delegating driver}.
* @param oldDelegating delegating driver to replace
* @param newDelegating new delegating driver to use
* @since 10.1
*/
private void replaceDelegating(final DelegatingDriver oldDelegating, final DelegatingDriver newDelegating) {
for (int i = 0; i < delegating.size(); ++i) {
if (delegating.get(i) == oldDelegating) {
delegating.set(i, newDelegating);
}
}
}
/** Find a {@link DelegatingDriver delegating driver} by name.
* @param name name to check
* @return a {@link DelegatingDriver delegating driver} managing this parameter name
* @since 9.1
*/
public DelegatingDriver findByName(final String name) {
for (final DelegatingDriver d : delegating) {
if (d.getName().equals(name)) {
return d;
}
}
return null;
}
/** Find a {@link DelegatingDriver delegating driver} by name.
* @param name name to check
* @return a {@link DelegatingDriver delegating driver} managing this parameter name
* @since 9.1
*/
public String findDelegatingSpanNameBySpanName(final String name) {
for (final DelegatingDriver d : delegating) {
for (Span<String> span = d.getNamesSpanMap().getFirstSpan(); span != null; span = span.next()) {
if (span.getData().equals(name)) {
return span.getData();
}
}
}
return null;
}
/** Sort the parameters lexicographically.
*/
public void sort() {
Collections.sort(delegating, new Comparator<DelegatingDriver>() {
/** {@inheritDoc} */
@Override
public int compare(final DelegatingDriver d1, final DelegatingDriver d2) {
return d1.getName().compareTo(d2.getName());
}
});
}
/** Filter parameters to keep only one type of selection status.
* @param selected if true, only {@link ParameterDriver#isSelected()
* selected} parameters will be kept, the other ones will be removed
*/
public void filter(final boolean selected) {
for (final Iterator<DelegatingDriver> iterator = delegating.iterator(); iterator.hasNext();) {
final DelegatingDriver delegatingDriver = iterator.next();
if (delegatingDriver.isSelected() != selected) {
iterator.remove();
delegatingDriver.removeOwner(this);
}
}
}
/** Get the number of parameters with different names.
* @return number of parameters with different names
*/
public int getNbParams() {
return delegating.size();
}
/** Get the number of values to estimate for parameters with different names.
* @return number of values to estimate for parameters with different names
*/
public int getNbValuesToEstimate() {
int nbValuesToEstimate = 0;
for (DelegatingDriver driver : delegating) {
nbValuesToEstimate += driver.getNbOfValues();
}
return nbValuesToEstimate;
}
/** Get delegating drivers for all parameters.
* <p>
* The delegating drivers are <em>not</em> the same as
* the drivers added to the list, but they delegate to them.
* </p>
* <p>
* All delegating drivers manage parameters with different names.
* </p>
* @return unmodifiable view of the list of delegating drivers
*/
public List<DelegatingDriver> getDrivers() {
return Collections.unmodifiableList(delegating);
}
/** Specialized driver delegating to several other managing
* the same parameter name.
*/
public static class DelegatingDriver extends ParameterDriver {
/** Lists owning this delegating driver. */
private final List<ParameterDriversList> owners;
/** Observer for propagating changes between all drivers. */
private ChangesForwarder forwarder;
/** Simple constructor.
* @param owner list owning this delegating driver
* @param driver first driver in the series
*/
DelegatingDriver(final ParameterDriversList owner, final ParameterDriver driver) {
super(driver.getName(), driver.getNamesSpanMap(),
driver.getValueSpanMap(), driver.getReferenceValue(),
driver.getScale(), driver.getMinValue(), driver.getMaxValue());
owners = new ArrayList<>();
addOwner(owner);
setValueSpanMap(driver);
setReferenceDate(driver.getReferenceDate());
setSelected(driver.isSelected());
// set up a change forwarder observing both the raw driver and the delegating driver
this.forwarder = new ChangesForwarder(this, driver);
addObserver(forwarder);
driver.addObserver(forwarder);
}
/** Add an owner for this delegating driver.
* @param owner owner to add
*/
void addOwner(final ParameterDriversList owner) {
owners.add(owner);
}
/** Remove one owner of this driver.
* @param owner owner to remove delegating driver from
* @since 10.1
*/
private void removeOwner(final ParameterDriversList owner) {
for (final Iterator<ParameterDriversList> iterator = owners.iterator(); iterator.hasNext();) {
if (iterator.next() == owner) {
iterator.remove();
}
}
}
/** Add a driver. Warning, by doing this operation
* all the delegated drivers present in the parameterDriverList
* will be overwritten with the attributes of the driver given
* in argument.
* <p>
* </p>
* Warning if a driver is added and a driver with the same name
* was already added before, they should have the same validity
* Period (that is to say that the {@link ParameterDriver#setPeriods}
* method should have been called with same arguments for all drivers
* having the same name) to avoid surprises. Whatever, all driver having
* same name will have their valueSpanMap, nameSpanMap and validity period
* overwritten with the last driver added attributes.
* @param driver driver to add
*/
private void add(final ParameterDriver driver) {
setValueSpanMap(driver);
setReferenceDate(driver.getReferenceDate());
// if any of the drivers is selected, all must be selected
if (isSelected()) {
driver.setSelected(true);
} else {
setSelected(driver.isSelected());
}
driver.addObserver(forwarder);
forwarder.add(driver);
}
/** Merge another instance.
* <p>
* After merging, the other instance is merely empty and preserved
* only as a child of the current instance. Changes are therefore
* still forwarded to it, but it is itself not responsible anymore
* for forwarding change.
* <p>
* </p>
* Warning if a driver is added and a driver with the same name
* was already added before, they should have the same validity
* Period (that is to say that the {@link ParameterDriver#setPeriods}
* method should have been called with same arguments for all drivers
* having the same name) to avoid surprises. Whatever, all driver having
* same name will have their valueSpanMap, nameSpanMap and validity period
* overwritten with the last driver added attributes.
* </p>
* @param other instance to merge
*/
private void merge(final DelegatingDriver other) {
if (other.forwarder == forwarder) {
// we are attempting to merge an instance with either itself
// or an already embedded one, just ignore the request
return;
}
// synchronize parameter
setValueSpanMap(other);
//setValue(other.getValue());
setReferenceDate(other.getReferenceDate());
if (isSelected()) {
other.setSelected(true);
} else {
setSelected(other.isSelected());
}
// move around drivers
for (final ParameterDriver otherDriver : other.forwarder.getDrivers()) {
// as drivers are added one at a time and always refer back to a single
// DelegatingDriver (through the ChangesForwarder), they cannot be
// referenced by two different DelegatingDriver. We can blindly move
// around all drivers, there cannot be any duplicates
forwarder.add(otherDriver);
otherDriver.replaceObserver(other.forwarder, forwarder);
}
// forwarding is now delegated to current instance
other.replaceObserver(other.forwarder, forwarder);
other.forwarder = forwarder;
// replace merged instance with current instance in former owners
for (final ParameterDriversList otherOwner : other.owners) {
owners.add(otherOwner);
otherOwner.replaceDelegating(other, this);
}
}
/** Get the raw drivers to which this one delegates.
* <p>
* These raw drivers all manage the same parameter name.
* </p>
* @return raw drivers to which this one delegates
*/
public List<ParameterDriver> getRawDrivers() {
return Collections.unmodifiableList(forwarder.getDrivers());
}
}
/** Local observer for propagating changes, avoiding infinite recursion. */
private static class ChangesForwarder implements ParameterObserver {
/** DelegatingDriver we are associated with. */
private final DelegatingDriver delegating;
/** Drivers synchronized together by the instance. */
private final List<ParameterDriver> drivers;
/** Root of the current update chain. */
private ParameterDriver root;
/** Depth of the current update chain. */
private int depth;
/** Simple constructor.
* @param delegating delegatingDriver we are associated with
* @param driver first driver in the series
*/
ChangesForwarder(final DelegatingDriver delegating, final ParameterDriver driver) {
this.delegating = delegating;
this.drivers = new ArrayList<>();
drivers.add(driver);
}
/** Get the {@link DelegatingDriver} associated with this instance.
* @return {@link DelegatingDriver} associated with this instance
* @since 9.1
*/
DelegatingDriver getDelegatingDriver() {
return delegating;
}
/** Add a driver to the list synchronized together by the instance.
* @param driver driver to add
* @since 10.1
*/
void add(final ParameterDriver driver) {
drivers.add(driver);
}
/** Get the drivers synchronized together by the instance.
* @return drivers synchronized together by the instance.
* @since 10.1
*/
public List<ParameterDriver> getDrivers() {
return drivers;
}
/** {@inheritDoc} */
@Override
public void valueSpanMapChanged(final TimeSpanMap<Double> previousValueSpanMap, final ParameterDriver driver) {
updateAll(driver, d -> d.setValueSpanMap(driver));
}
/** {@inheritDoc} */
@Override
public void valueChanged(final double previousValue, final ParameterDriver driver, final AbsoluteDate date) {
updateAll(driver, d -> d.setValue(driver.getValue(date), date));
}
/** {@inheritDoc} */
@Override
public void referenceDateChanged(final AbsoluteDate previousReferenceDate, final ParameterDriver driver) {
updateAll(driver, d -> d.setReferenceDate(driver.getReferenceDate()));
}
/** {@inheritDoc} */
@Override
public void nameChanged(final String previousName, final ParameterDriver driver) {
updateAll(driver, d -> d.setName(driver.getName()));
}
/** {@inheritDoc} */
@Override
public void selectionChanged(final boolean previousSelection, final ParameterDriver driver) {
updateAll(driver, d -> d.setSelected(driver.isSelected()));
}
/** {@inheritDoc} */
@Override
public void estimationTypeChanged(final boolean previousSelection, final ParameterDriver driver) {
updateAll(driver, d -> d.setContinuousEstimation(driver.isContinuousEstimation()));
}
/** {@inheritDoc} */
@Override
public void referenceValueChanged(final double previousReferenceValue, final ParameterDriver driver) {
updateAll(driver, d -> d.setReferenceValue(driver.getReferenceValue()));
}
/** {@inheritDoc} */
@Override
public void minValueChanged(final double previousMinValue, final ParameterDriver driver) {
updateAll(driver, d -> d.setMinValue(driver.getMinValue()));
}
/** {@inheritDoc} */
@Override
public void maxValueChanged(final double previousMaxValue, final ParameterDriver driver) {
updateAll(driver, d -> d.setMaxValue(driver.getMaxValue()));
}
/** {@inheritDoc} */
@Override
public void scaleChanged(final double previousScale, final ParameterDriver driver) {
updateAll(driver, d -> d.setScale(driver.getScale()));
}
/** Update all bound parameters.
* @param driver driver triggering the update
* @param updater updater to use
*/
private void updateAll(final ParameterDriver driver, final Updater updater) {
final boolean firstCall = depth++ == 0;
if (firstCall) {
root = driver;
}
if (driver == getDelegatingDriver()) {
// propagate change downwards, which will trigger recursive calls
for (final ParameterDriver d : drivers) {
if (d != root) {
updater.update(d);
}
}
} else if (firstCall) {
// first call started from an underlying driver, propagate change upwards
updater.update(getDelegatingDriver());
}
if (--depth == 0) {
// this is the end of the root call
root = null;
}
}
}
/** Interface for updating parameters. */
@FunctionalInterface
private interface Updater {
/** Update a driver.
* @param driver driver to update
*/
void update(ParameterDriver driver);
}
}