src/main/java/org/apache/commons/scxml2/model/TransitionalState.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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 org.apache.commons.scxml2.model;

import java.util.ArrayList;
import java.util.List;

/**
 * An abstract base class for state elements in SCXML that can be transitioned out from, such as State or Parallel.
 */
public abstract class TransitionalState extends EnterableState {

    /**
     * A list of outgoing Transitions from this state, by document order.
     */
    private List<Transition> transitions;

    /**
     * Optional property holding the data model for this state.
     */
    private Datamodel datamodel;

    /**
     * List of history states owned by a given state (applies to non-leaf
     * states).
     */
    private List<History> history;

    /**
     * The Invoke children, each which defines an external process that should
     * be invoked, immediately after the onentry executable content,
     * and the transitions become candidates after the invoked
     * process has completed its execution.
     * May occur 0 or more times.
     */
    private List<Invoke> invokes;

    /**
     * The set of EnterableState children contained in this TransitionalState
     */
    private List<EnterableState> children;

    public TransitionalState() {
        super();
        transitions = new ArrayList<Transition>();
        history = new ArrayList<History>();
        children = new ArrayList<EnterableState>();
        invokes = new ArrayList<Invoke>();
    }

    /**
     * Update TransitionTarget descendants their ancestors
     */
    protected void updateDescendantsAncestors() {
        super.updateDescendantsAncestors();
        for (History h : history) {
            // reset ancestors
            h.updateDescendantsAncestors();
        }
        for (TransitionTarget child : children) {
            child.updateDescendantsAncestors();
        }
    }

    /**
     * Get the TransitionalState (State or Parallel) parent.
     *
     * @return Returns the parent.
     */
    @Override
    public TransitionalState getParent() {
        return (TransitionalState)super.getParent();
    }

    /**
     * Set the TransitionalState parent
     *
     * @param parent The parent to set.
     */
    public final void setParent(final TransitionalState parent) {
        super.setParent(parent);
    }

    /**
     * Get the ancestor of this TransitionalState at specified level
     * @param level the level of the ancestor to return, zero being top
     * @return the ancestor at specified level
     */
    @Override
    public TransitionalState getAncestor(int level) {
        return (TransitionalState)super.getAncestor(level);
    }

    /**
     * Get the list of all outgoing transitions from this state, that
     * will be candidates for being fired on the given event.
     *
     * @param event The event
     * @return List Returns the candidate transitions for given event
     */
    public final List<Transition> getTransitionsList(final String event) {
        List<Transition> matchingTransitions = null; // since we returned null upto v0.6
        for (Transition t : transitions) {
            if ((event == null && t.getEvent() == null)
                    || (event != null && event.equals(t.getEvent()))) {
                if (matchingTransitions == null) {
                    matchingTransitions = new ArrayList<Transition>();
                }
                matchingTransitions.add(t);
            }
        }
        return matchingTransitions;
    }

    /**
     * Add a transition to the map of all outgoing transitions for
     * this state.
     *
     * @param transition
     *            The transitions to set.
     */
    public final void addTransition(final Transition transition) {
        transitions.add(transition);
        transition.setParent(this);
    }

    /**
     * Get the outgoing transitions for this state as a java.util.List.
     *
     * @return List Returns the transitions list.
     */
    public final List<Transition> getTransitionsList() {
        return transitions;
    }

    /**
     * Get the data model for this transition target.
     *
     * @return Returns the data model.
     */
    public final Datamodel getDatamodel() {
        return datamodel;
    }

    /**
     * Set the data model for this transition target.
     *
     * @param datamodel The Datamodel to set.
     */
    public final void setDatamodel(final Datamodel datamodel) {
        this.datamodel = datamodel;
    }

    /**
     * @param h History pseudo state
     *
     * @since 0.7
     */
    public final void addHistory(final History h) {
        history.add(h);
        h.setParent(this);
    }

    /**
     * Does this state have a history pseudo state.
     *
     * @return boolean true if a given state contains at least one
     *                 history pseudo state
     *
     * @since 0.7
     */
    public final boolean hasHistory() {
        return (!history.isEmpty());
    }

    /**
     * Get the list of history pseudo states for this state.
     *
     * @return a list of all history pseudo states contained by a given state
     *         (can be empty)
     * @see #hasHistory()
     *
     * @since 0.7
     */
    public final List<History> getHistory() {
        return history;
    }

    /**
     * Get the Invoke children (may be empty).
     *
     * @return Invoke Returns the invoke.
     */
    public final List<Invoke> getInvokes() {
        return invokes;
    }

    /**
     * Set the Invoke child.
     *
     * @param invoke
     *            The invoke to set.
     */
    public final void addInvoke(final Invoke invoke) {
        this.invokes.add(invoke);
        invoke.setParentEnterableState(this);
    }

    /**
     * Get the set of child transition targets (may be empty).
     *
     * @return Returns the children.
     *
     * @since 0.7
     */
    public final List<EnterableState> getChildren() {
        return children;
    }

    /**
     * Add a child.
     *
     * @param es A child enterable state.
     *
     * @since 0.7
     */
    protected void addChild(final EnterableState es) {
        children.add(es);
        es.setParent(this);
    }
}