pureweb.xml. XmlStateManager

The XmlStateManager class is used to interact with PureWeb's application state.

Application state is an XML hierarchical tree of properties and values which resides on both the service and the client; it provides a synchronized data store between these components. To maintain application state synchronicity, the differences in state are automatically transmitted between the client and the service; these differences are contained in a diff script, generated whenever PureWeb executes the difference method.

This class provides methods for getting and setting state values, and allows you to register handler functions that are called when a single value (addValueChangedHandler) or an entire section (addChildChangedHandler) of application state changes. When referring to a value in the tree, provide the entire path (except for the root element, which should be omitted), dividing each level using a slash, for example: /MainPage/TabX/ControlName. The path can also contain conditional operators:
  • /Definitions/#1 (first ordered child of an element called Definitions)
  • /Definition[Id=1;Type=Button] (a Definition element with Id of 1 and of type Button)

Method Summary

addChildChangedHandler
Registers a child changed handler for a value in the application state.
addValueChangedHandler
Registers a changed handler for a value in the application state.
clear
Clears the entire application state.
copyState
Makes a copy of the entire application state.
deleteTree
Deletes all application state elements from the specified path and below.
difference
Returns a diff script of the differences between the current state and the specified other state, such that if the diff script were merged to the other state, it would be equivalent to the current state.
element
Creates a copy of the element at the specified location and returns this element (if allowCreate is set to true), otherwise returns null.
finishChanges
Ends the batch changes that were started using startChanges.
getTree
Returns the application state node at the specified path, or null if the path does not exist.
getTreeAsXml
Returns the application state node at the specified path, or null if the path does not exist.
getValue
Returns the value of the element at the specified path in the application state tree, or null if it does not exist.
initialize
Initializes the state to a copy of the specified value.
merge
Merges the specified diff script into the managed state.
removeAllChildChangedHandlers
Unregisters all child changed handlers associated with the specified path in the application state tree.
removeAllValueChangedHandlers
Unregisters all value changed handlers associated with the specified path in the application state.
removeChildChangedHandler
Unregisters the specified child changed handler.
removeValueChangedHandler
Unregisters the specified value changed handler.
setTree
Sets the value of the node at the specified path in the application state tree.
setValue
Sets the value of the node at the specified path in the application state tree.
startChanges
Starts batch changes to application state.
toString
Returns the entire application state tree, expressed as a string.

Constructor

new XmlStateManager()

Initializes a new instance of XmlStateManager.

Extends

  • pureweb.events.EventTarget

Members

changeHandlersTimerpureweb.client.diagnostics.EventProfiler

A profiler that measures the amount of time taken to execute changed handlers.

diffTimerpureweb.client.diagnostics.EventProfiler

A profiler that measure the amount of time spent determining application state differences.

getTimerpureweb.client.diagnostics.EventProfiler

A profiler that measure the amount of time spent in the getValue, getValueAs and getTree methods.

mergeTimerpureweb.client.diagnostics.EventProfiler

A profiler that measure the amount of time spent merging application state differences.

setTimerpureweb.client.diagnostics.EventProfiler

A profiler that measure the amount of time spent in the setTree and setValue methods.

Method Detail

addChildChangedHandler(path, handler, context)

Registers a child changed handler for a value in the application state. The handler function will be called if a state change occurs at or below the specified path in the application state tree.
Parameters:
Name Type Argument Description
path string The path to the element in the application state tree to monitor for changes.
handler Object The handling function to execute when the value for the element or one of its child changes.
context Object <optional>
The context in which the handler will be executed (i.e. 'this').
Throws:
If either path or handler is null or undefined:
pureweb.NullArgumentException

addValueChangedHandler(path, handler, context)

Registers a changed handler for a value in the application state. When the specified value changes, the associated handling function will be called. If you want the handler to also be triggered if a child element of that value changes, use addChildChangedHandler instead.
Parameters:
Name Type Argument Description
path string The path to the element in the application state tree to monitor for changes.
handler Object The handling function to execute when the value for the element changes.
context Object <optional>
The context in which the handler will be executed (i.e. 'this').
Throws:
If either path or handler is null or undefined:
pureweb.NullArgumentException

