com.tomgibara.pronto.state
Interface StateGraphEditor<S,L>

Type Parameters:

S - the type of states that the graphs created by this editor contain

L - the type of labels that graphs created by this editor support

All Known Implementing Classes:

StateGraphEditorImpl

public interface StateGraphEditor<S,L>

Instances of this class may be used to define state graphs. Instances are obtained from existing state graphs. An initial editor may be obtained from an empty state graph which is in-turn available from the StateFactory class. An editor may be used after it has produced a graph without modifying the returned graph. In this way, one editor may be used to create multiple different graphs.

Author:

Tom Gibara

Method Summary

boolean	addGraph(StateGraph<S,L> graph) Adds all of the states and transitions from an existing state graph.
boolean	addState(S state) Adds a state to the current graph.
boolean	addStates(java.util.Set<S> states) Adds all the states in the supplied set.
boolean	addTransition(S source, L label, S target) Adds a transition to the current graph.
boolean	addTransition(StateTransition<S,L> transition) Adds a transition to the current graph.
boolean	addTransitions(java.util.Set<StateTransition<S,L>> transitions) Adds all the transitions in the supplied set.
StateGraph<S,L>	getGraph() Creates a new immutable graph instance based on the state of this editor.
boolean	removeMultiPaths(java.util.Set<S> initial, java.util.Set<S> terminal, PathType type) Removes every transition that may occur on any path between any specified initial and terminal state.
boolean	removePaths(S initial, S terminal, PathType type) Removes every transition that may occur on any path between the specified initial and terminal states.
boolean	removeState(S state) Removes a state from the current graph.
boolean	removeStates(java.util.Set<S> states) Removes all the states in the supplied set.
boolean	removeTransition(S source, L label, S target) Removes a transition from the current graph.
boolean	removeTransitions(java.util.Set<StateTransition<S,L>> transitions) Removes all the transitions in the supplied set.
boolean	removeTransitionsLabelled(java.util.Set<L> labels) Removes all the transitions that have a label in the supplied set.
boolean	removeTransitionsMatching(S source, L label, S target) Removes all the transitions which match the specified parameters.
boolean	removeTransitionsOn(S state) Removes all transitions which are incident on (ie.
boolean	retainGraph(StateGraph<S,L> graph) Removes from the current graph all of the states and transitions that are not contained within an existing state graph.
boolean	retainMultiPaths(java.util.Set<S> initial, java.util.Set<S> terminal, PathType type) Restricts the current graph to the smallest subgraph such that it contains every transition that occurs on any path from any specified initial state to any specified terminal state.
boolean	retainPaths(S initial, S terminal, PathType type) Restricts the current graph to the smallest subgraph such that it contains every transition that occurs on any path from the specified initial state to the specified terminal state.
boolean	retainStates(java.util.Set<S> states) Removes all the states that are not in the supplied set.
boolean	retainTransitions(java.util.Set<StateTransition<S,L>> transitions) Removes all the transitions that are not in the supplied set.
boolean	retainTransitionsLabelled(java.util.Set<L> labels) Removes all the transitions that do have a label in the supplied set.
boolean	reverse() Reverses the directionality of every transition in the current graph.
boolean	substituteLabel(L from, L to) Replaces all occurances of one label with another.
boolean	substituteLabels(java.util.Set<L> from, L to) Replaces all the labels in a supplied set with a single label.
boolean	substituteState(S from, S to) Replaces all occurances of one state with another.
boolean	substituteStates(java.util.Set<S> from, S to) Replaces all the states in a supplied set with a single state.

Method Detail

addState

boolean addState(S state)

Adds a state to the current graph.

Parameters:

state - the state to be added

Returns:

true if the graph was modified, false if the graph already contained the state

removeState

boolean removeState(S state)

Removes a state from the current graph. Any transitions incident on the state are also removed.

Parameters:

state - the state to be removed

Returns:

true if the current graph was modified, false if the graph does not contain the state

addTransition

boolean addTransition(StateTransition<S,L> transition)

Adds a transition to the current graph. The supplied transition is cloned (if necessary) and may be from any implementation of this API.

Parameters:

transition - the transition to add to the current graph

Returns:

true if the current graph was modified, false if the graph already contains the transition

addTransition

boolean addTransition(S source,
                      L label,
                      S target)

Adds a transition to the current graph.

Parameters:

source - the source of the transition, not null

label - the label of the transition, not null

target - the target of the transition, not null

Returns:

true if the current graph was modified, false if the graph already contains a matching transition

removeTransition

boolean removeTransition(S source,
                         L label,
                         S target)

Removes a transition from the current graph. The states of the transition are not removed.

Parameters:

source - the source of the transition, not null

label - the label of the transition, not null

target - the target of the transition, not null

Returns:

true if the current graph was modified, false if the graph does not contain a matching transition

removeTransitionsMatching

boolean removeTransitionsMatching(S source,
                                  L label,
                                  S target)

Removes all the transitions which match the specified parameters. The states of the matching transitions are not removed.

Parameters:

source - the required source, or null

label - the required label, or null

target - the required target, or null

Returns:

true if the current graph was modified, false if the graph did not contain any matching transitions

removeTransitionsOn

boolean removeTransitionsOn(S state)

Removes all transitions which are incident on (ie. states which are the source or target) a specified state.

Parameters:

state - the state for which the associated transitions are to be removed, not null

Returns:

true if the current graph was modified, or true if the state has no incident transitions

addStates

boolean addStates(java.util.Set<S> states)

Adds all the states in the supplied set.

Parameters:

states - a set of states, not null

Returns:

true if the current graph was modified, false if the set of graph states contains every state in the set.

removeStates

boolean removeStates(java.util.Set<S> states)

Removes all the states in the supplied set. Any transition that is incident on any state in the set is also removed.

Parameters:

states - a set of states, not null

Returns:

true if the current graph was modified, false if the set of graph states contains no state in the set.

retainStates

boolean retainStates(java.util.Set<S> states)

Removes all the states that are not in the supplied set. Any transition that is incident on any such state is also removed.

Parameters:

states - a set of states, not null

Returns:

true if the current graph was modified, false if the set states contains every state in the graph.

addTransitions

boolean addTransitions(java.util.Set<StateTransition<S,L>> transitions)

Adds all the transitions in the supplied set.

Parameters:

transitions - a set of transitions, not null

Returns:

true if the current graph was modified, false if the set of graph transitions contains every transition in the set.

removeTransitions

boolean removeTransitions(java.util.Set<StateTransition<S,L>> transitions)

Removes all the transitions in the supplied set. No states are removed.

Parameters:

transitions - a set of transitions, not null

Returns:

true if the current graph was modified, false if the set of graph transitions contains no transition in the set.

retainTransitions

boolean retainTransitions(java.util.Set<StateTransition<S,L>> transitions)

Removes all the transitions that are not in the supplied set. No states are removed.

Parameters:

transitions - a set of transitions, not null

Returns:

true if the current graph was modified, false if the set transitions contains every transition in the graph.

removeTransitionsLabelled

boolean removeTransitionsLabelled(java.util.Set<L> labels)

Removes all the transitions that have a label in the supplied set.

Parameters:

labels - the set of labels to be expunged from the current graph

Returns:

true if the current graph was modified, false if no transition is labelled with any label from the supplied set

retainTransitionsLabelled

boolean retainTransitionsLabelled(java.util.Set<L> labels)

Removes all the transitions that do have a label in the supplied set.

Parameters:

labels - the set of labels to be retained

Returns:

true if the current graph was modified, false if every transition is labelled with a label from the supplied set

addGraph

boolean addGraph(StateGraph<S,L> graph)

Adds all of the states and transitions from an existing state graph. The supplied graph is permitted to be from another implementation of this API. This method can be expected to be quicker than adding the graph's states and transitions independently.

Parameters:

graph - the graph to be added to this graph

Returns:

true if the current graph was modified, false if the supplied graph is a subset of the current graph

retainGraph

boolean retainGraph(StateGraph<S,L> graph)

Removes from the current graph all of the states and transitions that are not contained within an existing state graph. The supplied graph is permitted to be from another implementation of this API. This method can be expected to be quicker than retaining the graph's states and transitions independently.

Parameters:

graph - the graph which is to be retained by the current graph

Returns:

true if the current graph was modified, false if this graph is a subset of the supplied graph

substituteState

boolean substituteState(S from,
                        S to)

Replaces all occurances of one state with another. This is a convenience method that performs the same function as substituteStates does with a singleton set.

Parameters:

from - the state to be replaced

to - the state which replaces the existing state

Returns:

true if the current graph was modified, false if the state to be replaced is not a state in the graph

substituteStates

boolean substituteStates(java.util.Set<S> from,
                         S to)

Replaces all the states in a supplied set with a single state. This has the effect of converting any transition on any state in the set into a transition on the replacement state. The states in the set are removed from the current graph. The replacement state is permitted to be a member of the supplied set in which case that state is naturally preserved.

Parameters:

from - a set of states to be replaced

to - the state which replaces all states in the supplied set

Returns:

true if the current graph was modifed, false otherwise

substituteLabel

boolean substituteLabel(L from,
                        L to)

Replaces all occurances of one label with another. This is a convenience method that performs the same function as substituteLabels does with a singleton set.

Parameters:

from - the label to be replaced

to - the label which replaces the existing label

Returns:

true if the current graph was modified, false if no transition had the specified label

substituteLabels

boolean substituteLabels(java.util.Set<L> from,
                         L to)

Replaces all the labels in a supplied set with a single label. In the event that two transitions are differ only by their labels, both of which are in the supplied set, the two transitions will be replaced by a single transition.

Parameters:

from - a set of labels to be replaced

to - the label which replaces all labels in the supplied set

Returns:

true if the current graph was modifed, false otherwise

reverse

boolean reverse()

Reverses the directionality of every transition in the current graph. Circular transitions (those for which the target equals the source) are naturally unchanged.

Returns:

true if current graph was modified, false otherwise

removePaths

boolean removePaths(S initial,
                    S terminal,
                    PathType type)

Removes every transition that may occur on any path between the specified initial and terminal states. The states supplied to this method do not need to be from the set of initial/terminal states of the current graph. No states are removed.

Parameters:

initial - the state from which each paths begins

terminal - the state at which each path ends

type - a constraint on the paths

Returns:

true if the current graph was modified, false if there was no path between the initial and final states

removeMultiPaths

boolean removeMultiPaths(java.util.Set<S> initial,
                         java.util.Set<S> terminal,
                         PathType type)

Removes every transition that may occur on any path between any specified initial and terminal state. The states supplied to this method do not need to be from the set of initial/terminal states of the current graph. No states are removed.

Parameters:

initial - the states from which the path begins

terminal - the state at which the paths end

type - a constraint on the paths

Returns:

true if the current graph was modified, false if there was no path between any of the initial and final states

retainPaths

boolean retainPaths(S initial,
                    S terminal,
                    PathType type)

Restricts the current graph to the smallest subgraph such that it contains every transition that occurs on any path from the specified initial state to the specified terminal state. The states supplied to this method do not need to be from the set of initial/terminal states of the current graph. Note that the resulting graph may not contain the specified states (in which case it is empty) if no paths exist between the two states. Nor are the specified states guaranteed to be initial/terminal states in the new graph.

Parameters:

initial - the state from which all paths begin

terminal - the state at which all paths end

type - a constraint on the paths

Returns:

true if the current graph was modified, false otherwise

retainMultiPaths

boolean retainMultiPaths(java.util.Set<S> initial,
                         java.util.Set<S> terminal,
                         PathType type)

Restricts the current graph to the smallest subgraph such that it contains every transition that occurs on any path from any specified initial state to any specified terminal state. The states supplied to this method do not need to be from the set of initial/terminal states of the current graph. Note that the resulting graph may not contain the all of the specified states. Nor are the specified states guaranteed to be initial/terminal states in the new graph.

Parameters:

initial - the states from which any path must begin

terminal - the states at which any paths must end

type - a constraint on the paths

Returns:

true if the current graph was modified, false otherwise

getGraph

StateGraph<S,L> getGraph()

Creates a new immutable graph instance based on the state of this editor. This method may be called any number of times on the same editor. The returned graph is unaffected by subsequent changes made to this editor.

Returns:

a graph instances based on the current state of this editor.