1   /* Copyright 2002-2021 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 #getNeighborsSize()}.
52       */
53      Stream<T> getNeighbors(AbsoluteDate central);
54  
55      /**
56       * Get the fixed size of the lists returned by
57       * {@link #getNeighbors(AbsoluteDate)}.
58       *
59       * @return size of the list
60       */
61      int getNeighborsSize();
62  
63      /**
64       * Get the earliest entry in this cache.
65       *
66       * @return earliest cached entry
67       * @throws IllegalStateException if this cache is empty
68       */
69      T getEarliest()
70          throws IllegalStateException;
71  
72      /**
73       * Get the latest entry in this cache.
74       *
75       * @return latest cached entry
76       * @throws IllegalStateException if this cache is empty
77       */
78      T getLatest()
79          throws IllegalStateException;
80  
81  }