TimeSpanMap.java

  1. /* Copyright 2002-2020 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.Collections;
  20. import java.util.NavigableSet;
  21. import java.util.TreeSet;

  23. import org.orekit.time.AbsoluteDate;
  24. import org.orekit.time.ChronologicalComparator;
  25. import org.orekit.time.TimeStamped;

  27. /** Container for objects that apply to spans of time.

  29.  * @param <T> Type of the data.

  31.  * @author Luc Maisonobe
  32.  * @since 7.1
  33.  */
  34. public class TimeSpanMap<T> {

  36.     /** Container for the data. */
  37.     private final NavigableSet<Transition<T>> data;

  39.     /** Create a map containing a single object, initially valid throughout the timeline.
  40.      * <p>
  41.      * The real validity of this first entry will be truncated as other
  42.      * entries are either {@link #addValidBefore(Object, AbsoluteDate)
  43.      * added before} it or {@link #addValidAfter(Object, AbsoluteDate)
  44.      * added after} it.
  45.      * </p>
  46.      * @param entry entry (initially valid throughout the timeline)
  47.      */
  48.     public TimeSpanMap(final T entry) {
  49.         data = new TreeSet<Transition<T>>(new ChronologicalComparator());
  50.         data.add(new Transition<T>(AbsoluteDate.ARBITRARY_EPOCH, entry, entry));
  51.     }

  53.     /** Add an entry valid before a limit date.
  54.      * <p>
  55.      * As an entry is valid, it truncates the validity of the neighboring
  56.      * entries already present in the map.
  57.      * </p>
  58.      * <p>
  59.      * The transition dates should be entered only once, either
  60.      * by a call to this method or by a call to {@link #addValidAfter(Object,
  61.      * AbsoluteDate)}. Repeating a transition date will lead to unexpected
  62.      * result and is not supported.
  63.      * </p>
  64.      * <p>
  65.      * Using addValidBefore(entry, t) will make 'entry' valid in ]-∞, t[ (note the open bracket).
  66.      * </p>
  67.      * @param entry entry to add
  68.      * @param latestValidityDate date before which the entry is valid
  69.      * (must be different from <em>all</em> dates already used for transitions)
  70.      */
  71.     public void addValidBefore(final T entry, final AbsoluteDate latestValidityDate) {

  73.         if (data.size() == 1) {
  74.             final Transition<T> single = data.first();
  75.             if (single.getBefore() == single.getAfter()) {
  76.                 // the single entry was a dummy one, without a real transition
  77.                 // we replace it entirely
  78.                 data.clear();
  79.                 data.add(new Transition<T>(latestValidityDate, entry, single.getAfter()));
  80.                 return;
  81.             }
  82.         }

  84.         final Transition<T> previous =
  85.                 data.floor(new Transition<T>(latestValidityDate, entry, null));
  86.         if (previous == null) {
  87.             // the new transition will be the first one
  88.             data.add(new Transition<T>(latestValidityDate, entry, data.first().getBefore()));
  89.         } else {
  90.             // the new transition will be after the previous one
  91.             data.remove(previous);
  92.             data.add(new Transition<T>(previous.date,      previous.getBefore(), entry));
  93.             data.add(new Transition<T>(latestValidityDate, entry,                previous.getAfter()));
  94.         }

  96.     }

  98.     /** Add an entry valid after a limit date.
  99.      * <p>
  100.      * As an entry is valid, it truncates the validity of the neighboring
  101.      * entries already present in the map.
  102.      * </p>
  103.      * <p>
  104.      * The transition dates should be entered only once, either
  105.      * by a call to this method or by a call to {@link #addValidBefore(Object,
  106.      * AbsoluteDate)}. Repeating a transition date will lead to unexpected
  107.      * result and is not supported.
  108.      * </p>
  109.      * <p>
  110.      * Using addValidAfter(entry, t) will make 'entry' valid [t, +∞[ (note the closed bracket).
  111.      * </p>
  112.      * @param entry entry to add
  113.      * @param earliestValidityDate date after which the entry is valid
  114.      * (must be different from <em>all</em> dates already used for transitions)
  115.      */
  116.     public void addValidAfter(final T entry, final AbsoluteDate earliestValidityDate) {

  118.         if (data.size() == 1) {
  119.             final Transition<T> single = data.first();
  120.             if (single.getBefore() == single.getAfter()) {
  121.                 // the single entry was a dummy one, without a real transition
  122.                 // we replace it entirely
  123.                 data.clear();
  124.                 data.add(new Transition<T>(earliestValidityDate, single.getBefore(), entry));
  125.                 return;
  126.             }
  127.         }

  129.         final Transition<T> next =
  130.                 data.ceiling(new Transition<T>(earliestValidityDate, entry, null));
  131.         if (next == null) {
  132.             // the new transition will be the last one
  133.             data.add(new Transition<T>(earliestValidityDate, data.last().getAfter(), entry));
  134.         } else {
  135.             // the new transition will be before the next one
  136.             data.remove(next);
  137.             data.add(new Transition<T>(earliestValidityDate, next.getBefore(), entry));
  138.             data.add(new Transition<T>(next.date,            entry,            next.getAfter()));
  139.         }

  141.     }

  143.     /** Get the entry valid at a specified date.
  144.      * @param date date at which the entry must be valid
  145.      * @return valid entry at specified date
  146.      */
  147.     public T get(final AbsoluteDate date) {
  148.         final Transition<T> previous = data.floor(new Transition<T>(date, null, null));
  149.         if (previous == null) {
  150.             // there are no transition before the specified date
  151.             // return the first valid entry
  152.             return data.first().getBefore();
  153.         } else {
  154.             return previous.getAfter();
  155.         }
  156.     }

  158.     /** Get the time span containing a specified date.
  159.      * @param date date belonging to the desired time span
  160.      * @return time span containing the specified date
  161.      * @since 9.3
  162.      */
  163.     public Span<T> getSpan(final AbsoluteDate date) {
  164.         final Transition<T> previous = data.floor(new Transition<T>(date, null, null));
  165.         if (previous == null) {
  166.             // there are no transition before the specified date
  167.             // return the first valid entry
  168.             return new Span<>(data.first().getBefore(),
  169.                               AbsoluteDate.PAST_INFINITY,
  170.                               data.first().getDate());
  171.         } else {
  172.             final Transition<T> next = data.higher(previous);
  173.             return new Span<>(previous.getAfter(),
  174.                               previous.getDate(),
  175.                               next == null ? AbsoluteDate.FUTURE_INFINITY : next.getDate());
  176.         }
  177.     }

  179.     /** Extract a range of the map.
  180.      * <p>
  181.      * The object returned will be a new independent instance that will contain
  182.      * only the transitions that lie in the specified range.
  183.      * </p>
  184.      * <p>
  185.      * Consider for example a map containing objects O₀ valid before t₁, O₁ valid
  186.      * between t₁ and t₂, O₂ valid between t₂ and t₃, O₃ valid between t₃ and t₄,
  187.      * and O₄ valid after t₄. then calling this method with a {@code start}
  188.      * date between t₁ and t₂ and a {@code end} date between t₃ and t₄
  189.      * will result in a new map containing objects O₁ valid before t₂, O₂
  190.      * valid between t₂ and t₃, and O₃ valid after t₃. The validity of O₁
  191.      * is therefore extended in the past, and the validity of O₃ is extended
  192.      * in the future.
  193.      * </p>
  194.      * @param start earliest date at which a transition is included in the range
  195.      * (may be set to {@link AbsoluteDate#PAST_INFINITY} to keep all early transitions)
  196.      * @param end latest date at which a transition is included in the r
  197.      * (may be set to {@link AbsoluteDate#FUTURE_INFINITY} to keep all late transitions)
  198.      * @return a new instance with all transitions restricted to the specified range
  199.      * @since 9.2
  200.      */
  201.     public TimeSpanMap<T> extractRange(final AbsoluteDate start, final AbsoluteDate end) {

  203.         final NavigableSet<Transition<T>> inRange = data.subSet(new Transition<T>(start, null, null), true,
  204.                                                                 new Transition<T>(end,   null, null), true);
  205.         if (inRange.isEmpty()) {
  206.             // there are no transitions at all in the range
  207.             // we need to pick up the only valid object
  208.             return new TimeSpanMap<>(get(start));
  209.         }

  211.         final TimeSpanMap<T> range = new TimeSpanMap<>(inRange.first().before);
  212.         for (final Transition<T> transition : inRange) {
  213.             range.addValidAfter(transition.after, transition.getDate());
  214.         }

  216.         return range;

  218.     }

  220.     /** Get an unmodifiable view of the sorted transitions.
  221.      * @return unmodifiable view of the sorted transitions
  222.      */
  223.     public NavigableSet<Transition<T>> getTransitions() {
  224.         return Collections.unmodifiableNavigableSet(data);
  225.     }

  227.     /** Class holding transition times.
  228.      * <p>
  229.      * This data type is dual to {@link Span}, it is
  230.      * focused one transition date, and gives access to
  231.      * surrounding valid data whereas {@link Span} is focused
  232.      * on one valid data, and gives access to surrounding
  233.      * transition dates.
  234.      * </p>
  235.      * @param <S> Type of the data.
  236.      */
  237.     public static class Transition<S> implements TimeStamped {

  239.         /** Transition date. */
  240.         private final AbsoluteDate date;

  242.         /** Entry valid before the transition. */
  243.         private final S before;

  245.         /** Entry valid after the transition. */
  246.         private final S after;

  248.         /** Simple constructor.
  249.          * @param date transition date
  250.          * @param before entry valid before the transition
  251.          * @param after entry valid after the transition
  252.          */
  253.         private Transition(final AbsoluteDate date, final S before, final S after) {
  254.             this.date   = date;
  255.             this.before = before;
  256.             this.after  = after;
  257.         }

  259.         /** Get the transition date.
  260.          * @return transition date
  261.          */
  262.         @Override
  263.         public AbsoluteDate getDate() {
  264.             return date;
  265.         }

  267.         /** Get the entry valid before transition.
  268.          * @return entry valid before transition
  269.          */
  270.         public S getBefore() {
  271.             return before;
  272.         }

  274.         /** Get the entry valid after transition.
  275.          * @return entry valid after transition
  276.          */
  277.         public S getAfter() {
  278.             return after;
  279.         }

  281.     }

  283.     /** Holder for one time span.
  284.      * <p>
  285.      * This data type is dual to {@link Transition}, it
  286.      * is focused on one valid data, and gives access to
  287.      * surrounding transition dates whereas {@link Transition}
  288.      * is focused on one transition date, and gives access to
  289.      * surrounding valid data.
  290.      * </p>
  291.      * @param <S> Type of the data.
  292.      * @since 9.3
  293.      */
  294.     public static class Span<S> {

  296.         /** Valid data. */
  297.         private final S data;

  299.         /** Start of validity for the data. */
  300.         private final AbsoluteDate start;

  302.         /** End of validity for the data. */
  303.         private final AbsoluteDate end;

  305.         /** Simple constructor.
  306.          * @param data valid data
  307.          * @param start start of validity for the data
  308.          * @param end end of validity for the data
  309.          */
  310.         private Span(final S data, final AbsoluteDate start, final AbsoluteDate end) {
  311.             this.data  = data;
  312.             this.start = start;
  313.             this.end   = end;
  314.         }

  316.         /** Get the data valid during this time span.
  317.          * @return data valid during this time span
  318.          */
  319.         public S getData() {
  320.             return data;
  321.         }

  323.         /** Get the start of this time span.
  324.          * @return start of this time span
  325.          */
  326.         public AbsoluteDate getStart() {
  327.             return start;
  328.         }

  330.         /** Get the end of this time span.
  331.          * @return end of this time span
  332.          */
  333.         public AbsoluteDate getEnd() {
  334.             return end;
  335.         }

  337.     }

  339. }
Created with JaCoCo 0.8.5.201910111838