1   /* Copyright 2013 Applied Defense Solutions, Inc.
2    * Licensed to CS Communication & Systèmes (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.handlers;
18  
19  import org.hipparchus.CalculusFieldElement;
20  import org.hipparchus.ode.events.Action;
21  import org.orekit.propagation.FieldSpacecraftState;
22  import org.orekit.propagation.events.EventDetector;
23  import org.orekit.propagation.events.FieldEventDetector;
24  import org.orekit.time.FieldAbsoluteDate;
25  
26  
27  /**
28   * An interface defining how to override event handling behavior in the standard
29   * propagator eventing classes without requiring subclassing.  In cases where
30   * one wishes to use anonymous classes rather than explicit subclassing this
31   * allows for a more direct way to override the behavior.  Event classes have to
32   * specifically support this capability.
33   *
34   * @author Hank Grabowski
35   *
36   * @param <KK> object type that the handler is called from
37   * @since 6.1
38   */
39  public interface FieldEventHandler<KK extends FieldEventDetector<T>, T extends CalculusFieldElement<T>> {
40  
41      /** Initialize event handler at the start of a propagation.
42       * <p>
43       * This method is called once at the start of the propagation. It
44       * may be used by the event handler to initialize some internal data
45       * if needed.
46       * </p>
47       * <p>
48       * The default implementation does nothing
49       * </p>
50       * @param initialState initial state
51       * @param target target date for the propagation
52       * @deprecated as of 11.1, replaced by {@link #init(FieldSpacecraftState, FieldAbsoluteDate, FieldEventDetector)}
53       */
54      default void init(final FieldSpacecraftState<T> initialState,
55                        final FieldAbsoluteDate<T> target) {
56          // nothing by default
57      }
58  
59      /** Initialize event handler at the start of a propagation.
60       * <p>
61       * This method is called once at the start of the propagation. It
62       * may be used by the event handler to initialize some internal data
63       * if needed.
64       * </p>
65       * <p>
66       * The default implementation does nothing
67       * </p>
68       * @param initialState initial state
69       * @param target target date for the propagation
70       * @param detector event detector related to the event handler
71       * @since 11.1
72       */
73      default void init(FieldSpacecraftState<T> initialState,
74                        FieldAbsoluteDate<T> target,
75                        final KK detector) {
76          // TODO remove the default implementation in 12.0
77          //       when init(initialState, target) is removed
78          init(initialState, target);
79      }
80  
81      /**
82       * eventOccurred method mirrors the same interface method as in {@link EventDetector}
83       * and its subclasses, but with an additional parameter that allows the calling
84       * method to pass in an object from the detector which would have potential
85       * additional data to allow the implementing class to determine the correct
86       * return state.
87       *
88       * @param s SpaceCraft state to be used in the evaluation
89       * @param detector object with appropriate type that can be used in determining correct return state
90       * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
91       * @return the Action that the calling detector should pass back to the evaluation system
92       *
93       */
94      Action eventOccurred(FieldSpacecraftState<T> s, KK detector, boolean increasing);
95  
96      /** Reset the state prior to continue propagation.
97       * <p>This method is called after the step handler has returned and
98       * before the next step is started, but only when {@link
99       * #eventOccurred} has itself returned the {@link Action#RESET_STATE}
100      * indicator. It allows the user to reset the state for the next step,
101      * without perturbing the step handler of the finishing step. If the
102      * {@link #eventOccurred} never returns the {@link Action#RESET_STATE}
103      * indicator, this function will never be called, and it is safe to simply return null.</p>
104      * <p>
105      * The default implementation simply return its argument.
106      * </p>
107      * @param detector object with appropriate type that can be used in determining correct return state
108      * @param oldState old state
109      * @return new state
110      */
111     default FieldSpacecraftState<T> resetState(KK detector, FieldSpacecraftState<T> oldState) {
112         return oldState;
113     }
114 }