Objective-C API Library Reference  4.3.0-42-g45f162a
 All Classes Functions Typedefs Properties Pages
Public Functions | Properties | List of all members
PWXmlStateManager Class Reference

The PWStateManager class manages changes between the server and the client application.

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 applications; 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 (PWXmlStateManager) to explicitly lock application state before interacting with it.

All events are fired on the UI thread.

Constructors

(id) - init
 

Public Functions

(PWXmlStateLock *) - acquireLock
 
(void) - addChangedEvent:withTarget:
 
(void) - addChildChangedHandler:target:action:
 
(void) - addValueChangedHandler:target:action:
 
(void) - clear
 
(PWXmlElement *) - copyState
 
(void) - deleteTree:
 
(PWXmlElement *) - difference:versionThreshold:
 
(void) - finishChanges:
 
(id) - getTextAs:childPath:
 
(id) - getTextAsWithChildPathAndDefault:defaultValue:
 
(PWXmlElement *) - getTree:
 
(PWXmlElement *) - getTree:allowCreate:
 
(NSString *) - getValue:
 
(NSString *) - getValueWithAppStatePath:
 
(void) - initialize:
 
(void) - merge:
 
(void) - remove:
 
(void) - removeAllChildChangedHandlers:
 
(void) - removeAllChildChangedHandlersForTarget:
 
(void) - removeAllHandlers:
 
(void) - removeAllHandlersForTarget:
 
(void) - removeAllValueChangedHandlers:
 
(void) - removeAllValueChangedHandlersForTarget:
 
(void) - removeChangedEvent:withTarget:
 
(void) - removeChildChangedHandler:target:action:
 
(void) - removeValueChangedHandler:target:action:
 
(void) - setAppStatePathWithValue:value:
 
(void) - setTree:node:
 
(void) - setValue:value:
 
(void) - startChanges
 
(NSString *) - stringValue
 
(BOOL) - tryAcquireLock:stateLock:
 

Properties

PWEventTimerProfilerchangeHandlersTimer
 
PWEventTimerProfilerdiffTimer
 
PWEventTimerProfilergetTimer
 
PWEventTimerProfilermergeTimer
 
PWEventTimerProfilersetTimer
 

Methods Descriptions

- (PWXmlStateLock *) 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 PWXmlStateLock to interact with application state.
- (void) addChangedEvent: (SEL)  handlerSelector
withTarget: (id)  target 

Adds an event handler to be invoked when StateManager changes.

- (void) addChildChangedHandler: (NSString *)  path
target: (id)  target
action: (SEL)  action 

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
pathThe path to the element in the application state tree that you want to monitor for changes.
targetThe object to notify of the event.
actionThe handling function to execute when the value for the element or one of its child changes.
- (void) addValueChangedHandler: (NSString *)  path
target: (id)  target
action: (SEL)  action 

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.

Parameters
pathThe path to the value in the application state tree that you want to monitor for changes.
targetThe object to notify of the event.
actionThe handling function to execute when the value changes.
- (void) clear

Clears the entire application state.

- (PWXmlElement *) copyState

Makes a copy of the entire application state.

- (void) deleteTree: (NSString *)  path

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

- (PWXmlElement *) difference: (PWXmlElement *)  other
versionThreshold: (long)  versionThreshold 

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.

- (void) finishChanges: (BOOL)  notifyStateChanges

Finishes batch changes to state. If any changes were made, then the Changed event is fired. Assumes that the lock is held. This is intended for internal use only.

Parameters
notifyStateChangesIf set to YES, notify state changes.
- (id) getTextAs: (const char *)  objCType
childPath: (NSString *)  childPath 

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.

- (id) getTextAsWithChildPathAndDefault: (NSString *)  childPath
defaultValue: (id)  defaultValue 

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.

- (PWXmlElement *) getTree: (NSString *)  path

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.

Note
This element may not be valid after the lock is released.
- (PWXmlElement *) getTree: (NSString *)  path
allowCreate: (BOOL)  allowCreate 

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. If allowCreate is set to false, then null will be returned if the path does not exist.

- (NSString *) getValue: (NSString *)  path

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

- (NSString *) getValueWithAppStatePath: (NSString *)  appStatePath

Returns the value of the specified application state element.

- (id) init

Initializes a new instance of the XmlStateManager class.

- (void) initialize: (PWXmlElement *)  state

Initializes the state to a copy of the specified value.

- (void) merge: (PWXmlElement *)  diffScript

Merges the specified diff script into the managed state.

- (void) remove: (NSString *)  path

Removes the element at the specified path.

- (void) removeAllChildChangedHandlers: (NSString *)  path

Removes all child change handlers for specified path.

- (void) removeAllChildChangedHandlersForTarget: (id)  target

Removes all child change handlers for specified target object.

- (void) removeAllHandlers: (NSString *)  path

Removes all child changed handlers AND value changed handlers for the specified path.

- (void) removeAllHandlersForTarget: (id)  target

Removes all child changed handlers AND value changed handlers for the specified target object.

- (void) removeAllValueChangedHandlers: (NSString *)  path

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

- (void) removeAllValueChangedHandlersForTarget: (id)  target

Removes all value changed handlers for the specified target object.

- (void) removeChangedEvent: (SEL)  handlerSelector
withTarget: (id)  target 

Removes the specified event handler.

- (void) removeChildChangedHandler: (NSString *)  path
target: (id)  target
action: (SEL)  action 

Unregisters the specified child changed handler.

Parameters
pathThe path to the element in the application state tree.
targetThe object to notify of the event.
actionThe handler that you are unregistering.
- (void) removeValueChangedHandler: (NSString *)  path
target: (id)  target
action: (SEL)  action 

Unregisters the specified value changed handler.

Parameters
pathThe path to the value in the application state tree.
targetThe object to notify of the event.
actionThe handler that you are unregistering.
- (void) setAppStatePathWithValue: (NSString *)  appStatePath
value: (NSString *)  value 

Updates the specified application state element with the provided value.

- (void) setTree: (NSString *)  path
node: (PWXmlElement *)  node 

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

- (void) setValue: (NSString *)  path
value: (NSString *)  value 

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

- (void) startChanges

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

- (NSString *) stringValue

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

- (BOOL) tryAcquireLock: (NSTimeInterval)  timeout
stateLock: (PWXmlStateLock **)  stateLock 

Attempts to acquire a lock on the application state.

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

Properties Descriptions

- (PWEventTimerProfiler*) changeHandlersTimer
readnonatomicstrong

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

- (PWEventTimerProfiler*) diffTimer
readnonatomicstrong

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

- (PWEventTimerProfiler*) getTimer
readnonatomicstrong

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

- (PWEventTimerProfiler*) mergeTimer
readnonatomicstrong

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

- (PWEventTimerProfiler*) setTimer
readnonatomicstrong

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