EventsLogger.java

  1. /* Copyright 2002-2013 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (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.propagation.events;

  19. import java.io.Serializable;
  20. import java.util.ArrayList;
  21. import java.util.List;

  23. import org.orekit.errors.OrekitException;
  24. import org.orekit.propagation.SpacecraftState;
  25. import org.orekit.propagation.events.handlers.EventHandler;
  26. import org.orekit.time.AbsoluteDate;

  28. /** This class logs events detectors events during propagation.
  29.  *
  30.  * <p>As {@link EventDetector events detectors} are triggered during
  31.  * orbit propagation, an event specific {@link
  32.  * EventDetector.Action#eventOccurred(SpacecraftState, boolean) eventOccurred}
  33.  * method is called. This class can be used to add a global logging
  34.  * feature registering all events with their corresponding states in
  35.  * a chronological sequence (or reverse-chronological if propagation
  36.  * occurs backward).<p>
  37.  * <p>This class works by wrapping user-provided {@link EventDetector
  38.  * events detectors} before they are registered to the propagator. The
  39.  * wrapper monitor the calls to {@link
  40.  * EventDetector.Action#eventOccurred(SpacecraftState, boolean) eventOccurred}
  41.  * and store the corresponding events as {@link LoggedEvent} instances.
  42.  * After propagation is complete, the user can retrieve all the events
  43.  * that have occurred at once by calling method {@link #getLoggedEvents()}.</p>
  44.  *
  45.  * @author Luc Maisonobe
  46.  */
  47. public class EventsLogger implements Serializable {

  49.     /** Serializable UID. */
  50.     private static final long serialVersionUID = -8643810076248572648L;

  52.     /** List of occurred events. */
  53.     private final List<LoggedEvent> log;

  55.     /** Simple constructor.
  56.      * <p>
  57.      * Build an empty logger for events detectors.
  58.      * </p>
  59.      */
  60.     public EventsLogger() {
  61.         log = new ArrayList<EventsLogger.LoggedEvent>();
  62.     }

  64.     /** Monitor an event detector.
  65.      * <p>
  66.      * In order to monitor an event detector, it must be wrapped thanks to
  67.      * this method as follows:
  68.      * </p>
  69.      * <pre>
  70.      * Propagator propagator = new XyzPropagator(...);
  71.      * EventsLogger logger = new EventsLogger();
  72.      * EventDetector detector = new UvwDetector(...);
  73.      * propagator.addEventDetector(logger.monitorDetector(detector));
  74.      * </pre>
  75.      * <p>
  76.      * Note that the event detector returned by the {@link
  77.      * LoggedEvent#getEventDetector() getEventDetector} method in
  78.      * {@link LoggedEvent LoggedEvent} instances returned by {@link
  79.      * #getLoggedEvents()} are the {@code monitoredDetector} instances
  80.      * themselves, not the wrapping detector returned by this method.
  81.      * </p>
  82.      * @param monitoredDetector event detector to monitor
  83.      * @return the wrapping detector to add to the propagator
  84.      * @param <T> class type for the generic version
  85.      */
  86.     public <T extends EventDetector> EventDetector monitorDetector(final T monitoredDetector) {
  87.         return new LoggingWrapper<T>(monitoredDetector);
  88.     }

  90.     /** Clear the logged events.
  91.      */
  92.     public void clearLoggedEvents() {
  93.         log.clear();
  94.     }

  96.     /** Get an immutable copy of the logged events.
  97.      * <p>
  98.      * The copy is independent of the logger. It is preserved
  99.      * event if the {@link #clearLoggedEvents() clearLoggedEvents} method
  100.      * is called and the logger reused in another propagation.
  101.      * </p>
  102.      * @return an immutable copy of the logged events
  103.      */
  104.     public List<LoggedEvent> getLoggedEvents() {
  105.         return new ArrayList<EventsLogger.LoggedEvent>(log);
  106.     }

  108.     /** Class for logged events entries. */
  109.     public static class LoggedEvent implements Serializable {

  111.         /** Serializable UID. */
  112.         private static final long serialVersionUID = 20131202L;

  114.         /** Event detector triggered. */
  115.         private final EventDetector detector;

  117.         /** Triggering state. */
  118.         private final SpacecraftState state;

  120.         /** Increasing/decreasing status. */
  121.         private final boolean increasing;

  123.         /** Simple constructor.
  124.          * @param detector detector for event that was triggered
  125.          * @param state state at event trigger date
  126.          * @param increasing indicator if the event switching function was increasing
  127.          * or decreasing at event occurrence date
  128.          */
  129.         private LoggedEvent(final EventDetector detector, final SpacecraftState state, final boolean increasing) {
  130.             this.detector   = detector;
  131.             this.state      = state;
  132.             this.increasing = increasing;
  133.         }

  135.         /** Get the event detector triggered.
  136.          * @return event detector triggered
  137.          */
  138.         public EventDetector getEventDetector() {
  139.             return detector;
  140.         }

  142.         /** Get the triggering state.
  143.          * @return triggering state
  144.          * @see EventDetector.Action#eventOccurred(SpacecraftState, boolean)
  145.          */
  146.         public SpacecraftState getState() {
  147.             return state;
  148.         }

  150.         /** Get the Increasing/decreasing status of the event.
  151.          * @return increasing/decreasing status of the event
  152.          * @see EventDetector.Action#eventOccurred(SpacecraftState, boolean)
  153.          */
  154.         public boolean isIncreasing() {
  155.             return increasing;
  156.         }

  158.     }

  160.     /** Internal wrapper for events detectors.
  161.      * @param <T> class type for the generic version
  162.      */
  163.     private class LoggingWrapper<T extends EventDetector> extends AbstractReconfigurableDetector<LoggingWrapper<T>> {

  165.         /** Serializable UID. */
  166.         private static final long serialVersionUID = 20131118L;

  168.         /** Wrapped events detector. */
  169.         private final T detector;

  171.         /** Simple constructor.
  172.          * @param detector events detector to wrap
  173.          */
  174.         public LoggingWrapper(final T detector) {
  175.             this(detector.getMaxCheckInterval(), detector.getThreshold(),
  176.                  detector.getMaxIterationCount(), new LocalHandler<T>(),
  177.                  detector);
  178.         }

  180.         /** Private constructor with full parameters.
  181.          * <p>
  182.          * This constructor is private as users are expected to use the builder
  183.          * API with the various {@code withXxx()} methods to set up the instance
  184.          * in a readable manner without using a huge amount of parameters.
  185.          * </p>
  186.          * @param maxCheck maximum checking interval (s)
  187.          * @param threshold convergence threshold (s)
  188.          * @param maxIter maximum number of iterations in the event time search
  189.          * @param handler event handler to call at event occurrences
  190.          * @param detector events detector to wrap
  191.          * @since 6.1
  192.          */
  193.         private LoggingWrapper(final double maxCheck, final double threshold,
  194.                                final int maxIter, final EventHandler<LoggingWrapper<T>> handler,
  195.                                final T detector) {
  196.             super(maxCheck, threshold, maxIter, handler);
  197.             this.detector = detector;
  198.         }

  200.         /** {@inheritDoc} */
  201.         @Override
  202.         protected LoggingWrapper<T> create(final double newMaxCheck, final double newThreshold,
  203.                                            final int newMaxIter, final EventHandler<LoggingWrapper<T>> newHandler) {
  204.             return new LoggingWrapper<T>(newMaxCheck, newThreshold, newMaxIter, newHandler, detector);
  205.         }

  207.         /** Log an event.
  208.          * @param state state at event trigger date
  209.          * @param increasing indicator if the event switching function was increasing
  210.          */
  211.         public void logEvent(final SpacecraftState state, final boolean increasing) {
  212.             log.add(new LoggedEvent(detector, state, increasing));
  213.         }

  215.         /** {@inheritDoc} */
  216.         public void init(final SpacecraftState s0, final AbsoluteDate t) {
  217.             detector.init(s0, t);
  218.         }

  220.         /** {@inheritDoc} */
  221.         public double g(final SpacecraftState s) throws OrekitException {
  222.             return detector.g(s);
  223.         }

  225.     }

  227.     /** Local class for handling events.
  228.      * @param <T> class type for the generic version
  229.      */
  230.     private static class LocalHandler<T extends EventDetector> implements EventHandler<LoggingWrapper<T>> {

  232.         /** {@inheritDoc} */
  233.         public Action eventOccurred(final SpacecraftState s, final LoggingWrapper<T> wrapper, final boolean increasing)
  234.             throws OrekitException {
  235.             wrapper.logEvent(s, increasing);
  236.             if (wrapper.detector instanceof AbstractReconfigurableDetector) {
  237.                 @SuppressWarnings("unchecked")
  238.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) wrapper.detector).getHandler();
  239.                 return handler.eventOccurred(s, wrapper.detector, increasing);
  240.             } else {
  241.                 @SuppressWarnings("deprecation")
  242.                 final EventDetector.Action a = wrapper.detector.eventOccurred(s, increasing);
  243.                 return AbstractReconfigurableDetector.convert(a);
  244.             }
  245.         }

  247.         /** {@inheritDoc} */
  248.         @Override
  249.         public SpacecraftState resetState(final LoggingWrapper<T> wrapper, final SpacecraftState oldState)
  250.             throws OrekitException {
  251.             if (wrapper.detector instanceof AbstractReconfigurableDetector) {
  252.                 @SuppressWarnings("unchecked")
  253.                 final EventHandler<T> handler = ((AbstractReconfigurableDetector<T>) wrapper.detector).getHandler();
  254.                 return handler.resetState(wrapper.detector, oldState);
  255.             } else {
  256.                 @SuppressWarnings("deprecation")
  257.                 final SpacecraftState newState = wrapper.detector.resetState(oldState);
  258.                 return newState;
  259.             }
  260.         }

  262.     }

  264. }
Created with JaCoCo 0.6.3.201306030806