1 /* Copyright 2002-2024 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 import java.io.Serializable;
20
21 import org.hipparchus.CalculusFieldElement;
22
23 /** Interface for time scales.
24 * <p>This is the interface representing all time scales. Time scales are related
25 * to each other by some offsets that may be discontinuous (for example
26 * the {@link UTCScale UTC scale} with respect to the {@link TAIScale
27 * TAI scale}).</p>
28 * @author Luc Maisonobe
29 * @see AbsoluteDate
30 */
31 public interface TimeScale extends Serializable {
32
33 /** Get the offset to convert locations from {@link TAIScale} to instance.
34 * @param date conversion date
35 * @return offset in seconds to add to a location in <em>{@link TAIScale}
36 * time scale</em> to get a location in <em>instance time scale</em>
37 * @see #offsetToTAI(DateComponents, TimeComponents)
38 */
39 TimeOffset offsetFromTAI(AbsoluteDate date);
40
41 /** Get the offset to convert locations from {@link TAIScale} to instance.
42 * @param date conversion date
43 * @param <T> type of the filed elements
44 * @return offset in seconds to add to a location in <em>{@link TAIScale}
45 * time scale</em> to get a location in <em>instance time scale</em>
46 * @see #offsetToTAI(DateComponents, TimeComponents)
47 * @since 9.0
48 */
49 <T extends CalculusFieldElement<T>> T offsetFromTAI(FieldAbsoluteDate<T> date);
50
51 /** Get the offset to convert locations from instance to {@link TAIScale}.
52 * @param date date location in the time scale
53 * @param time time location in the time scale
54 * @return offset in seconds to add to a location in <em>instance time scale</em>
55 * to get a location in <em>{@link TAIScale} time scale</em>
56 * @see #offsetFromTAI(AbsoluteDate)
57 */
58 default TimeOffset offsetToTAI(final DateComponents date, final TimeComponents time) {
59 final AbsoluteDate reference = new AbsoluteDate(date, time, new TAIScale());
60 TimeOffset offset = TimeOffset.ZERO;
61 for (int i = 0; i < 8; i++) {
62 offset = offsetFromTAI(reference.shiftedBy(offset)).negate();
63 }
64 return offset;
65 }
66
67 /** Check if date is within a leap second introduction <em>in this time scale</em>.
68 * <p>
69 * This method will return false for all time scales that do <em>not</em>
70 * implement leap seconds, even if the date corresponds to a leap second
71 * in {@link UTCScale UTC scale}.
72 * </p>
73 * @param date date to check
74 * @return true if time is within a leap second introduction
75 */
76 default boolean insideLeap(final AbsoluteDate date) {
77 return false;
78 }
79
80 /** Check if date is within a leap second introduction <em>in this time scale</em>.
81 * <p>
82 * This method will return false for all time scales that do <em>not</em>
83 * implement leap seconds, even if the date corresponds to a leap second
84 * in {@link UTCScale UTC scale}.
85 * </p>
86 * @param date date to check
87 * @param <T> type of the filed elements
88 * @return true if time is within a leap second introduction
89 * @since 9.0
90 */
91 default <T extends CalculusFieldElement<T>> boolean insideLeap(final FieldAbsoluteDate<T> date) {
92 return false;
93 }
94
95 /** Check length of the current minute <em>in this time scale</em>.
96 * <p>
97 * This method will return 60 for all time scales that do <em>not</em>
98 * implement leap seconds, even if the date corresponds to a leap second
99 * in {@link UTCScale UTC scale}, and 61 for time scales that do implement
100 * leap second when the current date is within the last minute before the
101 * leap, or during the leap itself.
102 * </p>
103 * @param date date to check
104 * @return 60 or 61 depending on leap seconds introduction
105 */
106 default int minuteDuration(final AbsoluteDate date) {
107 return 60;
108 }
109
110 /** Check length of the current minute <em>in this time scale</em>.
111 * <p>
112 * This method will return 60 for all time scales that do <em>not</em>
113 * implement leap seconds, even if the date corresponds to a leap second
114 * in {@link UTCScale UTC scale}, and 61 for time scales that do implement
115 * leap second when the current date is within the last minute before the
116 * leap, or during the leap itself.
117 * </p>
118 * @param date date to check
119 * @param <T> type of the filed elements
120 * @return 60 or 61 depending on leap seconds introduction
121 * @since 9.0
122 */
123 default <T extends CalculusFieldElement<T>> int minuteDuration(final FieldAbsoluteDate<T> date) {
124 return 60;
125 }
126
127 /** Get the value of the previous leap.
128 * <p>
129 * This method will return 0 for all time scales that do <em>not</em>
130 * implement leap seconds.
131 * </p>
132 * @param date date to check
133 * @return value of the previous leap
134 */
135 default TimeOffset getLeap(final AbsoluteDate date) {
136 return TimeOffset.ZERO;
137 }
138
139 /** Get the value of the previous leap.
140 * <p>
141 * This method will return 0.0 for all time scales that do <em>not</em>
142 * implement leap seconds.
143 * </p>
144 * @param date date to check
145 * @param <T> type of the filed elements
146 * @return value of the previous leap
147 * @since 9.0
148 */
149 default <T extends CalculusFieldElement<T>> T getLeap(final FieldAbsoluteDate<T> date) {
150 return date.getField().getZero();
151 }
152
153 /** Get the name time scale.
154 * @return name of the time scale
155 */
156 String getName();
157
158 }