org.puremvc.as3.utilities.loadup.model.LoadupMonitorProxy

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

The Loadup utility 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 Loadup 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 LoadupAsOrdered provides an example use of this utility.

This LoadupMonitorProxy class has the main role in managing the loading process. The client application creates an instance of it for each batch of loading to be done. The term Monitor is used in the following documentation to signify this instance. Each Monitor instance is made unique by the proxyName it is given; hence there can be concurrent instances. When only one instance is required, the default name may well be sufficient. When the client application is finished with an instance, it should invoke the cleanup operation to facilitate garbage collection.

Repeated use of one monitor instance is possible, serial not concurrent, by invoking the reset operation to reset the state of the monitor and ready it for reuse.

For each loadup resource to be managed, the app has created a LoadupResourceProxy object. The app must register each of these with the Monitor, using the addResource method. See the LoadupResourceProxy 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 LoadupResourceLoadedCommand 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 LoadupResourceFailedCommand 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.

NOTE NOTE that 'loaded' and 'failed' notifications, when the monitor instance has its own custom name, i.e. a name other than the default name, MUST MUST include the monitor's name as the notification type, so that the utility command (see above) can know which monitor to inform.

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 ILoadupProxy 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 LoadupResourceProxy 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

Each notification sent by the Monitor includes a notification type; this is the Monitor's proxyName.

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 loadup and debug
WAITING_FOR_MORE_RESOURCES: optional

Technically, it is worth noting that an application could choose to ignore the LoadupResourceLoadedCommand and the LoadupResourceFailedCommand, 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 LoadupResourceProxy 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 LoadupResourceProxy '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 makeAndRegisterLoadupResource method of the LoadupAsOrdered 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	LoadupMonitorProxy
		expectedNumberOfResources : int [write-only] Only relevant if keepResourceListOpen() is relevant; purpose is to make the reporting of loading progress more valid.	LoadupMonitorProxy
		prefixIfAutoLRPName : String = "luLR_" This var is used by the addResourceViaLoadupProxy method.	LoadupMonitorProxy
		waitingForMoreResourcesNotificationName : String = "luWaitingForMoreResources" 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.	LoadupMonitorProxy

	Property	Defined by
		failedResourcesThisTry : Array [read-only] An array of LoadupResourceProxy objects.	LoadupMonitorProxy
		loadedResources : Array [read-only] An array of LoadupResourceProxy objects.	LoadupMonitorProxy
		resourceList : IResourceList [read-only]	LoadupMonitorProxy

	Method	Defined by
		LoadupMonitorProxy(proxyName:String = null, data:IResourceList = null) Constructor	LoadupMonitorProxy
		addResource(r:LoadupResourceProxy):void Add a resource to be loaded.	LoadupMonitorProxy
		addResources(resources:Array):void Add resourceS to be loaded.	LoadupMonitorProxy
		addResourcesViaLoadupProxy(pxs:Array):void Add resourceS via an array of ILoadupProxy objects - alternative to adding them singly.	LoadupMonitorProxy
		addResourceViaLoadupProxy(px:ILoadupProxy, resourceProxyName:String = null):void See addResource() above.	LoadupMonitorProxy
		allResourcesLoaded():Boolean Check have all the listed resources been loaded.	LoadupMonitorProxy
		cleanup():void This cleanup feature deals with removal of object state that is closely bound with this loadup monitor instance.	LoadupMonitorProxy
		closeResourceList():void If resource list is already closed, then nothing happens.	LoadupMonitorProxy
		getFailedResourcesThisTry():Array	LoadupMonitorProxy
		getLoadedResources():Array These 3 functions provide safe read-only access to 3 non-public objects.	LoadupMonitorProxy
		getResourceList():IResourceList	LoadupMonitorProxy
		getResourceViaLoadupProxyName(proxyName:String):LoadupResourceProxy Find the resource, that is, the LoadupResourceProxy object, where the corresponding ILoadupProxy object has the given name.	LoadupMonitorProxy
		isActive():Boolean Is the monitor active, meaning is it engaged in loading resources or has it finished this try.	LoadupMonitorProxy
		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.	LoadupMonitorProxy
		keepResourceListOpen():void	LoadupMonitorProxy
		loadResources():void Start to load all resources.	LoadupMonitorProxy
		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.	LoadupMonitorProxy
		reset():void Reset the state of the monitor, so that it is ready for reuse.	LoadupMonitorProxy
		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.	LoadupMonitorProxy
		resourceHasBeenTimedOut(r:LoadupResourceProxy):void Loading of the resource has timed out, update the state and check if the loading process is complete.	LoadupMonitorProxy
		resourceLoaded(proxyName:String):void The resource is loaded, update the state and check if the loading process is complete.	LoadupMonitorProxy
		sendProgressNotification():void Sends the Loading Progress notification, with percent loaded, for client app to observe.	LoadupMonitorProxy
		tryToCompleteLoadResources():void Try to complete the loading of outstanding resources	LoadupMonitorProxy

	Method	Defined by
		doCloseResourceList():void	LoadupMonitorProxy
		doSendNotification(notificationName:String, body:Object = null):void Notification type is this LoadupMonitorProxy's proxyName.	LoadupMonitorProxy
		findLRProxyByAppProxyName(appProxyName:String):LoadupResourceProxy Find the LoadupResourceProxy object, in the resourceList, that refers to the app resource proxy of the given name.	LoadupMonitorProxy
		initializeMonitor():void	LoadupMonitorProxy
		isAnyRemainingResourceLoadable():Boolean For each resource that has not yet been processed, check is there at least one that could be loaded.	LoadupMonitorProxy
		isLoadingFinished():Boolean Check if the loading process is finished.	LoadupMonitorProxy
		isLoadResourcesFeasible():Boolean Load resources is feasible unless there something illogical about the set of resources.	LoadupMonitorProxy
		removeResourceProxies():void	LoadupMonitorProxy

	Constant	Defined by
		CALL_OUT_OF_SYNC_IGNORED : String = "luCallOutOfSyncIgnored" [static]	LoadupMonitorProxy
		LOADING_COMPLETE : String = "luLoadingComplete" [static]	LoadupMonitorProxy
		LOADING_FINISHED_INCOMPLETE : String = "luLoadingFinishedIncomplete" [static]	LoadupMonitorProxy
		LOADING_PROGRESS : String = "luLoadingProgress" [static]	LoadupMonitorProxy
		LOAD_RESOURCE_TIMED_OUT : String = "luLoadResourceTimedOut" [static]	LoadupMonitorProxy
		NAME : String = "LoadupMonitorProxy" [static]	LoadupMonitorProxy
		RETRYING_LOAD_RESOURCE : String = "luRetryingLoadResource" [static]	LoadupMonitorProxy
		WAITING_FOR_MORE_RESOURCES : String = "luWaitingForMoreResources" [static]	LoadupMonitorProxy

	Constant	Defined by
		INVALID_RESET_MSG : String = ": LoadupMonitorProxy does not allow reset at this time"	LoadupMonitorProxy
		INVALID_RESOURCES_MSG : String = ": Invalid set of resources, check dependencies"	LoadupMonitorProxy
		UNKNOWN_ILOADUP_PROXY_MSG : String = ": Unknown ILoadupProxy in loaded/failed notification, not known in LoadupMonitorProxy instance named :"	LoadupMonitorProxy

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 LoadupResourceProxy objects.

