LoadManager |
Manages binary/data loads for the API. Most data send/load operations are handled transparently and with as many default paramaters as possible. In this way, loads can be “started and forgotten” if extra controls are not required. However, extra details are provided whenever more control in the application is desired.
Most of the operations within LoadManager may be either addressed directly or via event broadcasts. To facilitate this, loads or sends are typically not started automatically in order to give the host application a chance to set up receiving event listeners for items like load progress, errors, and so on.
All server interactions are based on the request-response paradigm and so return data (even if only a status response) will always be expected. Data is loaded into a binary buffer using streaming mechanisms so that is is available directly to the application even while still being read.
For a complete list of all functionality and data available through the BNMAPI instance, refer to the API documentation or to each class individually. Remember that since this is a singleton, all methods and members are available directly through this single reference.
__/ REQUIREMENTS \__
ActionScript 3.0 (or later)
__/ IMPORTS \__
com.bnm.api.instances.ErrorBroadcast com.bnm.api.instances.LoadItem com.bnm.api.instances.FIFOBuffer
__/ EXTENDS \__
com.bnm.api.ThreadManager
__/ IMPLEMENTS \__
nothing
__/ NOTICE \__
©opyright 2008 Bay New Media. All rights, as stipulated in the The MIT License, are reserved.
This ActionScript library is licensed and released under the MIT License (http://www.opensource.org
Please visit http://www.baynewmedia.com/ or email contact@baynewmedia.com for information, questions, concerns, or bug reports.
__/ NOTES \__
This class is commented using the NaturalDocs documentation system. It is intended to be easily read both from the direct source code and from an adaptation that is generated as hyperlinked HTML. The NaturalDocs specification used in this class’ documentation is version 1.35 though older versions may probably be used safely. For more information, please visit: http://www.naturaldocs.org/
The BNMAPI is officially available (primary sources) on Source Forge (http://sourceforge.net/projects/bnmapi/), on the Bay New Media site (http;//www.baynewmedia.com/), on the PeaBee project site (http://www.peabee.com/), and through the Bay New Media SVM repository server (visit http://www.baynewmedia.com/ for more information). Downloads from other sources may not be complete or up-to-date.
If you’re interested in joining the BNMAPI project in any capacity (development, testing, distribution, etc.), please visit us on Source Forge or the Bay New Media web site.
| LoadManager | Manages binary/data loads for the API. |
| Variables | |
| LoadManager_timeout | LoadManager_timeout (uint): Static class variable used to store the global timeout value for loads. |
| LoadManager_loadQueue | LoadManager_loadQueue (Array): Stores loads that have not yet completed (waiting to begin or in progress) in the queue. |
| LoadManager_concurrentLoadLimit | LoadManager_concurrentLoadLimit (uint): Specifies the number of loads that may be running at the same time (concurrently) at any given time. |
| LoadManager_concurrentLoads | LoadManager_concurrentLoads (uint): Tracks the number of active concurrent loads. |
| Functions and Properties | |
| LoadManager | Constructor method for the class. |
| onCreateLoadEvent | Invoked via the “LoadManager.CREATELOAD” event and is used as the event listener gateway for the createLoad method. |
| createLoad | loadObject (Object, required): An object containing the parameters to be associated with the load item. |
| startLoad | Begins an asset or data load from the network or local file location. |
| onLoadEnd | All-purpose method used for tracking the end of a load. |
| createNewFIFOBuffer | Creates a new <FIFOBuffer> for use with loads that need to retain sequencing. |
| set loadTimeout | Sets the timeout value (in seconds) for all subsequent load operations. |
| loadTimeout | |
| get loadTimeout | Returns the current timeout value for loads. |
| loadTimeout | |
| set concurrentLoadLimit | Sets the limit value on the number of allowable concurrent loads. |
| concurrentLoadLimit | |
| get concurrentLoadLimit | Returns the limit value on the number of allowable concurrent loads. |
| concurrentLoadLimit | |
| get maxConcurrentLoads | Returns TRUE if the number of current active loads has reached the allowable limit, otherwise FALSE is returned. |
| maxConcurrentLoads | |
| setListeners | Sets event listeners for the class instance/API chain. |
private static var LoadManager_timeout: uint
LoadManager_timeout (uint): Static class variable used to store the global timeout value for loads. This value is used whenever a new load is created and a custom timeout value is not assigned to it. The default value is 30 (seconds) but this may be changed via the loadTimeout setter getter methods. Any loads created prior to updating this value will be unaffected.
private static var LoadManager_loadQueue: Array
LoadManager_loadQueue (Array): Stores loads that have not yet completed (waiting to begin or in progress) in the queue. If the number of files currently loading has reached the concurrent limit, loads will be added to this array until concurrent loads complete or fail. Only loads that are set to start immediately will bypass this queue.
private static var LoadManager_concurrentLoadLimit: uint
LoadManager_concurrentLoadLimit (uint): Specifies the number of loads that may be running at the same time (concurrently) at any given time. If this limit is reached, new loads are added to the queue and are started as soon as other loads complete, time out, or experience load errors. Default is set to 10. If set to 0, no load limit is imposed (all loads begin right away regardless of how many other loads are active). Setter/getter methods are included.
private static var LoadManager_concurrentLoads: uint
LoadManager_concurrentLoads (uint): Tracks the number of active concurrent loads. This is not the number of items in the queue but rather the number of items currently loading. This value is automatically adjusted every time a load ends, times out, or encounters an error.
public function onCreateLoadEvent ( eventObj: Object ):void
Invoked via the “LoadManager.CREATELOAD” event and is used as the event listener gateway for the createLoad method. Contents of the event object’s “loadObject” parameter should mimic the parameter listing of the createLoad method as this is passed directly to that method.
eventObj (Object, required): A standard BNMAPI-based event object. Properties must include: loadObject (Object, required): An object containing all of the parameter properties to be sent directly to the createLoad method. For a full list, please refer to that method’s parameter list.
”LoadManager.ERROR”
nothing
nothing
no
public function createLoad ( loadObject: Object ):LoadItem
loadObject (Object, required): An object containing the parameters to be associated with the load item. These include: path (String, required): The local path or URL (relative or absolute) of the item to load. If omitted or clearly invalid, the operation fails immediately. target (untyped, required): This parameter specifies the target into which the loaded data will be placed. The loader will automatically determine the data type to convert the loaded data into. This value may be of any type but must not be null. As with any load operation, any data in the target object will be wiped out when the load completes. send (Object, optional): Optional object containing data to send to the server before attempting the load operation. This is similar to the “sendAndLoad” operation in ActionScript 2. If omitted, only a load operation takes place. This value is subject to the constraints put on the <flash.net.URLRequest.data> object. For example, if binary data is placed into this object, a “POST” operation is used by default to send the data. sendMethod (String, optional): An optional send method for submitting data to the server. Valid values are “GET” and “POST”. This value is not case sensitive and only applies if the “send” parameter is specified. If omitted or incorrect, “GET” is used as default. fastBuffer (Boolean, optional): If TRUE, the read buffer is updated more frequently and therefore allows data to be read more precisely as it’s being read. However, this takes up more system resources. When FALSE (default), the buffer is updated less often and therefore consumes fewer resources. Fast buffering is not supported on Sound target loads (this value is ignored). FIFOBuffer (FIFOBuffer, optional): Instance of the <FIFOBuffer> class to use if FIFO bufering is desired. See the <FIFOBufer> class for more information on load sequencing and how to use this type of buffering. immediate (Boolean, optional): If TRUE, the load will be started immediately, bypassing any queue controls and even before this method returns. If FALSE (default), the startLoad method must be invoked manually. timeout (uint, optional): A timeout value, in seconds, that will apply to this load. A load times out when this number of seconds elapses without any transfer activity. Whenever new data is detected, this counter is reset. If not supplied or of the wrong type, the static LoadManager_timeout value will be used.
LoadItem: A reference to the LoadItem instance that will be handling this load. Use this reference to create targetted listeners or to directly access the LoadItem instance when desired. If there was a problem creatin the load, NULL will be returned.
LoadManager.ERROR
nothing
no
public function startLoad ( loadItem: LoadItem, ... args ):Boolean
Begins an asset or data load from the network or local file location. Loads are queued based on internal limits so unless queueing is bypassed using the second parameter, the load may ot immediately begin to load.
loadItem (LoadItem, required): A reference to the LoadItem instance to begin loading. immediate (Boolean, optional): If TRUE, the load is started immediately regardless of the number of items in the queue.
Boolean: TRUE if the load was started successfully, FALSE if the load could not be immediately started (usually because the concurrent load limit has been reached).
nothing
nothing
no
public function onLoadEnd ( eventObj: Object ):void
All-purpose method used for tracking the end of a load. This is invoked whenever a load ends successfully or not and is used for internal load tracking and queue processing.
eventObj (Object, required): A standard BNMAPI event object.
nothing
nothing
nothing
no
public function createNewFIFOBuffer():FIFOBuffer
Creates a new <FIFOBuffer> for use with loads that need to retain sequencing. See the <FIFOBuffer> class for more information on load sequencing and implementation. This method is provided for easy access to new <FIFOBuffer> instances but a new instance may be created manually as well. Use the <FIFOBuffer> instance together with the createLoad method’s `FIFIOBuffer` parameter to enable sequencing for all associated loads.
none
FIFOBuffer: An instance of the FIFOBuffer class used for load sequencing.
nothing
nothing
<com.bnm.api.instances.FIFOBuffer>
Sets the timeout value (in seconds) for all subsequent load operations. Operations already created or in progress will be unaffected by this change. Timeouts occur when a certain amount of inactivity, as specified by this value occurs during a load operation. In other words, if this value is set to 30, no data must be received on the load in 30 seconds before it’s considered timed out. If any data is received during that interval, the timeout counter is reset. This is a global value but may be overriden on a per-load basis when creating a new load.
timeoutVal (uint): The timeout value, in seconds, to apply to all subsequent loads.
nothing
nothing
no
Returns the current timeout value for loads. This value may not necessarily be applied to all loads since only loads created after setting the loadTimeout value will be updated.
uint: The timeout value, in seconds, currently being used for loads.
nothing
nothing
no
Sets the limit value on the number of allowable concurrent loads. If this many loads are currently active, an attempt to start a new load normally will cause it to be pushed into the queue until an active load completes, times out, or encounters an error. This is an effective way to throttle the number of open connections if network load is a problem on application clients or servers.
uint: The number of allowable concurrent loads. If 0, all loads are started immediately upon request.
nothing
nothing
no
Returns the limit value on the number of allowable concurrent loads. If this many loads are currently active, an attempt to start a new load normally will cause it to be pushed into the queue until an active load completes, times out, or encounters an error. This is an effective way to throttle the number of open connections if network load is a problem on application clients or servers.
uint: The number of allowable concurrent loads.
nothing
nothing
no
Returns TRUE if the number of current active loads has reached the allowable limit, otherwise FALSE is returned. This is the best method of determining whether or not another load may be started immediately since there are a few different considerations that produce this value.
Boolean: TRUE if another load can be allowed to start at this time, FALSE if the concurrency limit disallows it.
nothing
nothing
no
private function setListeners ():void
Sets event listeners for the class instance/API chain. These are used as a secondary access mechanism for the LoadManager instance. Note that external broadcasts will be rejected as it is assumed that since another instance of the API is running remotely, that instance should manage its own loads.
none
nothing
nothing
nothing
no
LoadManager_timeout (uint): Static class variable used to store the global timeout value for loads.
private static var LoadManager_timeout: uint
LoadManager_loadQueue (Array): Stores loads that have not yet completed (waiting to begin or in progress) in the queue.
private static var LoadManager_loadQueue: Array
LoadManager_concurrentLoadLimit (uint): Specifies the number of loads that may be running at the same time (concurrently) at any given time.
private static var LoadManager_concurrentLoadLimit: uint
LoadManager_concurrentLoads (uint): Tracks the number of active concurrent loads.
private static var LoadManager_concurrentLoads: uint
Constructor method for the class.
public function LoadManager ()
Invoked via the “LoadManager.CREATELOAD” event and is used as the event listener gateway for the createLoad method.
public function onCreateLoadEvent ( eventObj: Object ):void
loadObject (Object, required): An object containing the parameters to be associated with the load item.
public function createLoad ( loadObject: Object ):LoadItem
Begins an asset or data load from the network or local file location.
public function startLoad ( loadItem: LoadItem, ... args ):Boolean
All-purpose method used for tracking the end of a load.
public function onLoadEnd ( eventObj: Object ):void
Creates a new FIFOBuffer for use with loads that need to retain sequencing.
public function createNewFIFOBuffer():FIFOBuffer
public function set loadTimeout ( timeoutVal: uint )
public function set concurrentLoadLimit ( limit: uint )
public function get maxConcurrentLoads ():Boolean
Sets event listeners for the class instance/API chain.
private function setListeners ():void