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.ode.events.Action;
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 /** Initialize event handler at the start of a propagation.
40 * <p>
41 * This method is called once at the start of the propagation. It
42 * may be used by the event handler to initialize some internal data
43 * if needed.
44 * </p>
45 * <p>
46 * The default implementation does nothing
47 * </p>
48 * @param initialState initial state
49 * @param target target date for the propagation
50 * @param detector event detector related to the event handler
51 *
52 */
53 default void init(SpacecraftState initialState, AbsoluteDate target, final T detector) {
54 // nothing by default
55 }
56
57 /**
58 * eventOccurred method mirrors the same interface method as in {@link EventDetector}
59 * and its subclasses, but with an additional parameter that allows the calling
60 * method to pass in an object from the detector which would have potential
61 * additional data to allow the implementing class to determine the correct
62 * return state.
63 *
64 * @param s SpaceCraft state to be used in the evaluation
65 * @param detector object with appropriate type that can be used in determining correct return state
66 * @param increasing with the event occurred in an "increasing" or "decreasing" slope direction
67 * @return the Action that the calling detector should pass back to the evaluation system
68 *
69 */
70 Action eventOccurred(SpacecraftState s, T detector, boolean increasing);
71
72 /** Reset the state prior to continue propagation.
73 * <p>This method is called after the step handler has returned and
74 * before the next step is started, but only when {@link
75 * #eventOccurred} has itself returned the {@link Action#RESET_STATE}
76 * indicator. It allows the user to reset the state for the next step,
77 * without perturbing the step handler of the finishing step. If the
78 * {@link #eventOccurred} never returns the {@link Action#RESET_STATE}
79 * indicator, this function will never be called, and it is safe to simply return null.</p>
80 * <p>
81 * The default implementation simply return its argument.
82 * </p>
83 * @param detector object with appropriate type that can be used in determining correct return state
84 * @param oldState old state
85 * @return new state
86 */
87 default SpacecraftState resetState(T detector, SpacecraftState oldState) {
88 return oldState;
89 }
90
91 }