Implementation
protected function get failedResourcesThisTry():Array

loadedResources

property

loadedResources:Array [read-only]

An array of LoadupResourceProxy objects.

Implementation
protected function get loadedResources():Array

prefixIfAutoLRPName

property

public var prefixIfAutoLRPName:String = "luLR_"

This var is used by the addResourceViaLoadupProxy method. The client app can assign a value, to override the initial value, if desired.

resourceList

property

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

waitingForMoreResourcesNotificationName

property

public var waitingForMoreResourcesNotificationName:String = "luWaitingForMoreResources"

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

LoadupMonitorProxy

()

constructor

public function LoadupMonitorProxy(proxyName:String = null, data:IResourceList = null)

Constructor

Parameters

	`proxyName:String` (default = `null`)

	`data:IResourceList` (default = `null`) — If you want to specify data and not proxyName, use (null,data)

Method detail

addResource

()

method

public function addResource(r:LoadupResourceProxy):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:LoadupResourceProxy

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

addResourcesViaLoadupProxy

()

method

public function addResourcesViaLoadupProxy(pxs:Array):void

Add resourceS via an array of ILoadupProxy objects - alternative to adding them singly. In this case, the client app must accept the default naming of the LoadupResourceProxy objects.

Parameters

pxs:Array

addResourceViaLoadupProxy

()

method

public function addResourceViaLoadupProxy(px:ILoadupProxy, resourceProxyName:String = null):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 LoadupResourceProxy (lrp) object for the ILoadupProxy object. Instead, the Loadup utility (LU) will create and register the lrp object, naming it as follows

use the name supplied as the second, optional argument; if supplied
otherwise, create a name by prefixing a suitable string to the name of the given ILoadupProxy object; the prefix is specified in the var prefixIfAutoLRPName, which has an initial value that should usually suffice for uniqueness i.e. const Loadup.PREFIX_IF_AUTO_LRP_NAME i.e. "luLR_"

