Module PauWareTwo
Package com.pauware.pauware_engine.Core

Class AbstractStateMachine

java.lang.Object
com.pauware.pauware_engine.Core.AbstractState
com.pauware.pauware_engine.Core.AbstractStateMachine
All Implemented Interfaces:
Manageable, Manageable_base
Direct Known Subclasses:
StateMachine
public abstract class AbstractStateMachine
extends AbstractState
implements Manageable
This abstract class represents the general notion of State Machine in UML. Use of this class occurs through the following subclass: StateMachine.

Compatibility: Java 9.

Since:
1.0

  • Field Details

    • Don_t_compute_invariants

      public static final boolean Don_t_compute_invariants
      This class variable is a constant value that disactivates the calculation of state invariants.
      See Also:
      run_to_completion(String,boolean), Constant Field Values

    • Compute_invariants

      public static final boolean Compute_invariants
      This class variable is a constant value that activates the calculation of state invariants.
      See Also:
      run_to_completion(String,boolean), Constant Field Values

    • Don_t_show_on_system_out

      public static final boolean Don_t_show_on_system_out
      This class variable is a constant value which represents the fact that the verbose mode for event processing is not activated.
      See Also:
      AbstractStateMachine(AbstractState,String,boolean), Constant Field Values

    • Show_on_system_out

      public static final boolean Show_on_system_out
      This class variable is a constant value which represents the fact that the verbose mode for event processing is activated.
      See Also:
      AbstractStateMachine(AbstractState,String,boolean), Constant Field Values

    • _show_on_system_out

      protected boolean _show_on_system_out
      This field records the chosen verbose mode associated with the state machine.
      See Also:
      Don_t_show_on_system_out, Show_on_system_out

    • _execution

      protected java.util.Map<Transition,​java.lang.Object[]> _execution
      This field represents all of the eligible transitions of a given run-to-completion cycle. This Map instance is empty at the beginning of a run-to-completion cycle.

    • _eliminated_transitions

      protected java.util.Vector<Transition> _eliminated_transitions
      This field records, during a run-to-completion cycle, the transitions to be eliminated. Eliminated transitions are the transitions overridden by other similar ones bound to substates. They are also those inhibited by allowed events.

    • _transitions

      protected java.util.Map<Transition,​java.util.Map<java.lang.String,​java.util.Map<AbstractGuard,​java.util.Vector<AbstractAction>>>> _transitions
      This field represents all of the cached transitions of the state machine.

    • _listeners

      protected java.util.ArrayList<AbstractStateMachine_listener> _listeners
      This field records listeners, if any, for the software component that owns the state machine.

    • _Undefined

      protected static final java.lang.String _Undefined
      This class variable is a constant value which represents the fact that the state machine's current state is not yet defined.
      See Also:
      in_state(String), Constant Field Values

    • _current_state

      protected java.lang.String _current_state
      This field records the state of a state machine computed within of a run-to-completion step.
      See Also:
      Manageable_base.async_current_state(), Manageable_base.current_state()

    • _verbose

      protected java.lang.StringBuffer _verbose
      This field records the result of an event occurrence processing within a run-to-completion step.
      See Also:
      Don_t_show_on_system_out, Show_on_system_out

  • Constructor Details

    • AbstractStateMachine

      protected AbstractStateMachine()
      This constructor creates a father for two composed AbstractStateMachine instances.
      Since:
      ver. 1.2
      See Also:
      AbstractState.createFather()

    • AbstractStateMachine

      public AbstractStateMachine​(AbstractState s, java.lang.String name) throws State_exception
      This constructor amounts to calling AbstractStateMachine(s,name,AbstractStateMachine.Don_t_show_on_system_out). It supports the composition of AbstractStateMachine instances (a.k.a.vertical composition) since ver. 1.2.
      Parameters:
      s -
      name -
      Throws:
      State_exception

    • AbstractStateMachine

      public AbstractStateMachine​(AbstractState s, java.lang.String name, boolean show_on_system_out) throws State_exception
      This constructor first creates and initializes a state machine; It next triggers all entry actions associated with all the explicit and implicit default input states of the state machine. Running this constructor therefore implies that all resources, used by the state machine in entry actions, are available and in an appropriate status. Use of this class occurs through the following subclass: StateMachine. Example of a user-defined Stack software component:


      AbstractStateMachine _Stack;
      ...
      _Stack = new StateMachine(_Empty.xor(_Not_empty),"Stack");

      Parameters:
      s - A state object resulting from a XOR-based state composition or an AND-based state composition
      name - A name assigned to the state machine. The name of the software component type running this state machine is preferred for this parameter
      show_on_system_out - If true, this parameter activates the verbose mode of a run-to-completion cycle (for tests only)
      Throws:
      State_exception

    • AbstractStateMachine

      public AbstractStateMachine​(AbstractState s, java.lang.String name, boolean show_on_system_out, AbstractStateMachine_listener listener) throws State_exception
      This constructor amounts to calling AbstractStateMachine(s,name,show_on_system_out) plus the definition of a state machine's listener.
      Parameters:
      s -
      name -
      show_on_system_out -
      listener - The state machine's listener is first initialized in receiving the state machine itself (for display purposes for instance) Next, it is informed of the state machine's status changes at the time when each run-to-completion cycle is finished.
      Throws:
      State_exception
      See Also:
      AbstractStateMachine(AbstractState,String,boolean), add_listener(AbstractStateMachine_listener)

    • AbstractStateMachine

      public AbstractStateMachine​(AbstractState s, java.lang.String name, boolean show_on_system_out, AbstractStateMachine_listener listener1, AbstractStateMachine_listener listener2) throws State_exception
      Doc. required
      Throws:
      State_exception

  • Method Details

    • add_listener

      public void add_listener​(AbstractStateMachine_listener listener) throws State_exception
      This method adds a listener to the state machine; this method MUST be called AFTER the state machine has started. A typical use of this method is when a viewer is added in order to graphically simulate a state machine as follows: _Programmable_thermostat.add_listener(new com.pauware.PauWare2Web.PauWare2Web_client());
      Parameters:
      listener -
      Throws:
      State_exception
      See Also:
      start(), remove_listener(AbstractStateMachine_listener)

    • remove_listener

      public void remove_listener​(AbstractStateMachine_listener listener) throws State_exception
      This method removes a listener of the state machine; this method MUST be called BEFORE the state machine has stopped.
      Parameters:
      listener -
      Throws:
      State_exception
      See Also:
      stop(), add_listener(AbstractStateMachine_listener)

    • completion

      public void completion() throws State_exception
      Completion transitions (i.e., those without any event label) are automatically triggered when reaching output states.
      Throws:
      State_exception
      Since:
      ver. 1.3

    • activate

      protected void activate​(AbstractState from, AbstractState to, java.lang.StringBuffer verbose) throws State_exception
      Internal use only; This method is called during a run-to-completion cycle.
      Parameters:
      from -
      to -
      verbose -
      Throws:
      State_exception
      See Also:
      run_to_completion(String,boolean)

    • disactivate

      protected void disactivate​(AbstractState from, AbstractState to, java.lang.StringBuffer verbose) throws State_exception
      Internal use only; This method is called during a run-to-completion cycle.
      Throws:
      State_exception
      See Also:
      run_to_completion(String,boolean)

    • root

      public boolean root()
      This method answers the question: is this state the most outer state of the state machine? The answer is always true for an instance of the AbstractStateMachine type.
      Overrides:
      root in class AbstractState
      Returns:

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,true);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, boolean guard) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard,null,null);.
      Parameters:
      event -
      from -
      to -
      guard -
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, boolean guard, java.lang.Object object, java.lang.String action) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard,object,action,null);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, boolean guard, java.lang.Object object, java.lang.String action, java.lang.Object[] args) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard,object,action,args,AbstractState.No_reentrance);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, boolean guard, java.lang.Object object, java.lang.String action, java.lang.Object[] args, byte reentrance_mode) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,null,"true",object,action,args,reentrance_mode); if guard is true, fires(event,from,to,null,"false",object,action,args,reentrance_mode); otherwise.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,null,null);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object[] guard_args) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,guard_args,null,null,null);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object object, java.lang.String action) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,object,action,null);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object[] guard_args, java.lang.Object object, java.lang.String action) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,guard_args,object,action,null);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object object, java.lang.String action, java.lang.Object[] args) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,null,object,action,args,AbstractState.No_reentrance);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object[] guard_args, java.lang.Object object, java.lang.String action, java.lang.Object[] args) throws Transition_based_exception
      This method amounts to calling fires(event,from,to,guard_object,guard_action,guard_args,object,action,args,AbstractState.No_reentrance);.
      Throws:
      Transition_based_exception

    • fires

      public void fires​(java.lang.String event, AbstractState from, AbstractState to, java.lang.Object guard_object, java.lang.String guard_action, java.lang.Object[] guard_args, java.lang.Object object, java.lang.String action, java.lang.Object[] args, byte reentrance_mode) throws Transition_based_exception
      This method creates and registers (caches) a transition labeled with an event name in a state machine (see: UML State Machine Diagrams formalism).
      Parameters:
      event - The name of the event labeling the transition
      from - The state being the origin of the transition
      to - The state being the end of the transition
      guard_object - The object in charge of executing the guard (if any)
      guard_action - The name of the action to be executed in order to establish the guard's evaluation; This is required * * * * * * * * * * * if guard_object is used
      guard_args - The arguments (if any) of the action which represents the guard
      object - The object in charge of executing the action, if any, triggered by the event; Multiple actions require multiple use of this method
      action - The name of the action to be executed; This is required * if object is used
      args - The arguments of the action to be executed * * * * * * * * * or null
      reentrance_mode - A flag value which is equal to AbstractState.Reentrance or AbstractState.No_reentrance; This value enables or disables the reentrance_mode mode of communication for the action to be executed
      Throws:
      Transition_based_exception

    • unfires

      public void unfires​(java.lang.String event, AbstractState from, AbstractState to, boolean guard, java.lang.Object object, java.lang.String action, java.lang.Object[] args, byte reentrance_mode) throws Transition_based_exception
      This method unregisters a transition labeled with an event name in a state machine (see: UML State Machine Diagrams formalism).
      Parameters:
      event - The name of the event labeling the transition
      from - The state being the origin of the transition
      to - The state being the end of the transition
      guard - Only simple guards are supported at this time
      object - The object in charge of executing the action, if any, triggered by the event; Multiple actions require multiple use of this method
      action - The name of the action to be executed; This is required * if object is used
      args - The arguments of the action to be executed * * * * * * * * * or null
      reentrance_mode - A flag value which is equal to AbstractState.Reentrance or AbstractState.No_reentrance; This value enables or disables the reentrance_mode mode of communication for the action to be executed
      Throws:
      Transition_based_exception

    • run_to_completion

      public void run_to_completion​(java.lang.String event) throws State_exception
      This method amounts to calling run_to_completion(event,AbstractStateMachine.Don_t_compute_invariants);
      Parameters:
      event -
      Throws:
      State_exception

    • run_to_completion

      public void run_to_completion​(java.lang.String event, boolean compute_invariants) throws State_exception
      This method is the key mechanism of the PauWare software; It moves a state machine from one stable consistent context to another.
      Parameters:
      event - The name of the event to be processed (null means no effect); Only transitions labeled and registered with this event name are processed (see: the fires(String,AbstractState,AbstractState,Object,String,Object[],Object,String,Object[],byte) method)
      compute_invariants - This mode triggers the calculation of invariants
      Throws:
      State_exception

    • start

      public void start() throws State_exception
      This method launches a state machine.
      Throws:
      State_exception

    • stop

      public void stop() throws State_exception
      This method stops a state machine.
      Throws:
      State_exception

    • async_current_state

      public java.lang.String async_current_state()
      Management facility: this method is offered by a software component, which implements the Manageable_base interface.
      Specified by:
      async_current_state in interface Manageable_base
      Returns:

    • in_state

      public boolean in_state​(java.lang.String name)
      Management facility: this method is offered by a software component, which implements the Manageable_base interface.
      Specified by:
      in_state in interface Manageable_base
      Returns:
      See Also:
      Manageable_base

    • to_state

      public void to_state​(java.lang.String name) throws State_exception
      Management facility: this method is offered by a software component, which implements the Manageable_base interface.
      Specified by:
      to_state in interface Manageable
      Parameters:
      name - The name of the state to which the state machine goes to.
      Throws:
      State_exception
      See Also:
      AbstractState.set_entryAction(Object,String,Object[],byte), AbstractState.set_exitAction(Object,String,Object[],byte), AbstractState.reset_entryAction(Object,String,Object[],byte), AbstractState.reset_exitAction(Object,String,Object[],byte)

    • verbose

      public java.lang.String verbose()
      Management facility: this method is offered by a software component, which implements the Manageable_base interface.
      Specified by:
      verbose in interface Manageable_base
      Returns:

    • equals

      public boolean equals​(java.lang.Object s)
      This method is used when an AbstractStateMachine is put in a map data structure as a key.
      Overrides:
      equals in class java.lang.Object
      Parameters:
      s -

    • hashCode

      public int hashCode()
      This method is used when an AbstractStateMachine is put in a map data structure as a key.
      Overrides:
      hashCode in class java.lang.Object

    • to_UML

      public java.lang.String to_UML​(java.lang.String event, Transition transition, AbstractGuard guard)
      For visualization purposes only: this method may be used by the PauWare2Web tool.
      Parameters:
      event -
      transition -
      guard -
      Returns:

    • to_PlantUML

      public java.lang.String to_PlantUML()
      For visualization purposes only: this method is used by the PauWare2Web tool to compute the state machine's visualization graph.
      Returns:
      Since:
      ver. 1.3