C# / .Net API Library Reference  4.3.2-74-ge1d4cca
Package Functions | Public Functions | Properties | Events
XmlStateManager Class Reference

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:

Methods in this class acquire a lock on application state internally; you can also use AcquireLock to explicitly lock application state before interacting with it.

Package Functions

XElement Element (string path)
 
XElement Element (string path, bool allowCreate)
 
void FinishChanges (bool notifyStateChanges)
 
void ReleaseLock ()
 
void StartChanges ()
 

Public Functions

XmlStateLock AcquireLock ()
 
void AddChildChangedHandler (string path, EventHandler< ValueChangedEventArgs > handler)
 
void AddValueChangedHandler (string path, EventHandler< ValueChangedEventArgs > handler)
 
void Clear ()
 
XElement CopyState ()
 
void DeleteTree (string path)
 
XElement Difference (XElement other, long versionThreshold)
 
XElement GetTree (string path)
 
XElement GetTree (string path, bool allowCreate)
 
string GetValue (string path)
 
GetValueAs< T > (string path)
 
GetValueAs< T > (string path, CultureInfo culture)
 
GetValueAs< T > (string path, T defaultValue)
 
GetValueAs< T > (string path, T defaultValue, CultureInfo culture)
 
void Initialize (XElement state)
 
void Merge (XElement diffScript)
 
void RemoveAllChildChangedHandlers (string path)
 
void RemoveAllValueChangedHandlers (string path)
 
void RemoveChildChangedHandler (string path, EventHandler< ValueChangedEventArgs > handler)
 
void RemoveValueChangedHandler (string path, EventHandler< ValueChangedEventArgs > handler)
 
void SetTree (string path, XElement node)
 
void SetValue (string path, object value)
 
override string ToString ()
 
string ToString (SaveOptions options)
 
bool TryAcquireLock (TimeSpan timeout, out XmlStateLock stateLock)
 
Constructors and Destructors
 XmlStateManager ()
 

Properties

object SyncRoot [get]
 
string this[string path] [get, set]
 

Events

EventHandler Changed
 

Usage Description

XmlStateLock AcquireLock ( )
inline

Locks the application state. This is necessary if you want the lock to be held for longer than a single operation, for example to perform atomic changes to multiple paths of the application state tree.

Note
Once you acquire the lock, you will need to use the methods in XmlStateLock to interact with application state.
void AddChildChangedHandler ( string  path,
EventHandler< ValueChangedEventArgs handler 
)
inline

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.

void AddValueChangedHandler ( string  path,
EventHandler< ValueChangedEventArgs handler 
)
inline

Registers a change 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.

void Clear ( )
inline

Clears the entire application state.

XElement CopyState ( )
inline

Makes a copy of the entire application state.

void DeleteTree ( string  path)
inline

Deletes all application state elements from the specified path and below.

XElement Difference ( XElement  other,
long  versionThreshold 
)
inline

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.

XElement Element ( string  path)
inlinepackage

Returns a copy of the element at the specified location. If the element does not exist it is created.

This is a potentially expensive operation.

XElement Element ( string  path,
bool  allowCreate 
)
inlinepackage

Returns a copy of the application state element at the specified path, or returns empty if the following two conditions are met:

  • the element does not exist, and
  • the allowCreate flag is set to false.

    This is a potentially expensive operation.
void FinishChanges ( bool  notifyStateChanges)
inlinepackage

Finishes batch changes to state. If any changes were made, then the Changed event is fired. Assumes that the lock is held.

XElement GetTree ( string  path)
inline

Returns the underlying XML node at the specified path. The node returned is a copy of the application state at that path, including the children elements, if any. Use SetTree to update the application state if making modifications to that node.

XElement GetTree ( string  path,
bool  allowCreate 
)
inline

Copies the application state tree at the specified path. If allowCreate is set to false, then null will be returned if the path does not exist.

string GetValue ( string  path)
inline

Returns the value of the application state element at the specified path, or null if the element does not exist.

T GetValueAs< T > ( string  path)
inline

Returns the value of the element at the specified path in the application state tree. The value will be returned in the specified data type. Will throw an InvalidCastException if the value does not exist or cannot be converted.

T GetValueAs< T > ( string  path,
CultureInfo  culture 
)
inline

Returns the value of the element at the specified path in the application state tree. The value will be returned in the specified data type. Will throw an InvalidCastException if the value does not exist or cannot be converted.

T GetValueAs< T > ( string  path,
defaultValue 
)
inline

Returns the value of the element at the specified path in the application state tree. The value will be returned in the specified data type. Will return the specified default if the value does not exist or cannot be converted.

T GetValueAs< T > ( string  path,
defaultValue,
CultureInfo  culture 
)
inline

Returns the value of the element at the specified path in the application state tree. The value will be returned in the specified data type. Will return the specified default if the value does not exist or cannot be converted.

void Initialize ( XElement  state)
inline

Initializes application state to a copy of the specified value.

void Merge ( XElement  diffScript)
inline

Merges the specified diff script in to the managed state.

void ReleaseLock ( )
inlinepackage

Releases the lock.

void RemoveAllChildChangedHandlers ( string  path)
inline

Unregisters all child changed handlers asociated with a given path in the application state tree.

void RemoveAllValueChangedHandlers ( string  path)
inline

Unregisters all value changed handlers associated with a given path in the application state tree.

void RemoveChildChangedHandler ( string  path,
EventHandler< ValueChangedEventArgs handler 
)
inline

Unregisters the specified child changed handler.

void RemoveValueChangedHandler ( string  path,
EventHandler< ValueChangedEventArgs handler 
)
inline

Unregisters the specified value changed handler.

void SetTree ( string  path,
XElement  node 
)
inline

Replaces the application state tree at the specified path with the element provided.

void SetValue ( string  path,
object  value 
)
inline

Sets the value of the application state element at the specified path.

void StartChanges ( )
inlinepackage

Starts batch changes to application state. Assumes the lock has been acquired.

override string ToString ( )
inline

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

string ToString ( SaveOptions  options)
inline

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

bool TryAcquireLock ( TimeSpan  timeout,
out XmlStateLock  stateLock 
)
inline

Tries to acquire a lock on the application state.

Note
If you acquire the lock, you will need to use the methods in XmlStateLock to interact with application state.

Property Documentation

object SyncRoot
get

Gets the mutex for StateManager.

string this[string path]
getset

Event Documentation

EventHandler Changed

This event is triggered whenever a change occurs within application state. Will be fired on the UI thread.