This shortcut is probably attractive only if there are no dependencies between the resources, because the app requires references to the lrp objects, to express the dependencies.

Parameters

	`px:ILoadupProxy`

	`resourceProxyName:String` (default = `null`)

allResourcesLoaded

()

method

public function allResourcesLoaded():Boolean

Check have all the listed resources been loaded.

Returns

Boolean

cleanup

()

method

public function cleanup():void

This cleanup feature deals with removal of object state that is closely bound with this loadup monitor instance. It is recommended that the client app invoke this or an equivalent, before removing the monitor instance. The reset() operation includes this cleanup and is a valid alternative.

Specifically, cleanup includes

removal of the LoadupResourceProxy objects from the map of registered proxies.

closeResourceList

()

method

public function closeResourceList():void

If resource list is already closed, then nothing happens.

doCloseResourceList

()

method

protected function doCloseResourceList():void

doSendNotification

()

method

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

Notification type is this LoadupMonitorProxy's proxyName.

Parameters

	`notificationName:String`

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

findLRProxyByAppProxyName

()

method

protected function findLRProxyByAppProxyName(appProxyName:String):LoadupResourceProxy

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

Parameters

appProxyName:String

Returns

LoadupResourceProxy

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

getResourceViaLoadupProxyName

()

method

public function getResourceViaLoadupProxyName(proxyName:String):LoadupResourceProxy

Find the resource, that is, the LoadupResourceProxy object, where the corresponding ILoadupProxy 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 Loadup utility.

Parameters

proxyName:String

Returns

LoadupResourceProxy

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

isAnyRemainingResourceLoadable

()

method

protected function isAnyRemainingResourceLoadable():Boolean

For each resource that has not yet been processed, check is there at least one that could be loaded. The r.isOkToLoad test should reveal cases like circular linkages across the requires property of the LRP objects and a requires property that contains an LRP object that has not been added as a resource.

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.

Also, for finished, an essential condition is that the resourceList is closed.

Returns

Boolean

isLoadResourcesFeasible

()

method

protected function isLoadResourcesFeasible():Boolean

Load resources is feasible unless there something illogical about the set of resources.

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 LoadupResourceProxy that requires it. Of course, it is perfectly valid to leave the policies unchanged.

Parameters

retryParameters:IRetryParameters

removeResourceProxies

()

method

protected function removeResourceProxies():void

reset

()

method

public function reset():void

Reset the state of the monitor, so that it is ready for reuse. This includes the cleanup operation, that is, removal of the previous LoadupResourceProxy objects from the map of registered proxies.

It is recommended that the client app check via isOkToReset() before invoking reset().

Note that an alternative to reset is to instantiate a new LoadupMonitorProxy.

Throws

— 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'.

Throws

— when the given proxy name is not recognised by this LoadupMonitorProxy.

resourceHasBeenTimedOut

()

method

public function resourceHasBeenTimedOut(r:LoadupResourceProxy):void

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

Parameters

r:LoadupResourceProxy

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.

Throws

— when the given proxy name is not recognised by this LoadupMonitorProxy.

sendProgressNotification

()

method

public function sendProgressNotification():void

Sends the Loading Progress notification, with percent loaded, for client app to observe. Used internally by the Loadup utility, 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 = "luCallOutOfSyncIgnored"

INVALID_RESET_MSG

constant

protected const INVALID_RESET_MSG:String = ": LoadupMonitorProxy 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 = "luLoadingComplete"

LOADING_FINISHED_INCOMPLETE

constant

public static const LOADING_FINISHED_INCOMPLETE:String = "luLoadingFinishedIncomplete"

LOADING_PROGRESS

constant

public static const LOADING_PROGRESS:String = "luLoadingProgress"

LOAD_RESOURCE_TIMED_OUT

constant

public static const LOAD_RESOURCE_TIMED_OUT:String = "luLoadResourceTimedOut"

NAME

constant

public static const NAME:String = "LoadupMonitorProxy"

RETRYING_LOAD_RESOURCE

constant

public static const RETRYING_LOAD_RESOURCE:String = "luRetryingLoadResource"

UNKNOWN_ILOADUP_PROXY_MSG

constant

protected const UNKNOWN_ILOADUP_PROXY_MSG:String = ": Unknown ILoadupProxy in loaded/failed notification, not known in LoadupMonitorProxy instance named :"

WAITING_FOR_MORE_RESOURCES

constant

public static const WAITING_FOR_MORE_RESOURCES:String = "luWaitingForMoreResources"

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