net.tangly.fsm.Transition Maven / Gradle / Ivy
/*
* Copyright 2006-2023 Marcel Baumann
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
* OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
*
*/
package net.tangly.fsm;
import java.util.function.BiConsumer;
import java.util.function.BiPredicate;
/**
* The transition defines a link between two finite machine states. The class provides an immutable interface on the instances.
*
* @param the class of the instance owning the finite state machine instance
* @param the state enumeration type uniquely identifying a state in the state machine
* @param the event enumeration type uniquely identifying the event sent to the state machine
*/
public interface Transition, E extends Enum> {
/**
* Return the start state or source state of the transition.
*
* @return source state of the transition
*/
State source();
/**
* Return the end state or target state of the transition.
*
* @return end state of the transition
*/
State target();
/**
* Return the identifier of the event triggering the firing of the transition.
*
* @return the identifier of the event
*/
E eventId();
/**
* Return the optional guard restricting the firing of the transition.
*
* @return guard of the transition if defined otherwise null
*/
BiPredicate> guard();
/**
* Indicate if the transition has a guard or not.
*
* @return flag indicating if the transition has a guard
* @see #guard()
*/
default boolean hasGuard() {
return guard() != null;
}
/**
* Return the optional action executed upon firing of the transition.
*
* @return action of the transition if defined otherwise null
*/
BiConsumer> action();
/**
* Indicate if the transition has an action or not.
*
* @return flag indicating if the transition has an action
* @see #action()
*/
default boolean hasAction() {
return action() != null;
}
/**
* Evaluate the event and guard of the transition.
*
* @param context instance owning the finite state machine
* @param event event triggering the transition
* @return true if the transition can be fired otherwise false
*/
boolean evaluate(O context, Event event);
/**
* Execute the action associated with the transition if defined. The action is only executed if the event and guard evaluate to true {@link #evaluate(Object, Event)}.
*
* @param context instance owning the finite state machine
* @param event the event triggering the execution of the action
* @return true if the transition was fired otherwise false
*/
boolean execute(O context, Event event);
/**
* Return the human-readable description of the transition.
*
* @return the description of the transition if defined otherwise null
*/
String description();
/**
* Return the human-readable description of the guard for the transition.
*
* @return the description of the guard for the transition if defined otherwise null
*/
String guardDescription();
/**
* Return the human-readable description of the action for the transition.
*
* @return the description of the action for the transition if defined otherwise null
*/
String actionDescription();
}