ErrorBroadcast

ErrorBroadcast

Used for reporting and broadcasting errors.  Errors may be fatal or non-fatal.  Non-fatal errors simply display a string in the trace window and any listening components.  Fatal errors are ones in which further execution cannot continue.

__/ REQUIREMENTS \__

ActionScript 3.0 (or later)

__/ IMPORTS \__

nothing

__/ EXTENDS \__

com.bnm.api.CoreData com.bnm.api.instances.Exception flash.utils.* flash.errors.*

__/ 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/licenses/mit-license.php).  Please refer to the accompanying text file “license.txt”, which should be distributed with every package and version of this library, for information on usage, distribution, copying, and other important information.

Please visit http://www.baynewmedia.com/ or email con.nosp@m.tact@baynewm.nosp@m.edia.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.

Summary
ErrorBroadcastUsed for reporting and broadcasting errors.
Variables
message(String) A string describing the error condition.
remedy(String) A string describing a possible solution to the problem.
code(int) An error code to include with the error broadcast and/or with the Flash runtime error dialog.
_sourceMethodName(String) The name of the source method (the method broadcasting the error).
_sourceObject(untyped) A reference to the soucre object being used to broadcast this error.
_sourceObjectID(String) The name of the source object (the object broadcasting the error).
_fullSourceObjectPath(String) The full package path (including class name) of the specified source object (the object broadcasting the error).
Functions
ErrorBroadcastCreates a new ErrorBroadcast instance.
commitCommits the error broadcast by broadcasting to all listeners and/or displays the Flash error dialog.
getSourceMethodNameReturns the method name if the specified method within the specified object.
getSourceObjectIDReturns the short class ID (not full class path) of the specified parameter object.
getSourcePathReturns the full class package path of the specified parameter object.

Variables

message

public var message: String

(String) A string describing the error condition.  Avoid including the source (e.g. class name) since this will be retreieved by the constructor.

remedy

public var remedy: String

(String) A string describing a possible solution to the problem.  Try to include specific information that can be acted on, as well as information on finding specific locations in source code, data, etc., that isn’t covered by the general object detection in the constructor.

code

public var code: int

(int) An error code to include with the error broadcast and/or with the Flash runtime error dialog.  This value is arbitrary (within the bounds of the ‘int’ data type), but it is advisable to create a standardized code system for clarity.

_sourceMethodName

private var _sourceMethodName: String

(String) The name of the source method (the method broadcasting the error).  This is determined dynamically by the class constructor.

_sourceObject

private var _sourceObject: *

(untyped) A reference to the soucre object being used to broadcast this error.  When the error is sent, it is sent as originating from this object.

_sourceObjectID

private var _sourceObjectID: String

(String) The name of the source object (the object broadcasting the error).  This is determined dynamically by the class constructor.

_fullSourceObjectPath

private var _fullSourceObjectPath: String

(String) The full package path (including class name) of the specified source object (the object broadcasting the error).  This is determined dynamically by the constructor.

Functions

ErrorBroadcast

public function ErrorBroadcast (sourceObject: *,
sourceMethod: Function,
... args)

Creates a new ErrorBroadcast instance.

Parameters

sourceObject (untyped, required): The object that is generating the error.  The object will be scanned to provide extra information for the error report. sourceMethod (function, required): The source method generating the error.  This method must reside in the sourceObject parameter otherwise it can’t be identified.This is appended to the full object path when reporting the error. message (string, optional): The error message to include with the broadcast or with the Flash runtime error dialog.  If the message isn’t set here, it should be set before calling the commit method.  I(f not supplied before calling commit, the error broadcast is not executed. remedy (string, optional): A suggested remedy to the problem.  This is a brief description of common fixes that may be attempted by the developer and/or end-user (depending on teh type of reporting mechanism chosen).  If the remedy isn’t provided, it should be set before calling the commit method.  The remedy is optional (though recommended), so the error can still be broadcast even if the remedy isn’t provided. code (int, optional): An error code to include with the broadcast or with the Flash runtime error dialog.  This value is arbitrary (within the bounds of the ‘int’ data type), but it is advisable to create a standardized code system for clarity.

Returns

ErrorBroadcast: A reference to the newly created class instance.

Broadcasts

nothing

Throws

nothing

Bubbles

no

commit

public function commit(... args):void

Commits the error broadcast by broadcasting to all listeners and/or displays the Flash error dialog.

Parameters

useExternal (Boolean, optional): If TRUE (default), an external debug event is sent (for external event listeners, for example). useCollation (Boolean, optional): If TRUE (default), two events are sent.  One is a targetted error composed of an “ClassName.ERROR” event, and one is “ErrorBroadcast.ALL” which is general.  The latter type of error is useful for listeners that want to catch all errors rather than only specific ones.

Returns

nothing

Broadcasts

”ClassName.ERROR” (“ClassName” is replaced with the fully qualified class name).  “Error.ALL” (broadcast if the “useCollation” parameter is true).

Throws

nothing

Bubbles

no

getSourceMethodName

private function getSourceMethodName(objectRef: *,
methodRef: Function):String

Returns the method name if the specified method within the specified object.

Parameters

objectRef (untyped, required): Any object to evaluate. methodRef (Function, required): A reference to the method for which to find the name.  This method must reside within the ‘objectRef’ object.

Returns

String: The method name of the specified method reference provided.  If the method can’t be found in the specified source object, NULL is returned.

Broadcasts

nothing

Throws

nothing

Bubbles

no

getSourceObjectID

private function getSourceObjectID (objectRef: *):String

Returns the short class ID (not full class path) of the specified parameter object.

Parameters

objectRef (untyped, required): Any object to evaluate for a class name.

Returns

String: The short class name of the parameter object.  Returns NULL if the parameter was NULL or otherwise invalid.

Broadcasts

nothing

Throws

nothing

Bubbles

no

getSourcePath

private function getSourcePath(objectRef: *):String

Returns the full class package path of the specified parameter object.

Parameters

objectRef (untyped, required): Any object to evaluate for a path.

Returns

String: The fully qualified class path (including class name) of the parameter object.  Returns NULL if the parameter was NULL or otherwise invalid.

Broadcasts

nothing

Throws

nothing

Bubbles

no

Provides facilities for data checking and conversion for all types of Flash data types.
public var message: String
(String) A string describing the error condition.
public var remedy: String
(String) A string describing a possible solution to the problem.
public var code: int
(int) An error code to include with the error broadcast and/or with the Flash runtime error dialog.
private var _sourceMethodName: String
(String) The name of the source method (the method broadcasting the error).
private var _sourceObject: *
(untyped) A reference to the soucre object being used to broadcast this error.
private var _sourceObjectID: String
(String) The name of the source object (the object broadcasting the error).
private var _fullSourceObjectPath: String
(String) The full package path (including class name) of the specified source object (the object broadcasting the error).
public function ErrorBroadcast (sourceObject: *,
sourceMethod: Function,
... args)
Creates a new ErrorBroadcast instance.
public function commit(... args):void
Commits the error broadcast by broadcasting to all listeners and/or displays the Flash error dialog.
private function getSourceMethodName(objectRef: *,
methodRef: Function):String
Returns the method name if the specified method within the specified object.
private function getSourceObjectID (objectRef: *):String
Returns the short class ID (not full class path) of the specified parameter object.
private function getSourcePath(objectRef: *):String
Returns the full class package path of the specified parameter object.