LoadItem |
Manages the tracking, progress, and reporting for a single binary/data load. This is a more advanced version of a URLLoader or URLStream instance in that all (or most) valid Flash data types, whether binary or text-based, are supported and automatically generated upon load completion. A load of an external SWF or JPEG file, for example, is handled exactly the same way as the load of an XML document. This provides centralized manageability for loads as well as allowing data to be intercepted and manipulated (for example, decrypted) before being used.
__/ REQUIREMENTS \__
ActionScript 3.0 (or later)
__/ IMPORTS \__
com.bnm.api.instances.ErrorBroadcast com.bnm.api.instances.XMLs com.bnm.api.instances.FIFOBuffer flash.display.* flash.media.Sound flash.net.* flash.events.* flash.utils.ByteArray flash.utils.getTimer com.bnm.api.ThreadManager com.bnm.api.instances.TimeObject com.bnm.api.instances.Thread
__/ 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 con@baynewm edia.com for information, questions, concerns, or bug reports. tact
__/ 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.
LoadItem | Manages the tracking, progress, and reporting for a single binary/data load. |
Constants | |
ZLIB_HEADER | (String) The three byte signature that identifies a ZLIB compressed file. |
GIF_Header | (String) The three byte signature that identifies a GIF89s image file. |
JPEG_Header | (String) The three byte signature that identifies a JPEG image file. |
Variables | |
_content | (untyped) The object or instance into which loaded data will placed in its final, converted state. |
_type | (String) Defines the target daa type to which to convert the loaded data stored in the _content property. |
_method | (String) The server submission method to use when sendind data to the server. |
_request | (URLRequest) An instance of the <URLRequest> class used to build the request object during send/load operations. |
_stream | (URLStream) An instance of the <URLStream> class used to stream data from the server or local file. |
_trackingObject | (Object) Object used to track the progress of the current load, including calculations on average load speeds, etc. |
_buffer | (ByteArray) Used to stora raw binary data as it’s loading and after the load completes. |
_fastBuffer | (Boolean) If TRUE, the fast buffering mechanism is used to allow reading of data at a faster interval. |
_fastBufferThread | (Thread) A Thread instance used for monitoring the buffer during fast buffering operations. |
_FIFOBuffer | (FIFOBuffer) An optional <FIFOBuffer> instance to be used with this load. |
_loader | (Loader) An instance of the <Loader> class used to dynamically create display objects from a <ByteArray> once it’s been loaded from the stream. |
Functions and Properties | |
LoadItem | Constructor method for the class. |
start | Attempts to start the load operation. |
onProgress | Invoked by Flash on any <ProgressEvent> event for the associated load item. |
onSoundProgress | Trackes the progress of a <Sound> instance via <ProgressEvent> broadcasts. |
updateFastBuffer | Updates the internal fast buffer which is read on a regular interval, as opposed to the standard progress event broadcast whenever a block of data is read. |
onLoadComplete | Invoked via a standard <Event> event whenever a load operation successfully completes. |
onHTTPStatus | Invoked via a standard <HTTPStatusEvent> event whenever a load operation reports an HTTP status (404, 200, etc.) |
onSecurityError | Invoked via a standard <SecurityErrorEvent> event whenever a load operation halts due to a security restriction. |
onSecurityError | Invoked via a standard <IOErrorEvent> event whenever a load operation encounters an input/output error. |
onIOError | |
onReadLoaderBuffer | The final step in data conversion (after invoking convertData) for MovieClip, Bitmap, and Sprite types that require a buffer conversion from a ByteArray to a Loader type. |
broadcastCompletionEvent | Broadcasts the “LoadItem.COMPLETE” event when a load is ready to report that it has fully completed. |
set path | Sets the path (URL or local file reference) from which to load the asset or data from. |
path | |
get path | Returns the path value assigned to this LoadItem instance. |
path | |
get content | Returns the content object instance into which the data or asset is to be, or is being, loaded. |
content | |
set content | Dummy proprty intercept that reports an error (the _content) property may only be set internally. |
content | |
set type | Specifies the target content type into which the loaded data should be converted. |
type | |
get type | Returns the type value which will determine how the loaded data will be converted (and therefore the type of the content property). |
type | |
set method | Sets the server submission method to use when the load operation submits data. |
method | |
get method | Returns the server submission method currently being used when submitting data to the server. |
method | |
set fastBuffer | Enables or disables fast buffering for any subsequent load operation (will not affect an active one). |
fastBuffer | |
get fastBuffer | Returns the state of the fast buffer mechanism. |
fastBuffer | |
set useFIFOBuffer | Assigns a <FIFOBuffer> instance for use with this load item. |
useFIFOBuffer | |
get useFIFOBuffer | Returns a <FIFOBuffer> instance for use with this load item. |
useFIFOBuffer | |
set sendData | Assigns any data to be sent to the URL request. |
sendData | |
get sendData | Returns any data assigned to the request object for sending to the server. |
sendData | |
startFastBuffer | Begins the fast buffer thread used for more accurate updates of the transfer buffer. |
stopFastBuffer | Stops the fast buffer execution thread, if running, and cleans up the Thread instance for garbage collection. |
convertData | Converts data to the content object type based on the internal _type type. |
setDefaults | Sets default properties, instances, and values at class instantiation. |
setListeners | Sets event listeners for the class instance/API chain. |
setSoundListeners | Sets event listeners for the class instance/API chain. |
removeSoundListeners | Removes event listeners for the Sound object, typically when the load operation completes. |
private var _content: *
(untyped) The object or instance into which loaded data will placed in its final, converted state. The data type of this variable is based on the _type property of the class unless the data can’t be converted to this type (XML data converted into a MovieClip, for example).
private var _type: String
(String) Defines the target daa type to which to convert the loaded data stored in the _content property. The most universal type is “binary” (default) which will hold any type of data in a native <ByteArray>. Where possible, data will be converted but this may sometimes cause an error (if XML is loaded, for example, and the `_type` is set to “movieclip”).
private var _method: String
(String) The server submission method to use when sendind data to the server. If the sendData property hasn’t been set or has been set to NULL when the load begins, the send methos is ignored since no data is available to send. Valid values for _method include “GET” or “POST” and should be accessed via the included setter/getter methods.
private var _stream: URLStream
(URLStream) An instance of the <URLStream> class used to stream data from the server or local file. This is the instance that actually controls the data transport and a stream is used to provide buffered data access as well as to allow dynamic manipulation of the data. Unlike other loading methods, loaded data is not assumed to be of a specific type. Rather, that determination is made based on the <_target> property and automatic conversion is done once all data is loaded. Note that loads of audio data are treated differently because, as of this version of Flash, dynamic audio data assignment is not yet supported. This may change in future revisions (eg. Flash Player 10).
private var _fastBufferThread: Thread
(Thread) A Thread instance used for monitoring the buffer during fast buffering operations. The fast buffer thread is only used if the _fastBuffer valus is TRUE at the time when the load is started.
public function onProgress ( eventObj: ProgressEvent ):void
Invoked by Flash on any <ProgressEvent> event for the associated load item. This typically occurs when new data is available to read from the transfer buffer. Load progress is tracked internally and reported in a variety of ways with a re-broadcast event.
eventObj (ProgressEvent, required): A standard <ProgressEvent> object.
nothing
LoadItem.PROGRESS
nothing
no
public function onSoundProgress ( eventObj: ProgressEvent ):void
Trackes the progress of a <Sound> instance via <ProgressEvent> broadcasts. Sound loads, although reported in the same manner to any listener, are tracked differently within the Flash player.
eventObj (ProgressEvent, required): A standard <ProgressEvent> instance.
nothing
”LoadItem.PROGRESS”
nothing
no
public function updateFastBuffer ():void
Updates the internal fast buffer which is read on a regular interval, as opposed to the standard progress event broadcast whenever a block of data is read. This method, in theory, allows ready of data that is not yet available during a progress event as it is read before the event itself.
none
nothing
nothing
no
public function onLoadComplete ( eventObj: Event ):void
Invoked via a standard <Event> event whenever a load operation successfully completes. This does not mean that the loaded daa is yet ready to be used. With some data types such as Bitmaps and MovieClips, an extra asynchronous step is taken to convert them to their final target.
eventObj (Event, required): A standard <Event> instance.
nothing
nothing
nothing
no
public function onHTTPStatus ( eventObj: HTTPStatusEvent ):void
Invoked via a standard <HTTPStatusEvent> event whenever a load operation reports an HTTP status (404, 200, etc.)
eventObj (HTTPStatusEvent, required): A standard <HTTPStatusEvent> instance.
nothing
LoadItem.HTTPSTATUS
nothing
no
public function onSecurityError ( eventObj: SecurityErrorEvent ):void
Invoked via a standard <SecurityErrorEvent> event whenever a load operation halts due to a security restriction.
eventObj (SecurityErrorEvent, required): A standard <SecurityErrorEvent> instance.
nothing
LoadItem.ERROR
nothing
no
public function onReadLoaderBuffer( eventObj: Event ):void
The final step in data conversion (after invoking convertData) for MovieClip, Bitmap, and Sprite types that require a buffer conversion from a ByteArray to a Loader type. Since this is accomplished asynchonously it is invoked via an event. For other types such as XML, String, ByteArray, and Sound, no further conversion takes place.
eventObj (Event, required): A standard <Event> object instance.
nothing
nothing
nothing
public function broadcastCompletionEvent( ... args ):void
Broadcasts the “LoadItem.COMPLETE” event when a load is ready to report that it has fully completed. This method is centralize so that the format of the call may be standardized as well as providing support for FIFOBuffer functionality if it’s being used. For FIFO buffered loads, “LoadItem.FIFOCOMPLETE” is broadcast instead.
fromFIFO (Boolean, optional): Used by the <FIFOBuffer> instance to broadcast a standard completion message. If TRUE, a standard “LoadItem.COMPLETE” message is broadcast regardless of other settings, otherwise the presence of FIFO buffering is checked first and, if present, a “LoadItem.FIFOCOMPLETE” event is broadcast instead.
nothing
LoadItem.COMPLETE LoadItem.FIFOCOMPLETE
nothing
no
Returns the content object instance into which the data or asset is to be, or is being, loaded. Note that this property can’t be assigned since it’s controller internally (it’s therefore read-only).
untyped: The target object into which the data or asset will be, or is being, loaded. May be NULL if not yet assigned, otherwise it may be of any type depending on the type of data being loaded.
nothing
nothing
no
Dummy proprty intercept that reports an error (the _content) property may only be set internally.
untyped: This property is ignored.
LoadItem.ERROR
nothing
no
Specifies the target content type into which the loaded data should be converted. Valid type include “binary” (also “bin” or “b” or “bytearray” or “byte”), “movieclip” (or “movie” or “swf”), “string” (or “str or “s”), “xml” (or “x”), “xmls” (or “xs”), bitmap (or “bmp”), “sprite” (or “spr”), “sound” (or “snd”), and “shape” (or “shp”). This value is not case sensitive and if not specified or invalid, “binary” is used.
String: The target data type to which to convert the loaded data into and assign to the content property. Setting this value after a load has completed has no effect.
nothing
nothing
no
Returns the type value which will determine how the loaded data will be converted (and therefore the type of the content property). Possible values are “binary” (default, a <ByteArray> instance), “movieclip” (a <MovieClip> instance), “string” ( a <String> instance), “xml” (an <XML> instance), “xmls” (an XMLs instance), “bitmap” (a <Bitmap> instance), “sprite” (a <Sprite> instance), or “shape” (a <Shape> instance).
String: The data type to which the loaded data will be converted into and which will assigned to the content property.
nothing
nothing
no
Sets the server submission method to use when the load operation submits data. If the sendData property hasn’t been set or is NULL, the method is ignored since there is no data to submit (so only a load operation takes place).
String: The submission method to use when submitting data to the server. Valid values include “GET” and “POST” (not case sensitive). If the parameter is invalid or NULL, “GET” is set as default.
nothing
nothing
no
Returns the server submission method currently being used when submitting data to the server. This value is only used if sendData has been set, otherwise it will be ignored when the load operation begins.
String: The submission method to use when submitting data to the server. Will either be “GET” or “POST”.
nothing
nothing
no
Enables or disables fast buffering for any subsequent load operation (will not affect an active one). Fast buffering uses a Thread instance to monitor the loading buffer more frequently than when using <ProgressEvent> updates and is therefore, in theory, able to read data before update events are broadcast. Because data is checked and read much more frequently, enabling fast buffering creates more processing and memory overhead during loads, so it should be used sparringly. This value will not affect loads already in progress so it must be set before calling the start method.
Boolean: If TRUE, fast buffering is enabled. If FALSE, it is disabled.
nothing
nothing
no
Assigns a <FIFOBuffer> instance for use with this load item. When FIFOBuffering is enabled in this way, loads are sequenced even though they may be received asynchronously. That is, loads report completion in the order in which they were created rather than in the order in which they ended (which can often be somewhat random). See the <com.api.instances.FIFOBuffer> class for more information.
FIFOBuffer: A FIFOBuffer instance to assign to this load. The load instance automatically assigns itself to the <FIFOBuffer> instance as soon as this property is set, thereby assuring proper sequencing.
nothing
nothing
no
Assigns any data to be sent to the URL request. This will then be converted appropriately and sent using either a “GET” or “POST” operation to the server based on the setting of the method value. See the <URLRequest.data> property for more information on how this data is handled and converted.
Object: An object containing data to send to the server. This is typically composed of name/value pairs where the name is the property name within the object and the value is its value. Data to be sent will be automatically converted to URL-friendly formats (e.g. URL encoding) before being sent. Must not be NULL.
nothing
nothing
no
Returns any data assigned to the request object for sending to the server. See the <URLRequest.data> property for more information on how this data is handled and converted.
Object: An object containing name/value pairs to be sent to the server during a send/load operation.
nothing
nothing
no
private function startFastBuffer ():void
Begins the fast buffer thread used for more accurate updates of the transfer buffer. The typical method of updating the transfer buffer is to do so on a standard event broadcast from the stream. However, these may be infrequent and only include data in chunks. The fast buffer, in comparison runs on a timer thread and reads data immediately even if an event hasn’t yet been broadcast from the stream. To enable fast buffering, simply set this instance’s fastBuffer property to true. Be aware that this has extra processing and memory overhead since buffer checking shuffles loaded data around in memory on each thread tick.
none
nothing
nothing
nothing
no
private function stopFastBuffer ():void
Stops the fast buffer execution thread, if running, and cleans up the Thread instance for garbage collection. this method may be called blind since the Thread instance is not assumed to be active.
none
nothing
nothing
nothing
no
private function convertData ():void
Converts data to the content object type based on the internal _type type. If the loaded data cannot be converted to the target type, an error is reported along with possible remedies. Note that for certain operations this is the end of the line step wherease for other operations (such as creating Bitmap or MovieClip instances), one more step is required.
none
nothing
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
private function removeSoundListeners ():void
Removes event listeners for the Sound object, typically when the load operation completes. Because listeners are added before any new Sound load operation, they must also be removed before a subsequent load to prevent multiple event broadcasts.
none
nothing
nothing
nothing
no
(String) The three byte signature that identifies a ZLIB compressed file.
public const ZLIB_HEADER: String
(String) The three byte signature that identifies a GIF89s image file.
public const GIF_Header: String
(String) The three byte signature that identifies a JPEG image file.
public const JPEG_Header: String
(untyped) The object or instance into which loaded data will placed in its final, converted state.
private var _content: *
(String) Defines the target daa type to which to convert the loaded data stored in the _content property.
private var _type: String
(String) The server submission method to use when sendind data to the server.
private var _method: String
(URLRequest) An instance of the URLRequest class used to build the request object during send/load operations.
private var _request: URLRequest
(URLStream) An instance of the URLStream class used to stream data from the server or local file.
private var _stream: URLStream
(Object) Object used to track the progress of the current load, including calculations on average load speeds, etc.
private var _trackingObject: Object
(ByteArray) Used to stora raw binary data as it’s loading and after the load completes.
private var _buffer: ByteArray
(Boolean) If TRUE, the fast buffering mechanism is used to allow reading of data at a faster interval.
private var _fastBuffer: Boolean
(Thread) A Thread instance used for monitoring the buffer during fast buffering operations.
private var _fastBufferThread: Thread
(FIFOBuffer) An optional FIFOBuffer instance to be used with this load.
private var _FIFOBuffer: FIFOBuffer
(Loader) An instance of the Loader class used to dynamically create display objects from a ByteArray once it’s been loaded from the stream.
private var _loader: Loader
Constructor method for the class.
public function LoadItem ()
Attempts to start the load operation.
public function start ():void
Invoked by Flash on any ProgressEvent event for the associated load item.
public function onProgress ( eventObj: ProgressEvent ):void
Trackes the progress of a Sound instance via ProgressEvent broadcasts.
public function onSoundProgress ( eventObj: ProgressEvent ):void
Updates the internal fast buffer which is read on a regular interval, as opposed to the standard progress event broadcast whenever a block of data is read.
public function updateFastBuffer ():void
Invoked via a standard Event event whenever a load operation successfully completes.
public function onLoadComplete ( eventObj: Event ):void
Invoked via a standard HTTPStatusEvent event whenever a load operation reports an HTTP status (404, 200, etc.)
public function onHTTPStatus ( eventObj: HTTPStatusEvent ):void
Invoked via a standard SecurityErrorEvent event whenever a load operation halts due to a security restriction.
public function onSecurityError ( eventObj: SecurityErrorEvent ):void
public function onIOError ( eventObj: IOErrorEvent ):void
The final step in data conversion (after invoking convertData) for MovieClip, Bitmap, and Sprite types that require a buffer conversion from a ByteArray to a Loader type.
public function onReadLoaderBuffer( eventObj: Event ):void
Converts data to the content object type based on the internal _type type.
private function convertData ():void
Broadcasts the “LoadItem.COMPLETE” event when a load is ready to report that it has fully completed.
public function broadcastCompletionEvent( ... args ):void
public function set path ( pathString: String )
public function get content ():*
public function set type ( typeStr: String )
public function set method ( methodString: String )
public function set fastBuffer ( bufferSet: Boolean )
public function set useFIFOBuffer ( buffer: FIFOBuffer )
public function set sendData ( dataObject: Object )
Begins the fast buffer thread used for more accurate updates of the transfer buffer.
private function startFastBuffer ():void
Stops the fast buffer execution thread, if running, and cleans up the Thread instance for garbage collection.
private function stopFastBuffer ():void
Sets default properties, instances, and values at class instantiation.
private function setDefaults ():void
Sets event listeners for the class instance/API chain.
private function setListeners ():void
Sets event listeners for the class instance/API chain.
private function setSoundListeners ():void
Removes event listeners for the Sound object, typically when the load operation completes.
private function removeSoundListeners ():void