org.puremvc.as3.utilities.startupmanager.model.StartupMonitorProxy

Package	org.puremvc.as3.utilities.startupmanager.model
Class	public class StartupMonitorProxy
Inheritance	StartupMonitorProxy org.puremvc.as3.patterns.proxy.Proxy
Implements	org.puremvc.as3.interfaces.IProxy

The Startup Manager offers a solution to the problem of how to manage the loading of data resources, be that at application startup or at some other time in the duration of the application. See the StartupManager class for an introduction to this utility.

An example of use is as follows. In the context of the puremvc framework, the application typically has a startup command that manages the instantiation of essential actors like proxies and mediators. At this time, you may also want to prime the application with some resources, for example data, before allowing user interaction. This utility offers a way of doing that.

The utility enables the application to do the following

state how the resource loading should be sequenced so that dependent resources are loaded in correct order
specify a retry policy, per resource
be aware of the progress of the resource loading
know when the resource loading is complete
cater for an open-ended list of resources.

The demo app called StartupAsOrdered provides an example use of this utility.

This StartupMonitorProxy class has the main role in managing the loading process. The client application creates a single instance of it. The term Monitor is used in the following documentation to signify this instance. Repeated use of the monitor is possible, serial not concurrent, by invoking the reset operation to reset the state of the monitor and ready it for reuse. In the case of reset, note that the jobId property could be useful.

For each startup resource to be managed, the app has created a StartupResourceProxy object. The app must register each of these with the Monitor, using the addResource method. See the StartupResourceProxy class for detail on that class.

It is assumed that the app has defined separate 'loaded' notifications for each resource. When the app completes a resource load, it will send the relevant notification. The app must register the utility command StartupResourceLoadedCommand for each of these notifications, so that the command can inform the Monitor that the resource has been loaded.

Given that a resource load could fail, it is also recommended the app defines separate 'failed' notifications for each resource. If a fail occurs, the app will send the relevant notification. The app must register the utility command StartupResourceFailedCommand for each of these notifications, so that the command can inform the Monitor that the resource load has failed.

NOTE NOTE that 'loaded' and 'failed' notifications MUST MUST use the body of the Notification to identify the resource, using the application's resource proxy name. In the case a 'failed' notification, the body can contain the name as a simple String object, as it would for a 'loaded' notification, but it can also embed the name in a FailureInfo object. A FailureInfo object enables the app to send a 'do not retry' instruction to the utility, when required.

The app starts the loading of resources using the loadResources method. For each resource that the Monitor decides should be loaded, it invokes the load method on the app's resource proxy using the IStartupProxy interface.

When the utility receives a 'failed' notification, and the notification does not state 'do not retry', that is, retry is allowed (this is the default), the utility will retry to load that resource, subject to the retry policy associated with the resource.

During the loading of resources, the Monitor can send various notifications to the application. These are as follows:

LOADING_PROGRESS: sent after each resource load, with percent loaded as the note body, an integer
RETRYING_LOAD_RESOURCE: a load operation has failed and the Monitor is now retrying the load; the notification identifies the resource using the app's resource proxy name in the notification body
LOAD_RESOURCE_TIMED_OUT: the Monitor has asked the app to load a resource and has now timed out the load; the timeout was decided by the StartupResourceProxy for the resource; the notification identifies the resource using the app's resource proxy name in the notification body
LOADING_COMPLETE: all resources have been successfully loaded
LOADING_FINISHED_INCOMPLETE: all resources that could be loaded have been loaded, but not all have been loaded; some may have failed, even after retries, some may have timed out, some may depend on others and one of those others has failed
CALL_OUT_OF_SYNC_IGNORED: the app has called a method on the Monitor and that method is not valid at this stage of the process
WAITING_FOR_MORE_RESOURCES: when the context is an open-ended resource list (see below), and all resources listed so far have been loaded, this notification is sent instead of the LOADING_COMPLETE notification

The recommended response of the app to each of these notifications is as follows:

