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.List;
20  
21  import org.orekit.time.AbsoluteDate;
22  import org.orekit.time.TimeStamped;
23  
24  /** Generator to use for creating entries in {@link GenericTimeStampedCache time stamped caches}.
25   * <p>
26   * As long as a generator is referenced by one {@link GenericTimeStampedCache cache} only, it is
27   * guaranteed to be called in a thread-safe way, even if the cache is used in a multi-threaded
28   * environment. The cache takes care of scheduling the calls to all the methods defined in
29   * this interface so only one thread uses them at any time. There is no need for the
30   * implementing classes to handle synchronization or locks by themselves.
31   * </p>
32   * <p>
33   * The generator is provided by the user of the {@link GenericTimeStampedCache cache} and should
34   * be consistent with the way he will use the cached data.
35   * </p>
36   * <p>
37   * If entries must have regular time gaps (for example one entry every 3600 seconds), then
38   * the generator must ensure by itself all generated entries are exactly located on the
39   * expected regular grid, even if they are generated in random order. The reason for that
40   * is that the cache may ask for entries in different ranges and merge these ranges afterwards.
41   * A typical example would be a cache first calling the generator for 6 points around
42   * 2012-02-19T17:48:00 and when these points are exhausted calling the generator again for 6
43   * new points around 2012-02-19T23:20:00. If all points must be exactly 3600 seconds apart,
44   * the generator should generate the first 6 points at 2012-02-19T15:00:00, 2012-02-19T16:00:00,
45   * 2012-02-19T17:00:00, 2012-02-19T18:00:00, 2012-02-19T19:00:00 and 2012-02-19T20:00:00, and
46   * the next 6 points at 2012-02-19T21:00:00, 2012-02-19T22:00:00, 2012-02-19T23:00:00,
47   * 2012-02-20T00:00:00, 2012-02-20T01:00:00 and 2012-02-20T02:00:00. If the separation between
48   * the points is irrelevant, the first points could be generated at 17:48:00 instead of
49   * 17:00:00 or 18:00:00. The cache <em>will</em> merge arrays returned from different calls in
50   * the same global time slot.
51   * </p>
52   * @param <T> Type of the cached data.
53   * @author Luc Maisonobe
54   */
55  public interface TimeStampedGenerator<T extends TimeStamped> {
56  
57      /** Generate a chronologically sorted list of entries to be cached.
58       * <p>
59       * If {@code existingDate} is earlier than {@code date}, the range covered by
60       * generated entries must cover at least from {@code existingDate} (excluded)
61       * to {@code date} (included). If {@code existingDate} is later than {@code date},
62       * the range covered by generated entries must cover at least from {@code date}
63       * (included) to {@code existingDate} (excluded).
64       * </p>
65       * <p>
66       * The generated entries may cover a range larger than the minimum specified above
67       * if the generator prefers to generate large chunks of data at once. It may
68       * generate again entries already generated by an earlier call (typically at {@code
69       * existingDate}), these extra entries will be silently ignored by the cache.
70       * </p>
71       * <p>
72       * Non-coverage of the minimum range may lead to a loss of data, as the gap will
73       * not be filled by the {@link GenericTimeStampedCache} in subsequent calls.
74       * </p>
75       * <p>
76       * The generated entries <em>must</em> be chronologically sorted.
77       * </p>
78       * @param existingDate date of the closest already existing entry (may be null)
79       * @param date date that must be covered by the range of the generated array
80       * @return chronologically sorted list of generated entries
81       */
82      List<T> generate(AbsoluteDate existingDate, AbsoluteDate date);
83  
84  }