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.time;
18  
19  /** This interface represents objects that have a {@link AbsoluteDate}
20   * date attached to them.
21   * <p>Classes implementing this interface can be stored chronologically
22   * in sorted sets using {@link ChronologicalComparator} as the
23   * underlying comparator. An example using for {@link org.orekit.orbits.Orbit
24   * Orbit} instances is given here:</p>
25   * <pre>
26   *     SortedSet&lt;Orbit&gt; sortedOrbits =
27   *         new TreeSet&lt;Orbit&gt;(new ChronologicalComparator());
28   *     sortedOrbits.add(orbit1);
29   *     sortedOrbits.add(orbit2);
30   *     ...
31   * </pre>
32   * <p>This interface is also the base interface used to {@link
33   * org.orekit.utils.TimeStampedCache cache} series of time-dependent
34   * objects for interpolation in a thread-safe manner.</p>
35   * @see AbsoluteDate
36   * @see ChronologicalComparator
37   * @see org.orekit.utils.TimeStampedCache
38   * @author Luc Maisonobe
39   */
40  public interface TimeStamped {
41  
42      /** Get the date.
43       * @return date attached to the object
44       */
45      AbsoluteDate getDate();
46  
47      /** Compute the physically elapsed duration between two instants.
48       * <p>The returned duration is the number of seconds physically
49       * elapsed between the two instants, measured in a regular time
50       * scale with respect to surface of the Earth (i.e either the {@link
51       * TAIScale TAI scale}, the {@link TTScale TT scale} or the {@link
52       * GPSScale GPS scale}). It is the only method that gives a
53       * duration with a physical meaning.</p>
54       * @param other instant to subtract from the instance
55       * @return offset in seconds between the two instants (positive
56       * if the instance is posterior to the argument)
57       * @see AbsoluteDate#durationFrom(AbsoluteDate)
58       * @since 12.0
59       */
60      default double durationFrom(final TimeStamped other) {
61          return getDate().durationFrom(other.getDate());
62      }
63  
64  }