clear()

Clears the entire application state.

copyState() → {Element}

Makes a copy of the entire application state.

deleteTree(path)

Deletes all application state elements from the specified path and below.
Parameters:
Name Type Description
path The path to remove.

difference(other, versionThreshold) → {Element}

Returns a diff script of the differences between the current state and the specified other state, such that if the diff script were merged to the other state, it would be equivalent to the current state.
Parameters:
Name Type Description
other Element The element to compare against the current element.
versionThreshold number The version threshold.
Throws:
If other is null or undefined:
pureweb.NullArgumentException

element(path, args) → {Element}

Creates a copy of the element at the specified location and returns this element (if allowCreate is set to true), otherwise returns null.
Parameters:
Name Type Argument Description
path string The path.
args Object <optional>
A boolean value that indicates whether to create the element.

finishChanges(notifyStateChanges)

Ends the batch changes that were started using startChanges. Any suppressed events will be fired.
Parameters:
Name Type Description
notifyStateChanges boolean Set to true to send notification when application state changes.

getTree(path, args) → {Object|Array.<string>|string|undefined}

Returns the application state node at the specified path, or null if the path does not exist. This node is a copy of the application state at that path, including the children elements, if any. The node is returned as a JSON-esque object; to receive the result as an XML element instead, use getTreeAsXml.
Parameters:
Name Type Argument Description
path string The path.
args Object <optional>
An object containing the boolean value of allowCreate.

getTreeAsXml(path, args) → {Element}

Returns the application state node at the specified path, or null if the path does not exist. This node is a copy of the application state at that path, including the children elements, if any. The node is returned as an XML element; to receive the result as an JSON object instead, use getTree.
Parameters:
Name Type Argument Description
path string The path.
args Object <optional>
An object containing the boolean value of allowCreate.

getValue(path)

Returns the value of the element at the specified path in the application state tree, or null if it does not exist.
Parameters:
Name Type Description
path string The path where to get the property value.

initialize(state)

Initializes the state to a copy of the specified value.
Parameters:
Name Type Description
state Node The application state.

merge(diffScript)

Merges the specified diff script into the managed state.
Parameters:
Name Type Description
diffScript Element The element containing a script of the differences.

removeAllChildChangedHandlers(path)

Unregisters all child changed handlers associated with the specified path in the application state tree.
Parameters:
Name Type Description
path string The path.
Throws:
If path is null or undefined:
pureweb.NullArgumentException

removeAllValueChangedHandlers(path)

Unregisters all value changed handlers associated with the specified path in the application state.
Parameters:
Name Type Description
path string The path.
Throws:
If path is null or undefined:
pureweb.NullArgumentException

removeChildChangedHandler(path, handler)

Unregisters the specified child changed handler.
Parameters:
Name Type Description
path string The path to the element in the application state tree
handler Object The handler that you are unregistering.
Throws:
If either path or handler is null or undefined:
pureweb.NullArgumentException

removeValueChangedHandler(path, handler)

Unregisters the specified value changed handler.
Parameters:
Name Type Description
path string The path to the value in the application state tree.
handler Object The handler that you are unregistering.
Throws:
If either path or handler is null or undefined:
pureweb.NullArgumentException

setTree(path, node)

Sets the value of the node at the specified path in the application state tree.
Parameters:
Name Type Description
path string The path where to set the value.
node Object | Element The value to set, expressed either as a JSON-esque JavaScript object, or as an XML Element.

setValue(path, value)

Sets the value of the node at the specified path in the application state tree.
Parameters:
Name Type Description
path string The path where to set the value.
value Element | boolean | null | number | string The value to set.

startChanges()

Starts batch changes to application state. Events will be suppressed until finishChanges is called.

toString() → {string}

Returns the entire application state tree, expressed as a string.