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

Type Parameters:

S - the type of states in this graph

L - the type of transition labels in this graph

All Known Implementing Classes:

StateGraphImpl

public interface StateGraph<S,L>

A state graph consists of a set of states and a set of transitions between them. StateGraph instances are immutable and are safe for concurrent use. Modifying a graph is performed by obtaining an editor from the graph. There is no requirement that the graph be disconnected nor is the graph required to be acyclic.

Author:

Tom Gibara

Method Summary

S	getInitialState() The single initial state.
java.util.Set<S>	getInitialStates() An immutable set of the states that are not the target of any transition.
java.util.Set<java.util.List<StateTransition<S,L>>>	getMultiPaths(java.util.Set<S> initial, java.util.Set<S> terminal, PathType type) A set containing every possible path (represented as a list of transitions) from any initial state to any terminal state.
java.util.List<StateTransition<S,L>>	getPath(S initial, S terminal, PathType type) A convenience method that may be called to obtain the single existing path from an initial state to a terminal state.
java.util.Set<java.util.List<StateTransition<S,L>>>	getPaths(S initial, S terminal, PathType type) A set containing every possible path (represented as a list of transitions) from the initial state to the terminal state.
S	getTerminalState() The single terminal state.
java.util.Set<S>	getTerminalStates() An immutable set of the states that are not the source of any transition.
StateTransition<S,L>	getTransition(S source, L label, S target) Obtains the specified state transition from this graph.
java.util.Set<StateTransition<S,L>>	getTransitionsMatching(S source, L label, S target) Returns an immutable set of all transitions that match the supplied parameters.
StateGraphEditor<S,L>	newEditor() Obtains an editor which may be used to edit a copy of this graph.
java.util.Set<S>	states() The set of states in this graph.
java.util.Set<StateTransition<S,L>>	transitions() An immutable set containing every transition in the graph.

Method Detail

states

java.util.Set<S> states()

The set of states in this graph. The presence of a state in this set does not guarantee that there is a transition on that state.

Returns:

the set of states, may be empty

getTerminalStates

java.util.Set<S> getTerminalStates()

An immutable set of the states that are not the source of any transition.

Returns:

the set of terminal states, may be empty.

getTerminalState

S getTerminalState()
                   throws ProntoStateException

The single terminal state. This is a convenience method for situations where the client code knows that there is at most one terminal state.

Returns:

the single terminal state or null

Throws:

ProntoStateException - if there is more than terminal state

getInitialStates

java.util.Set<S> getInitialStates()

An immutable set of the states that are not the target of any transition.

Returns:

the set of initial states, may be empty

getInitialState

S getInitialState()
                  throws ProntoStateException

The single initial state. This is a convenience method for situations where the client code knows that there is at most one initial state.

Returns:

the single initial state or null

Throws:

ProntoStateException - if there is more than initial state

getTransition

StateTransition<S,L> getTransition(S source,
                                   L label,
                                   S target)

Obtains the specified state transition from this graph. To match multiple transitions use the getTransitionsMatching method.

Parameters:

source - the source of the transition, not null

label - the transition's label, not null

target - the target of the transition, not null

Returns:

the state transition in this graph with the exact source, label and target supplied, or null

getTransitionsMatching

java.util.Set<StateTransition<S,L>> getTransitionsMatching(S source,
                                                           L label,
                                                           S target)

Returns an immutable set of all transitions that match the supplied parameters. Supplying null for every parameter results in every transition being returned.

Parameters:

source - the required transition source, or null to match any source

label - the required transition label, or null to match any label

target - the required transition target, or null to match any target

Returns:

an immutable set of the matching transitions

transitions

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

An immutable set containing every transition in the graph.

Returns:

an immutable set containing every transition in the graph

getPath

java.util.List<StateTransition<S,L>> getPath(S initial,
                                             S terminal,
                                             PathType type)
                                             throws ProntoStateException

A convenience method that may be called to obtain the single existing path from an initial state to a terminal state. If no path exists null is returned. If a null terminal state is supplied then the single path originating from the initial state is returned.

Parameters:

initial - the state at which path begins, not null

terminal - the state at which path terminates, may be null

type - a constraint on the path

Returns:

the single path from an initial state to a terminal state, or null

Throws:

ProntoStateException - if there is more than one path between an initial state and a terminal state

getPaths

java.util.Set<java.util.List<StateTransition<S,L>>> getPaths(S initial,
                                                             S terminal,
                                                             PathType type)

A set containing every possible path (represented as a list of transitions) from the initial state to the terminal state. Paths may contain cycles but cannot be empty. If a null terminal state is supplied then all paths originating from the initial state are returned.

Parameters:

initial - the state at which paths begin, not null

terminal - the state at which paths terminate, may be null

type - a constraint on the paths

Returns:

an immutable set of the paths from initial states to terminal states

getMultiPaths

java.util.Set<java.util.List<StateTransition<S,L>>> getMultiPaths(java.util.Set<S> initial,
                                                                  java.util.Set<S> terminal,
                                                                  PathType type)

A set containing every possible path (represented as a list of transitions) from any initial state to any terminal state. Paths may contain cycles but cannot be empty. If a null terminal set is supplied then all paths originating from the initial set are returned.

Parameters:

initial - the states at which paths begin, not null

terminal - the states at which paths terminate, may be null

type - a constraint on the paths

Returns:

an immutable set of the paths from initial states to terminal states

newEditor

StateGraphEditor<S,L> newEditor()

Obtains an editor which may be used to edit a copy of this graph. A new editor is returned on each call to this method.

Returns:

an editor over this graph.