org.mobicents.commons.fsm.FiniteStateMachine Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-fsm Show documentation
There is a newer version: 1.0.139
/*
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.mobicents.commons.fsm;

import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;

import org.mobicents.commons.annotations.NotThreadSafe;
import org.mobicents.commons.event.Event;

/**
 * @author [email protected] (Thomas Quintana)
 */
@NotThreadSafe public abstract class FiniteStateMachine {
  private final Lock lock;
  private State state;
  private Map> transitions;
  
  protected FiniteStateMachine() {
    super();
    this.lock = new ReentrantLock();
  }
  
  private boolean canTransitionTo(final State state) {
    return transitions.get(this.state).containsKey(state);
  }
  
  private void checkIsInitialized() throws FiniteStateMachineException {
    if(state == null || transitions == null) {
      final StringBuilder buffer = new StringBuilder();
      buffer.append("The finite state machine has not been initialized. ");
      buffer.append("Please initialize the state machine before using it.");
      throw new FiniteStateMachineException(buffer.toString());
    }
  }
  
  private void checkNotNull(final State state) throws NullPointerException {
    if(state == null) {
      final StringBuilder buffer = new StringBuilder();
      buffer.append("The state parameter can not be null. ");
      buffer.append("Please provide a usable state and try again.");
      throw new NullPointerException(buffer.toString());
    }
  }
  
  private void checkNotNull(final State state, final Set transitions)
      throws NullPointerException {
    checkNotNull(state);
    if(transitions == null) {
      final StringBuilder buffer = new StringBuilder();
      buffer.append("The transitions parameter can not be null. ");
      buffer.append("Please provide a set of transitions and try again.");
      throw new NullPointerException(buffer.toString());
    }
  }
  
  private String conditionFailed(final Event event, final Transition transition) {
    final StringBuilder buffer = new StringBuilder();
    buffer.append("The condition guarding a transition from a(n) ");
    buffer.append(transition.getStateOnEnter().getId());
    buffer.append(" state to a(n) ").append(transition.getStateOnExit().getId());
    buffer.append(" state has failed. The event type that caused the failure is of type ");
    buffer.append(event.getType().getClass().getName());
    return buffer.toString();
  }
  
  private String finiteStateMachineFailed() {
    final StringBuilder buffer = new StringBuilder();
    buffer.append("This finite state machine failed. It may be in an illegal or unusable state.");
    buffer.append("Please re-initialize before continuing use of this finite state machine.");
    return buffer.toString();
  }
  
  protected State getState() {
    lock();
    try {
      return state;
    } finally {
      unlock();
    }
  }
  
  private Transition getTransitionTo(final State state) {
    return transitions.get(this.state).get(state);
  }
  
  protected void initialize(final State state, final Set transitions) {
    checkNotNull(state, transitions);
    lock();
    try {
      this.state = state;
      this.transitions = toImmutableMap(transitions);
    } finally {
      unlock();
    }
  }
  
  protected void lock() {
    lock.lock();
  }
  
  private String noTransitionFound(final State from, final State to) {
    final StringBuilder buffer = new StringBuilder();
    buffer.append("No transition could be found from a(n) ");
    buffer.append(from.getId()).append(" state to a(n) ");
    buffer.append(to.getId()).append(" state.");
    return buffer.toString();
  }
  
  protected  void transition(final Event event, final State state)
      throws FiniteStateMachineException, NullPointerException,
      TransitionFailedException, TransitionNotFoundException {
    checkNotNull(state);
    checkIsInitialized();
    lock();
    try {
      if(!canTransitionTo(state)) {
        final String message = noTransitionFound(this.state, state);
        throw new TransitionNotFoundException(message, event, state);
      }
      final Transition transition = getTransitionTo(state);
      final Condition condition = transition.getCondition();
      boolean accept = true;
      if(condition != null) {
        accept = condition.accept(event, transition);
      }
      if(accept) {
        final Action actionOnExit = this.state.getActionOnExit();
        if(actionOnExit != null) {
          actionOnExit.execute(event, this.state);
        }
        this.state = state;
        final Action actionOnEnter = this.state.getActionOnEnter();
        if(actionOnEnter != null) {
          actionOnEnter.execute(event, this.state);
        }
      } else {
        final String message = conditionFailed(event, transition);
        throw new TransitionFailedException(message, event, transition);
      }
    } catch(final RuntimeException exception) {
      final String message = finiteStateMachineFailed();
      throw new FiniteStateMachineException(message, exception);
    } finally {
      unlock();
    }
  }
  
  private Map> toImmutableMap(final Set transitions) {
    final Map> map = new HashMap>();
    for(final Transition transition : transitions) {
      final State stateOnEnter = transition.getStateOnEnter();
      if(!map.containsKey(stateOnEnter)) {
        map.put(stateOnEnter, new HashMap());
      }
      final State stateOnExit = transition.getStateOnExit();
      map.get(stateOnEnter).put(stateOnExit, transition);
    }
    return Collections.unmodifiableMap(map);
  }
  
  protected boolean tryLock() {
    return lock.tryLock();
  }
  
  protected void unlock() {
    lock.unlock();
  }
}