LOADING_PROGRESS: optional
RETRYING_LOAD_RESOURCE: optional
LOAD_RESOURCE_TIMED_OUT: optional, see the getFailedResourcesThisTry() method as another way to find out what resources have failed or have timed out
LOADING_COMPLETE: should listen for, now the application can proceed
LOADING_FINISHED_INCOMPLETE: should listen for, can try again to load the remaining resources by invoking the tryToCompleteLoadResources method on the Monitor; in this case, the Monitor resets the retry policy of each outstanding resource, so that the retry history is removed and each resource can be retried again to the fullest extent
CALL_OUT_OF_SYNC_IGNORED: should listen for, should probably abort startup and debug
WAITING_FOR_MORE_RESOURCES: optional

Technically, it is worth noting that an application could choose to ignore the StartupResourceLoadedCommand and the StartupResourceFailedCommand, and instead directly invoke the corresponding methods on the Monitor, namely, resourceLoaded and resourceFailed.

An Error is thrown when certain exceptions are encountered, for example

Invalid Resources: if the Monitor decides that the set of resources cannot be loaded, for example, there are no resources, or they have inter-dependencies such that it is not feasible to load them.

The property defaultRetryPolicy is a convenient way of setting a retry policy that will be used as the default in StartupResourceProxy objects. This is assigned an initial value based on the utility's own standard retry policy and configured as: maxRetries=0, retryInterval=0, timeout=300secs. The timeout is set because it is deemed important to have some fallback timeout in the case of asynchronous operations. Also, see method reConfigureAllRetryPolicies() below.

The utility can be used to load an open-ended list of resources, where the full set of resources is not known at the outset. For example, the first resource loaded might determine what other resources are to be loaded. This method of loading is accomplished as follows

before invoking loadResources(), invoke keepResourceListOpen()
after invoking loadResources(), use addResource() or addResources() to add to the list, as the additional resources arise; note that the StartupResourceProxy 'requires' property should be set before adding to the list; this requirement can lead to addResources() being preferred as the means of adding an inter-dependent set of resources; consequently, the approach implemented by the makeAndRegisterStartupResource method of the StartupAsOrdered demo is not applicable in this circumstance
invoke closeResourceList() to inform the monitor that all resources have been added
before invoking loadResources(), set the expectedNumberOfResources property, if you want the report of loading progress to be reasonable; this will be used until a more exact number is known.

