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.orekit.errors.OrekitException;
20  import org.orekit.propagation.SpacecraftState;
21  import org.orekit.propagation.events.EventDetector;
22  import org.orekit.time.AbsoluteDate;
23  
24  
25  /**
26   * An interface defining how to override event handling behavior in the standard
27   * propagator eventing classes without requiring subclassing.  In cases where
28   * one wishes to use anonymous classes rather than explicit subclassing this
29   * allows for a more direct way to override the behavior.  Event classes have to
30   * specifically support this capability.
31   *
32   * @author Hank Grabowski
33   *
34   * @param <T> object type that the handler is called from
35   * @since 6.1
36   */
37  public interface EventHandler<T extends EventDetector> {
38  
39      /** Enumerate for actions to be performed when an event occurs. */
40      enum Action {
41  
42          /** Stop indicator.
43           * <p>This value should be used as the return value of the {@link
44           * #eventOccurred eventOccurred} method when the propagation should be
45           * stopped after the event ending the current step.</p>
46           */
47          STOP,
48  
49          /** Reset state indicator.
50           * <p>This value should be used as the return value of the {@link
51           * #eventOccurred eventOccurred} method when the propagation should
52           * go on after the event ending the current step, with a new state
53           * (which will be retrieved thanks to the {@link #resetState
54           * resetState} method).</p>
55           */
56          RESET_STATE,
57  
58          /** Reset derivatives indicator.
59           * <p>This value should be used as the return value of the {@link
60           * #eventOccurred eventOccurred} method when the propagation should
61           * go on after the event ending the current step, with recomputed
62           * derivatives vector.</p>
63           */
64          RESET_DERIVATIVES,
65  
66          /** Continue indicator.
67           * <p>This value should be used as the return value of the {@link
68           * #eventOccurred eventOccurred} method when the propagation should go
69           * on after the event ending the current step.</p>
70           */
71          CONTINUE;
72  
73      }
74  
75      /** Initialize event handler at the start of a propagation.
76       * <p>
77       * This method is called once at the start of the propagation. It
78       * may be used by the event handler to initialize some internal data
79       * if needed.
80       * </p>
81       * <p>
82       * The default implementation does nothing
83       * </p>
84       * @param initialState initial state
85       * @param target target date for the propagation
86       *
87       * @throws OrekitException if some specific error occurs
88       */
89      default void init(SpacecraftState initialState, AbsoluteDate target)
90              throws OrekitException {
91          // nothing by default
92      }
93  
94      /**
95       * eventOccurred method mirrors the same interface method as in {@link EventDetector}
96       * and its subclasses, but with an additional parameter that allows the calling
97       * method to pass in an object from the detector which would have potential
98       * additional data to allow the implementing class to determine the correct
99       * return state.
100      *
101      * @param s SpaceCraft state to be used in the evaluation
102      * @param detector object with appropriate type that can be used in determining correct return state
103      * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
104      * @return the Action that the calling detector should pass back to the evaluation system
105      *
106      * @exception OrekitException if some specific error occurs
107      */
108     Action eventOccurred(SpacecraftState s, T detector, boolean increasing) throws OrekitException;
109 
110     /** Reset the state prior to continue propagation.
111      * <p>This method is called after the step handler has returned and
112      * before the next step is started, but only when {@link
113      * #eventOccurred} has itself returned the {@link Action#RESET_STATE}
114      * indicator. It allows the user to reset the state for the next step,
115      * without perturbing the step handler of the finishing step. If the
116      * {@link #eventOccurred} never returns the {@link Action#RESET_STATE}
117      * indicator, this function will never be called, and it is safe to simply return null.</p>
118      * <p>
119      * The default implementation simply return its argument.
120      * </p>
121      * @param detector object with appropriate type that can be used in determining correct return state
122      * @param oldState old state
123      * @return new state
124      * @exception OrekitException if the state cannot be reseted
125      */
126     default SpacecraftState resetState(T detector, SpacecraftState oldState)
127         throws OrekitException {
128         return oldState;
129     }
130 
131 }