C++ API Library Reference  4.3.2-74-ge1d4cca
Classes | Public Functions | List of all members
TypelessStateManager Class Reference

The TypelessStateManager 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 to and from 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.

Public Functions

TypelessStateLock AcquireLock ()
 
void AddChildChangedHandler (String const &path, ValueChangedCallback handler)
 
void AddValueChangedHandler (String const &path, ValueChangedCallback handler)
 
void Clear ()
 
void ClearChildChangedHandlers ()
 
void ClearValueChangedHandlers ()
 
Typeless CopyState ()
 
Typeless CopyState (String const &path)
 
void DeleteTree (String const &path)
 
Typeless Difference (Typeless const &other, Int64 versionThreshold=0)
 
Typeless Element (String const &path, bool allowCreate=true)
 
Typeless Element (String const &path) const
 
void FinishChanges (bool notifyStateChanges, ValueChangedCallbackList &callbackList)
 
Nullable< String > const & GetValue (String const &path) const
 
template<typename T >
GetValueAs (String const &path) const
 
template<typename T >
GetValueAs (String const &path, T const &defaultValue) const
 
void Initialize (Typeless const &state)
 
void Merge (Typeless const &diffScript)
 
Nullable< String > const & operator[] (String const &path) const
 
void RemoveAllChildChangedHandlers (String const &path)
 
void RemoveAllValueChangedHandlers (String const &path)
 
void RemoveChildChangedHandler (String const &path, ValueChangedCallback handler)
 
void RemoveValueChangedHandler (String const &path, ValueChangedCallback handler)
 
void SetNotificationCallbacks (Function< void(void)> startNotification, Function< void(void)> finishNotification)
 
void SetValue (String const &path, Nullable< String > const &value)
 
void SetValue (String const &path, String const &value)
 
template<typename T >
void SetValueAs (String const &path, T const &value)
 
void StartChanges ()
 
Threading::MutexSyncRoot () const
 
String ToString (const Xml::TypelessXmlWriterOptions &options=Xml::TypelessXmlWriterOptions::Default()) const
 
bool TryAcquireLock (TimeSpan timeout, TypelessStateLock &lock)
 
Events

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

 DEFINE_EVENT_INDIRECT (Changed, TypelessStateManager, EmptyEventArgs, GetChangedEvent())
 
Constructors and Destructors
 TypelessStateManager ()
 
virtual ~TypelessStateManager ()
 

Usage Description

TypelessStateLock AcquireLock ( )

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 TypelessStateLock to interact with application state.
void AddChildChangedHandler ( String const &  path,
ValueChangedCallback  handler 
)

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 const &  path,
ValueChangedCallback  handler 
)

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 ( )

Clears the entire application state.

void ClearChildChangedHandlers ( )

Clears all registered child changed handlers.

void ClearValueChangedHandlers ( )

Clears all registered value changed handlers.

Typeless CopyState ( )
inline

Makes a copy of the entire application state.

Typeless CopyState ( String const &  path)
inline

Makes a copy of the section of application state at the specified path.

DEFINE_EVENT_INDIRECT ( Changed  ,
TypelessStateManager  ,
EmptyEventArgs  ,
GetChangedEvent()   
)
void DeleteTree ( String const &  path)
inline

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

Typeless Difference ( Typeless const &  other,
Int64  versionThreshold = 0 
)

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.

Typeless Element ( String const &  path,
bool  allowCreate = true 
)
inline

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

  • the element does not exist, and
  • the allowCreate flag is set to false.
Typeless Element ( String const &  path) const
inline

Returns a copy of the application state element at the specified path, or returns Typeless::Empty() if the element does not exist.

void FinishChanges ( bool  notifyStateChanges,
ValueChangedCallbackList &  callbackList 
)

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

Nullable<String> const& GetValue ( String const &  path) const
inline

Returns the value of the element at the specified path in the application state tree. Will return null if the element does not exist.

T GetValueAs ( String const &  path) const
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 ( String const &  path,
T const &  defaultValue 
) const
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.

void Initialize ( Typeless const &  state)

Initializes application state to a copy of the specified value.

void Merge ( Typeless const &  diffScript)

Merges the specified diff script into the managed state.

Nullable<String> const& operator[] ( String const &  path) const
inline

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

void RemoveAllChildChangedHandlers ( String const &  path)

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

void RemoveAllValueChangedHandlers ( String const &  path)

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

void RemoveChildChangedHandler ( String const &  path,
ValueChangedCallback  handler 
)

Unregisters the specified child changed handler.

void RemoveValueChangedHandler ( String const &  path,
ValueChangedCallback  handler 
)

Unregisters the specified value changed handler.

void SetNotificationCallbacks ( Function< void(void)>  startNotification,
Function< void(void)>  finishNotification 
)

Sets notification callbacks; intended for internal use only.

void SetValue ( String const &  path,
Nullable< String > const &  value 
)
inline

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

void SetValue ( String const &  path,
String const &  value 
)
inline

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

void SetValueAs ( String const &  path,
T const &  value 
)
inline

Sets the value of the element at the specified path in the application state tree. The value will be set in the specified data type.

void StartChanges ( )

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

Threading::Mutex& SyncRoot ( ) const
inline

Gets the Mutex for StateManager.

String ToString ( const Xml::TypelessXmlWriterOptions &  options = Xml::TypelessXmlWriterOptions::Default()) const

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

bool TryAcquireLock ( TimeSpan  timeout,
TypelessStateLock lock 
)

Tries to acquire a lock on the application state.

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