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