com.tangosol.util.fsm.FiniteStateMachine Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of coherence Show documentation
Oracle Coherence Community Edition
There is a newer version: 24.03
/*
 * Copyright (c) 2000, 2020, Oracle and/or its affiliates.
 *
 * Licensed under the Universal Permissive License v 1.0 as shown at
 * http://oss.oracle.com/licenses/upl.
 */
package com.tangosol.util.fsm;

/**
 * A {@link FiniteStateMachine} implements a general purpose finite-state-machine.
 *
 * @param   the type of state of the FiniteStateMachine
 *
 * @see Model
 * @see Transition
 * @see TransitionAction
 * @see StateEntryAction
 *
 * @author Brian Oliver
 * @since Coherence 12.2.1
 */
public interface FiniteStateMachine>
    {
    /**
     * Obtains the name of the {@link FiniteStateMachine}.  This is primarily used for
     * display/logging/monitoring purposes.
     *
     * @return the name of the {@link FiniteStateMachine}
     */
    public String getName();

    /**
     * Request the {@link FiniteStateMachine} to process the specified {@link Event}.
     * 
     * Note: There's no guarantee that the {@link Event} will be processed because:
     * 

     *    the {@link Transition} to be performed for the {@link Event}
     *        is invalid as the {@link FiniteStateMachine} is not in the required
     *        starting state.
     *    
the {@link FiniteStateMachine} may have been stopped.
     * 
     *
     * @param event  the {@link Event} for the {@link FiniteStateMachine} to
     *               process
     */
    public void process(Event event);

    /**
     * Obtains the current state of the {@link FiniteStateMachine}.
     * 
     * Note: After returning the current state there's no guarantee that the state will be the same
     * because a {@link Transition} may be executing asynchronously in the background on another thread.
     *
     * @return  the current state of the {@link FiniteStateMachine}
     */
    public S getState();

    /**
     * Obtains the number of transitions that have occurred in the {@link FiniteStateMachine}.
     * 

     * Note: After returning the count there's no guarantee that the count will be the same on the next request
     * because a {@link Transition} may be executing asynchronously in the background on another thread.
     *
     * @return  the number of transitions that have occurred in the {@link FiniteStateMachine}
     */
    public long getTransitionCount();

    /**
     * Start the {@link FiniteStateMachine} and enter the initial state.
     * 

     * Note: Once stopped a {@link FiniteStateMachine} can't be restarted; instead a
     * new {@link FiniteStateMachine} should be created.
     *
     * @return true if the start was successful or the FiniteStateMachine is already stated,
     * false if it has been stopped
     *
     * @throws IllegalStateException  if the FiniteStateMachine was already stopped
     */
    public boolean start();

    /**
     * Stops the {@link FiniteStateMachine} as soon as possible.
     * 

     * Note: Once stopped a {@link FiniteStateMachine} can't be restarted; instead a new
     * {@link FiniteStateMachine} should be created.
     *
     * @return true if the stop was successful, false if it's already stopped
     *
     * @throws IllegalStateException  if the FiniteStateMachine was never started
     */
    public boolean stop();

    /**
     * Add a {@link FiniteStateMachineListener} to the {@link FiniteStateMachine}.
     * 

     * Note that unique instances of FiniteStateMachineListener are identified
     * via their {@code equals} and {@code hashCode} implementations.
     *
     * @param listener  the listener to be added
     */
    public void addListener(FiniteStateMachineListener listener);

    /**
     * Remove a {@link FiniteStateMachineListener} from the {@link FiniteStateMachine}.
     * 
     * Note that unique instances of FiniteStateMachineListener are identified
     * via their {@code equals} and {@code hashCode} implementations.
     *
     * @param listener  the listener to be removed
     */
    public void removeListener(FiniteStateMachineListener listener);
    }