Adapted from original code of Meekgeek and Daniele Ugoletti, implemented in Daniele's ApplicationSkeleton_v1.3 demo, Nov 2007, posted to the puremvc forums.

	Property	Defined by
		defaultRetryPolicy : IRetryPolicy	StartupMonitorProxy
		expectedNumberOfResources : int [write-only] Only relevant if keepResourceListOpen() is relevant; purpose is to make the reporting of loading progress more valid.	StartupMonitorProxy
		jobId : String Each use of the StartupManager, to load a set of resources, can be given a job id.	StartupMonitorProxy
		waitingForMoreResourcesNotificationName : String = "smWaitingForMoreResources" If the client app overrides the initial value of this var, then it is in charge of its value; the reset() operation DOES NOT reset it to the initial value.	StartupMonitorProxy

	Property	Defined by
		failedResourcesThisTry : Array [read-only] An array of StartupResourceProxy objects.	StartupMonitorProxy
		_jobId : String = ""	StartupMonitorProxy
		loadedResources : Array [read-only] An array of StartupResourceProxy objects.	StartupMonitorProxy
		resourceList : IResourceList [read-only]	StartupMonitorProxy

	Method	Defined by
		StartupMonitorProxy(data:IResourceList = null)	StartupMonitorProxy
		addResource(r:StartupResourceProxy):void Add a resource to be loaded.	StartupMonitorProxy
		addResources(resources:Array):void Add resourceS to be loaded.	StartupMonitorProxy
		addResourcesViaStartupProxy(pxs:Array):void Add resourceS via an array of StartupProxy objects - alternative to adding them singly.	StartupMonitorProxy
		addResourceViaStartupProxy(px:IStartupProxy):void See addResource() above.	StartupMonitorProxy
		allResourcesLoaded():Boolean Check have all the listed resources been loaded.	StartupMonitorProxy
		closeResourceList():void	StartupMonitorProxy
		getFailedResourcesThisTry():Array	StartupMonitorProxy
		getLoadedResources():Array These 3 functions provide safe read-only access to 3 non-public objects.	StartupMonitorProxy
		getResourceList():IResourceList	StartupMonitorProxy
		getResourceViaStartupProxyName(proxyName:String):StartupResourceProxy Find the resource, that is, the StartupResourceProxy object, where the corresponding IStartupProxy object has the given name.	StartupMonitorProxy
		isActive():Boolean Is the monitor active, meaning is it engaged in loading resources or has it finished this try.	StartupMonitorProxy
		isOkToReset():Boolean Is it ok to reset this monitor? Yes, if the monitor is not currently active; by active we mean that loading has started and the monitor has not yet reached a LOADING_COMPLETE or LOADING_FINISHED_INCOMPLETE state.	StartupMonitorProxy
		keepResourceListOpen():void	StartupMonitorProxy
		loadResources():void Start to load all resources.	StartupMonitorProxy
		reConfigureAllRetryPolicies(retryParameters:IRetryParameters):void After loading has 'finished incomplete', this method is a convenient way for the client app to change the retry policies, where the same input parameters apply to all policy instances.	StartupMonitorProxy
		reset():void Reset the state of the monitor, so that it is ready for reuse.	StartupMonitorProxy
		resourceFailed(proxyName:String, allowRetry:Boolean = true):void The resource load has failed, update the state, retry the load if possible, otherwise check are we finished with this try to load resources.	StartupMonitorProxy
		resourceHasBeenTimedOut(r:StartupResourceProxy):void Loading of the resource has timed out, update the state and check if the loading process is complete.	StartupMonitorProxy
		resourceLoaded(proxyName:String):void The resource is loaded, update the state and check if the loading process is complete.	StartupMonitorProxy
		sendProgressNotification():void Sends the Loading Progress notification, with percent loaded, for client app to observe.	StartupMonitorProxy
		tryToCompleteLoadResources():void Try to complete the loading of outstanding resources	StartupMonitorProxy

	Method	Defined by
		doSendNotification(notificationName:String, body:Object = null):void	StartupMonitorProxy
		findSRProxyByAppProxyName(appProxyName:String):StartupResourceProxy Find the StartupResourceProxy object, in the resourceList, that refers to the app resource proxy of the given name.	StartupMonitorProxy
		initializeMonitor():void	StartupMonitorProxy
		isLoadingFinished():Boolean Check if the loading process is finished.	StartupMonitorProxy
		isLoadResourcesFeasible():Boolean	StartupMonitorProxy

	Constant	Defined by
		CALL_OUT_OF_SYNC_IGNORED : String = "smCallOutOfSyncIgnored" [static]	StartupMonitorProxy
		LOADING_COMPLETE : String = "smLoadingComplete" [static]	StartupMonitorProxy
		LOADING_FINISHED_INCOMPLETE : String = "smLoadingFinishedIncomplete" [static]	StartupMonitorProxy
		LOADING_PROGRESS : String = "smLoadingProgress" [static]	StartupMonitorProxy
		LOAD_RESOURCE_TIMED_OUT : String = "smLoadResourceTimedOut" [static]	StartupMonitorProxy
		NAME : String = "StartupMonitorProxy" [static]	StartupMonitorProxy
		RETRYING_LOAD_RESOURCE : String = "smRetryingLoadResource" [static]	StartupMonitorProxy
		WAITING_FOR_MORE_RESOURCES : String = "smWaitingForMoreResources" [static]	StartupMonitorProxy

	Constant	Defined by
		INVALID_RESET_MSG : String = ": StartupMonitorProxy does not allow reset at this time"	StartupMonitorProxy
		INVALID_RESOURCES_MSG : String = ": Invalid set of resources, check dependencies"	StartupMonitorProxy
		UNKNOWN_PROXY_MSG : String = ": not a known Application Resource Proxy"	StartupMonitorProxy

Property detail

defaultRetryPolicy

property

defaultRetryPolicy:IRetryPolicy  [read-write]Implementation
    public function get defaultRetryPolicy():IRetryPolicy
    public function set defaultRetryPolicy(value:IRetryPolicy):void

expectedNumberOfResources

property

expectedNumberOfResources:int [write-only]

Only relevant if keepResourceListOpen() is relevant; purpose is to make the reporting of loading progress more valid.

Implementation
public function set expectedNumberOfResources(value:int):void

failedResourcesThisTry

property

failedResourcesThisTry:Array [read-only]

An array of StartupResourceProxy objects.

Implementation
protected function get failedResourcesThisTry():Array

_jobId

property

protected var _jobId:String = ""

