Solstice::State::Machine - Representation of a finite state machine for Solstice. See Solstice::State::Tracker to run through a state machine.


use Solstice::State::Machine;

my $machine = new Solstice::State::Machine();


This is the main state machine representation for the Solstice tools. The Solstice::State::Tracker uses this representation to keep track of state. A Solstice::State::Machine's data is stored only once in the main apache thread via Solstice::Service::Memory;


No symbols exported.



Creates a new Solstice::State::Machine object.

returns - a new state machine object.


Initializes the state machine using the XML files given.

$xmlFiles - a reference to a hash of XML filenames.


Builds the state graph from the XML file.

$xmlFile - the path to the xml file.

returns - whether successful.

_fullyQualify($name, [$namespace])

Fully qualifies a state or flow name by prefixing it with the application namespace.


Given the parsed XML node for the states section of the Xml file, create and store the corresponding State objects.

$xmlNode - the XML node to load from.


Loads the page flows that this application exposes from the $xmlNode.

$xmlNode - the XML node to load from.

_loadTransition($pageflow, $transition_start, $xmlNode)

Loads a single transition from the $xmlNode.

$pageflow - the page flow to add the transition to. $transition_start - the start state of the transition. $xmlNode - the XML to load from.

_loadPageFlowInclude($pageflow, $transition_start, $xmlNode)

Loads a page flow include and adds it to the $pageflow

$pageflow - the page flow to include the page flow include into. $transition_start - the start state of the transition that takes you to the new flow. $xmlNode - the XML node to load from.

_loadFailovers($state, $xmlNode)

Loads the failovers for a given state out of the Xml node.

$pageflow - the pageflow object to put the failovers in. $state - the name of the state to load the failovers for. $xmlNode - the Xml node to load from.


$stateName - the name of the state.

returns - whether the state exists in the machine.

_addState($stateName, $controller)

Adds a state to the machine.

$stateName - the name of the state to add. $controller - the controller for the state.


Gets the Solstice::State::Node object by name.

$stateName - the name of the state to return.

returns - the state with the given $stateName.


Adds a page flow to the machine.

transition($flow, $state, $action)

Gets the target state given a page flow, an initial state, and a transition action from it.

$flow - the page flow to use. $state - the state name to transition from. $action - the transition to take.

returns - ($do_pop, $new_flow, $new_state)

$do_pop - whether the transition exited a flow. $new_flow - the new flow. $new_state - the new state.


Gets the main page flow for the machine.


Gets the start state for an application.


Gets the page flow given the app namespace and its name.


Gets a reference to a hash of all the page flows.


Parses the XML file.

returns - the parsed xml document.

canUseBackButton($flow, $state, $transition)

Returns whether the user should be able to use the back button after this transition.

getBackErrorMessage($flow, $state, $transition)

Returns the error message if a the back button is used and it is not allowed.

requires*($flow, $state, $transition)

Given a state and action from the state, returns whether a: -validation -revert -commit -freshen -update is required.

$flow - the page flow. $state - the start state. $action - the action out of the state.

get*FailoverState*($flow, $state)

Gets the name of the failover state.

getController($state, $application)

Gets the controller for the given state.

$state - the state to get the controller for. $application - the application.

returns - the controller object for the $state.


Gets the name of the controller for the given state.

$state - the state to get the controller name for.

returns - the controller name (string).

_createNode($stateName, $controller)

Creates a new node object.

_createPageFlow($namespace, $pageflow_name, $entrance)

Creates a new page flow object.

_createTransition($action, $transition_final, $on_back, $lifecycle_stages)

Creates a new transition object.

_createFlowTransition($action, $namespace, $flowname, $on_back, $lifecycle_stages)

Creates a new flow transition object.


Returns the package name of the flow transition object.


Returns a string containing the xml serialization of the machine.


Copyright 1998-2007 Office of Learning Technologies, University of Washington

Licensed under the Educational Community License, Version 1.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at:

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.