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.utils;
18
19 import org.hipparchus.CalculusFieldElement;
20 import org.orekit.time.FieldAbsoluteDate;
21 import org.orekit.time.FieldTimeStamped;
22
23 import java.util.stream.Stream;
24
25 /**
26 * Interface for a data structure that can provide concurrent access to {@link FieldTimeStamped} data surrounding a given
27 * date.
28 *
29 * @param <T> the type of data
30 * @param <KK> type of the field element
31 *
32 * @author Luc Maisonobe
33 * @author Evan Ward
34 * @author Vincent Cucchietti
35 * @see ImmutableFieldTimeStampedCache
36 */
37 public interface FieldTimeStampedCache<T extends FieldTimeStamped<KK>, KK extends CalculusFieldElement<KK>> {
38
39 /**
40 * Get the entries surrounding a central date.
41 * <p>
42 * If the central date is well within covered range, the returned array will be balanced with half the points before
43 * central date and half the points after it (depending on n parity, of course). If the central date is near the
44 * boundary, then the returned array will be unbalanced and will contain only the n earliest (or latest) entries. A
45 * typical example of the later case is leap seconds cache, since the number of leap seconds cannot be arbitrarily
46 * increased.
47 * <p>
48 * This method is safe for multiple threads to execute concurrently.
49 *
50 * @param central central date
51 *
52 * @return list of cached entries surrounding the specified date. The size of the list is guaranteed to be
53 * {@link #getMaxNeighborsSize()}.
54 */
55 default Stream<T> getNeighbors(FieldAbsoluteDate<KK> central) {
56 return getNeighbors(central, getMaxNeighborsSize());
57 }
58
59 /**
60 * Get the entries surrounding a central date.
61 * <p>
62 * If the central date is well within covered range, the returned array will be balanced with half the points before
63 * central date and half the points after it (depending on n parity, of course). If the central date is near the
64 * boundary, then the returned array will be unbalanced and will contain only the n earliest (or latest) entries. A
65 * typical example of the later case is leap seconds cache, since the number of leap seconds cannot be arbitrarily
66 * increased.
67 * <p>
68 * This method is safe for multiple threads to execute concurrently.
69 *
70 * @param central central date
71 * @param n number of neighbors (cannot exceed {@link #getMaxNeighborsSize()})
72 *
73 * @return list of cached entries surrounding the specified date. The size of the list is guaranteed to be
74 * {@link #getMaxNeighborsSize()}.
75 * @since 12.1
76 */
77 Stream<T> getNeighbors(FieldAbsoluteDate<KK> central, int n);
78
79 /**
80 * Get the fixed size of the lists returned by {@link #getNeighbors(FieldAbsoluteDate)}.
81 *
82 * @return size of the list
83 */
84 int getMaxNeighborsSize();
85
86 /**
87 * Get the earliest entry in this cache.
88 *
89 * @return earliest cached entry
90 *
91 * @throws IllegalStateException if this cache is empty
92 */
93 T getEarliest()
94 throws IllegalStateException;
95
96 /**
97 * Get the latest entry in this cache.
98 *
99 * @return latest cached entry
100 *
101 * @throws IllegalStateException if this cache is empty
102 */
103 T getLatest()
104 throws IllegalStateException;
105 }