jobId

property

jobId:String [read-write]

Each use of the StartupManager, to load a set of resources, can be given a job id. The notifications sent by the StartupManager include this job id as the notification type. The reset() operation includes resetting the jobId to blank; hence, if setting jobId, do so after reset or after initial instantiation of StartupMonitorProxy.

Implementation
public function get jobId():String
public function set jobId(value:String):void

loadedResources

property

loadedResources:Array [read-only]

An array of StartupResourceProxy objects.

Implementation
protected function get loadedResources():Array

resourceList

property

resourceList:IResourceList [read-only]Implementation
protected function get resourceList():IResourceList

waitingForMoreResourcesNotificationName

property

public var waitingForMoreResourcesNotificationName:String = "smWaitingForMoreResources"

If the client app overrides the initial value of this var, then it is in charge of its value; the reset() operation DOES NOT reset it to the initial value.

Constructor detail

StartupMonitorProxy

()

constructor

public function StartupMonitorProxy(data:IResourceList = null)Parameters

data:IResourceList (default = null)

Method detail

addResource

()

method

public function addResource(r:StartupResourceProxy):void

Add a resource to be loaded. Should be done before invoking loadResources(), unless client app is using the facility to keep the resource list open. In the case of the list being kept open, if adding resources after loading has commenced, add them in strict logical order according to dependencies; if this is difficult, consider the alternative addResources() method. Otherwise, the Invalid Resources error could occur.

Parameters

r:StartupResourceProxy

addResources

()

method

public function addResources(resources:Array):void

Add resourceS to be loaded. Should be done before invoking loadResources(), unless client app is using the facility to keep the resource list open. This facility to add multiple resources is likely to be useful when adding resources after loading has commenced and the resources have inter dependencies.

Parameters

resources:Array

addResourcesViaStartupProxy

()

method

public function addResourcesViaStartupProxy(pxs:Array):void

Add resourceS via an array of StartupProxy objects - alternative to adding them singly.

Parameters

pxs:Array

addResourceViaStartupProxy

()

method

public function addResourceViaStartupProxy(px:IStartupProxy):void

See addResource() above. This method offers an alternative to that, as a shortcut for the client app, whereby the app does not have to create the StartupResourceProxy (sup) object for the IStartupProxy object. Instead, the StartupManager (SM) will create the sup object. But note that the app does not then have a reference to it and has not given it a name and has not registered it using registerProxy(). In fact, the SM will not give it a name and hence will not register it. This is fine as regards the SM operations. This is only practical if there are no dependencies between the resources, because the app requires references to the sup objects, to express the dependencies.

Parameters

px:IStartupProxy

allResourcesLoaded

()

method

public function allResourcesLoaded():Boolean

Check have all the listed resources been loaded.

Returns

Boolean

closeResourceList

()

method

public function closeResourceList():void

doSendNotification

()

method

protected function doSendNotification(notificationName:String, body:Object = null):voidParameters

	`notificationName:String`

	`body:Object` (default = `null`)

findSRProxyByAppProxyName

()

method

protected function findSRProxyByAppProxyName(appProxyName:String):StartupResourceProxy

Find the StartupResourceProxy object, in the resourceList, that refers to the app resource proxy of the given name.

Parameters

appProxyName:String

Returns

StartupResourceProxy

getFailedResourcesThisTry

()

method

public function getFailedResourcesThisTry():Array

Returns

Array

getLoadedResources

()

method

public function getLoadedResources():Array

These 3 functions provide safe read-only access to 3 non-public objects.

Returns

Array

getResourceList

()

method

public function getResourceList():IResourceList

Returns

IResourceList

getResourceViaStartupProxyName

()

method

public function getResourceViaStartupProxyName(proxyName:String):StartupResourceProxy

Find the resource, that is, the StartupResourceProxy object, where the corresponding IStartupProxy object has the given name. Return null if not found. An example use of this is with the proxyName caotained in a notification from the StartupManager.

Parameters

proxyName:String

Returns

StartupResourceProxy

initializeMonitor

()

method

protected function initializeMonitor():void

See also

reset()

isActive

()

method

public function isActive():Boolean

Is the monitor active, meaning is it engaged in loading resources or has it finished this try.

Returns

Boolean

isLoadingFinished

()

method

protected function isLoadingFinished():Boolean

