ImmutableTimeStampedCache.java

  1. /* Contributed in the public domain.
  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. import java.util.ArrayList;
  19. import java.util.Collection;
  20. import java.util.Collections;
  21. import java.util.List;
  22. import java.util.stream.Stream;

  23. import org.hipparchus.exception.LocalizedCoreFormats;
  24. import org.orekit.errors.OrekitException;
  25. import org.orekit.errors.OrekitIllegalArgumentException;
  26. import org.orekit.errors.OrekitIllegalStateException;
  27. import org.orekit.errors.OrekitMessages;
  28. import org.orekit.errors.TimeStampedCacheException;
  29. import org.orekit.time.AbsoluteDate;
  30. import org.orekit.time.ChronologicalComparator;
  31. import org.orekit.time.TimeStamped;

  32. /**
  33.  * A cache of {@link TimeStamped} data that provides concurrency through
  34.  * immutability. This strategy is suitable when all of the cached data is stored
  35.  * in memory. (For example, {@link org.orekit.time.UTCScale UTCScale}) This
  36.  * class then provides convenient methods for accessing the data.
  37.  *
  38.  * @author Evan Ward
  39.  * @param <T>  the type of data
  40.  */
  41. public class ImmutableTimeStampedCache<T extends TimeStamped>
  42.     implements TimeStampedCache<T> {

  43.     /**
  44.      * An empty immutable cache that always throws an exception on attempted
  45.      * access.
  46.      */
  47.     @SuppressWarnings("rawtypes")
  48.     private static final ImmutableTimeStampedCache EMPTY_CACHE =
  49.         new EmptyTimeStampedCache<>();

  50.     /**
  51.      * the cached data. Be careful not to modify it after the constructor, or
  52.      * return a reference that allows mutating this list.
  53.      */
  54.     private final List<T> data;

  55.     /**
  56.      * the maximum size list to return from {@link #getNeighbors(AbsoluteDate, int)}.
  57.      * @since 12.0
  58.      */
  59.     private final int maxNeighborsSize;

  60.     /**
  61.      * Create a new cache with the given neighbors size and data.
  62.      *
  63.      * @param maxNeighborsSize the maximum size of the list returned from
  64.      *        {@link #getNeighbors(AbsoluteDate, int)}. Must be less than or equal to
  65.      *        {@code data.size()}.
  66.      * @param data the backing data for this cache. The list will be copied to
  67.      *        ensure immutability. To guarantee immutability the entries in
  68.      *        {@code data} must be immutable themselves. There must be more data
  69.      *        than {@code maxNeighborsSize}.
  70.      * @throws IllegalArgumentException if {@code neightborsSize > data.size()}
  71.      *         or if {@code neighborsSize} is negative
  72.      */
  73.     public ImmutableTimeStampedCache(final int maxNeighborsSize,
  74.                                      final Collection<? extends T> data) {
  75.         // parameter check
  76.         if (maxNeighborsSize > data.size()) {
  77.             throw new OrekitIllegalArgumentException(OrekitMessages.NOT_ENOUGH_CACHED_NEIGHBORS,
  78.                                                      data.size(), maxNeighborsSize);
  79.         }
  80.         if (maxNeighborsSize < 1) {
  81.             throw new OrekitIllegalArgumentException(LocalizedCoreFormats.NUMBER_TOO_SMALL,
  82.                                                      maxNeighborsSize, 1);
  83.         }

  84.         // assign instance variables
  85.         this.maxNeighborsSize = maxNeighborsSize;
  86.         // sort and copy data first
  87.         this.data = new ArrayList<>(data);
  88.         this.data.sort(new ChronologicalComparator());

  89.     }

  90.     /**
  91.      * private constructor for {@link #EMPTY_CACHE}.
  92.      */
  93.     private ImmutableTimeStampedCache() {
  94.         this.data             = null;
  95.         this.maxNeighborsSize = 0;
  96.     }

  97.     /** {@inheritDoc} */
  98.     public Stream<T> getNeighbors(final AbsoluteDate central, final int n) {
  99.         if (n > maxNeighborsSize) {
  100.             throw new OrekitException(OrekitMessages.NOT_ENOUGH_DATA, maxNeighborsSize);
  101.         }
  102.         return new SortedListTrimmer(n).getNeighborsSubList(central, data).stream();
  103.     }

  104.     /** {@inheritDoc} */
  105.     public int getMaxNeighborsSize() {
  106.         return maxNeighborsSize;
  107.     }

  108.     /** {@inheritDoc} */
  109.     public T getEarliest() {
  110.         return this.data.get(0);
  111.     }

  112.     /** {@inheritDoc} */
  113.     public T getLatest() {
  114.         return this.data.get(this.data.size() - 1);
  115.     }

  116.     /**
  117.      * Get all of the data in this cache.
  118.      *
  119.      * @return a sorted collection of all data passed in the
  120.      *         {@link #ImmutableTimeStampedCache(int, Collection) constructor}.
  121.      */
  122.     public List<T> getAll() {
  123.         return Collections.unmodifiableList(this.data);
  124.     }

  125.     /** {@inheritDoc} */
  126.     @Override
  127.     public String toString() {
  128.         return "Immutable cache with " + this.data.size() + " entries";
  129.     }

  130.     /**
  131.      * An empty immutable cache that always throws an exception on attempted
  132.      * access.
  133.      */
  134.     private static class EmptyTimeStampedCache<T extends TimeStamped> extends ImmutableTimeStampedCache<T> {

  135.         /** {@inheritDoc} */
  136.         @Override
  137.         public Stream<T> getNeighbors(final AbsoluteDate central) {
  138.             throw new TimeStampedCacheException(OrekitMessages.NO_CACHED_ENTRIES);
  139.         }

  140.         /** {@inheritDoc} */
  141.         @Override
  142.         public int getMaxNeighborsSize() {
  143.             return 0;
  144.         }

  145.         /** {@inheritDoc} */
  146.         @Override
  147.         public T getEarliest() {
  148.             throw new OrekitIllegalStateException(OrekitMessages.NO_CACHED_ENTRIES);
  149.         }

  150.         /** {@inheritDoc} */
  151.         @Override
  152.         public T getLatest() {
  153.             throw new OrekitIllegalStateException(OrekitMessages.NO_CACHED_ENTRIES);
  154.         }

  155.         /** {@inheritDoc} */
  156.         @Override
  157.         public List<T> getAll() {
  158.             return Collections.emptyList();
  159.         }

  160.         /** {@inheritDoc} */
  161.         @Override
  162.         public String toString() {
  163.             return "Empty immutable cache";
  164.         }

  165.     }

  166.     /**
  167.      * Get an empty immutable cache, cast to the correct type.
  168.      * @param <TS>  the type of data
  169.      * @return an empty {@link ImmutableTimeStampedCache}.
  170.      */
  171.     @SuppressWarnings("unchecked")
  172.     public static <TS extends TimeStamped> ImmutableTimeStampedCache<TS> emptyCache() {
  173.         return (ImmutableTimeStampedCache<TS>) EMPTY_CACHE;
  174.     }

  175. }