1 /* Copyright 2002-2021 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;
18
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;
24
25 import org.orekit.time.AbsoluteDate;
26
27
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 {
49
50 /** Managed drivers. */
51 private final List<DelegatingDriver> delegating;
52
53 /** Creates an empty list.
54 */
55 public ParameterDriversList() {
56 this.delegating = new ArrayList<>();
57 }
58
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) {
70
71 final DelegatingDriver existingHere = findByName(driver.getName());
72 final DelegatingDriver alreadyBound = getAssociatedDelegatingDriver(driver);
73
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 }
92
93 }
94
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 }
109
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 }
122
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 }
136
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 }
148
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 }
162
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 }
169
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 }
183
184 /** Specialized driver delegating to several other managing
185 * the same parameter name.
186 */
187 public static class DelegatingDriver extends ParameterDriver {
188
189 /** Lists owning this delegating driver. */
190 private final List<ParameterDriversList> owners;
191
192 /** Observer for propagating changes between all drivers. */
193 private ChangesForwarder forwarder;
194
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());
202
203 owners = new ArrayList<>();
204 addOwner(owner);
205
206 setValue(driver.getValue());
207 setReferenceDate(driver.getReferenceDate());
208 setSelected(driver.isSelected());
209
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);
214
215 }
216
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 }
223
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 }
235
236 /** Add a driver.
237 * @param driver driver to add
238 */
239 private void add(final ParameterDriver driver) {
240
241 setValue(driver.getValue());
242 setReferenceDate(driver.getReferenceDate());
243
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 }
250
251 driver.addObserver(forwarder);
252 forwarder.add(driver);
253
254 }
255
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) {
266
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 }
272
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 }
281
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 }
291
292 // forwarding is now delegated to current instance
293 other.replaceObserver(other.forwarder, forwarder);
294 other.forwarder = forwarder;
295
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 }
301
302 }
303
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 }
313
314 }
315
316 /** Local observer for propagating changes, avoiding infinite recursion. */
317 private static class ChangesForwarder implements ParameterObserver {
318
319 /** DelegatingDriver we are associated with. */
320 private final DelegatingDriver delegating;
321
322 /** Drivers synchronized together by the instance. */
323 private final List<ParameterDriver> drivers;
324
325 /** Root of the current update chain. */
326 private ParameterDriver root;
327
328 /** Depth of the current update chain. */
329 private int depth;
330
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 }
340
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 }
348
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 }
356
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 }
364
365 /** {@inheritDoc} */
366 @Override
367 public void valueChanged(final double previousValue, final ParameterDriver driver) {
368 updateAll(driver, d -> d.setValue(driver.getValue()));
369 }
370
371 /** {@inheritDoc} */
372 @Override
373 public void referenceDateChanged(final AbsoluteDate previousReferenceDate, final ParameterDriver driver) {
374 updateAll(driver, d -> d.setReferenceDate(driver.getReferenceDate()));
375 }
376
377 /** {@inheritDoc} */
378 @Override
379 public void nameChanged(final String previousName, final ParameterDriver driver) {
380 updateAll(driver, d -> d.setName(driver.getName()));
381 }
382
383 /** {@inheritDoc} */
384 @Override
385 public void selectionChanged(final boolean previousSelection, final ParameterDriver driver) {
386 updateAll(driver, d -> d.setSelected(driver.isSelected()));
387 }
388
389 /** {@inheritDoc} */
390 @Override
391 public void referenceValueChanged(final double previousReferenceValue, final ParameterDriver driver) {
392 updateAll(driver, d -> d.setReferenceValue(driver.getReferenceValue()));
393 }
394
395 /** {@inheritDoc} */
396 @Override
397 public void minValueChanged(final double previousMinValue, final ParameterDriver driver) {
398 updateAll(driver, d -> d.setMinValue(driver.getMinValue()));
399 }
400
401 /** {@inheritDoc} */
402 @Override
403 public void maxValueChanged(final double previousMaxValue, final ParameterDriver driver) {
404 updateAll(driver, d -> d.setMaxValue(driver.getMaxValue()));
405 }
406
407 /** {@inheritDoc} */
408 @Override
409 public void scaleChanged(final double previousScale, final ParameterDriver driver) {
410 updateAll(driver, d -> d.setScale(driver.getScale()));
411 }
412
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) {
418
419 final boolean firstCall = depth++ == 0;
420 if (firstCall) {
421 root = driver;
422 }
423
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 }
435
436 if (--depth == 0) {
437 // this is the end of the root call
438 root = null;
439 }
440
441 }
442
443 }
444
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 }
453
454 }