Check if the loading process is finished. For each resource that has not yet been processed, check whether it could be loaded. If none can be loaded, then we are finished.

Returns

Boolean

isLoadResourcesFeasible

()

method

protected function isLoadResourcesFeasible():Boolean

Returns

Boolean

isOkToReset

()

method

public function isOkToReset():Boolean

Is it ok to reset this monitor? Yes, if the monitor is not currently active; by active we mean that loading has started and the monitor has not yet reached a LOADING_COMPLETE or LOADING_FINISHED_INCOMPLETE state.

Returns

Boolean

keepResourceListOpen

()

method

public function keepResourceListOpen():void

loadResources

()

method

public function loadResources():void

Start to load all resources. Expect to be called just once. Guard against unexpected usage: e.g. empty resourceList, e.g. infeasible 'requires' specification.

reConfigureAllRetryPolicies

()

method

public function reConfigureAllRetryPolicies(retryParameters:IRetryParameters):void

After loading has 'finished incomplete', this method is a convenient way for the client app to change the retry policies, where the same input parameters apply to all policy instances. Another way is for the app to set a new retry policy instance on each StartupResourceProxy that requires it. Of course, it is perfectly valid to leave the policies unchanged.

Parameters

retryParameters:IRetryParameters

reset

()

method

public function reset():void

Reset the state of the monitor, so that it is ready for reuse. It is recommended that the client app check via isOkToReset() before invoking reset(). See also the jobId property. Throws Error if reset is not allowed.

resourceFailed

()

method

public function resourceFailed(proxyName:String, allowRetry:Boolean = true):void

The resource load has failed, update the state, retry the load if possible, otherwise check are we finished with this try to load resources.

Parameters

	`proxyName:String` — App resource proxy name for the failed load.

	`allowRetry:Boolean` (default = `true`) — False means the client app says 'do not retry'.

resourceHasBeenTimedOut

()

method

public function resourceHasBeenTimedOut(r:StartupResourceProxy):void

Loading of the resource has timed out, update the state and check if the loading process is complete.

Parameters

r:StartupResourceProxy

resourceLoaded

()

method

public function resourceLoaded(proxyName:String):void

The resource is loaded, update the state and check if the loading process is complete.

Parameters

proxyName:String — App resource proxy name for the loaded resource.

sendProgressNotification

()

method

public function sendProgressNotification():void

Sends the Loading Progress notification, with percent loaded, for client app to observe. Used internally by the StartupManager, but can be invoked by a client app if desired, for example to cause more frequent notifications because there is a custom calculation of progress percentage.

tryToCompleteLoadResources

()

method

public function tryToCompleteLoadResources():void

Try to complete the loading of outstanding resources

Constant detail

CALL_OUT_OF_SYNC_IGNORED

constant

public static const CALL_OUT_OF_SYNC_IGNORED:String = "smCallOutOfSyncIgnored"

INVALID_RESET_MSG

constant

protected const INVALID_RESET_MSG:String = ": StartupMonitorProxy does not allow reset at this time"

INVALID_RESOURCES_MSG

constant

protected const INVALID_RESOURCES_MSG:String = ": Invalid set of resources, check dependencies"

LOADING_COMPLETE

constant

public static const LOADING_COMPLETE:String = "smLoadingComplete"

LOADING_FINISHED_INCOMPLETE

constant

public static const LOADING_FINISHED_INCOMPLETE:String = "smLoadingFinishedIncomplete"

LOADING_PROGRESS

constant

public static const LOADING_PROGRESS:String = "smLoadingProgress"

LOAD_RESOURCE_TIMED_OUT

constant

public static const LOAD_RESOURCE_TIMED_OUT:String = "smLoadResourceTimedOut"

NAME

constant

public static const NAME:String = "StartupMonitorProxy"

RETRYING_LOAD_RESOURCE

constant

public static const RETRYING_LOAD_RESOURCE:String = "smRetryingLoadResource"

UNKNOWN_PROXY_MSG

constant

protected const UNKNOWN_PROXY_MSG:String = ": not a known Application Resource Proxy"

WAITING_FOR_MORE_RESOURCES

constant

public static const WAITING_FOR_MORE_RESOURCES:String = "smWaitingForMoreResources"

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class StartupMonitorProxy	Properties \| Methods \| Constants