jump to navigation

Inaugural London Brightcove Dev Group meeting October 14, 2009

Posted by Allen Manning in : Brightcove, Event , add a comment

If you are a developer in or around London and are interested in checking out some Brightcove tech, and possibly winning some prizes, the Inagural meeting of the Brightcove Developer Group will be on the 26th of October near Monument station in London.

There will be a general coding challenge, and the best results will be eligible for winning prizes. Jeremy Allaire, CEO of Brightcove, will be there along with myself judging the entries. If the challenge has anything to do with the BC Media API, then I will be hacking away myself as an excuse to grow the new BC Actionscript Wrapper that I have just started working on.

Entry is free, and food and beer will be provided.

Even if you don’t have any previous Brightcove experience, this is a great chance to sync up with other developers and get a taste of this technology. If you are a seasoned BC developer, then this is definitely the place for you. I am looking forward to hearing thoughts about improving the product so please bring your ideas.

Entry is limited and is on a first-come first-serve basis. For more info, check this out:

http://londonbdg.eventbrite.com/

ActionScript wrapper for the Brightcove Media APIs October 13, 2009

Posted by Allen Manning in : Brightcove, Flex, Refactoring , 1 comment so far

Brightcove has made some big strides in opening up their online service to developers in the last few years.  In particular, the Brightcove Media API, a JSON-based read and write API for interacting with the Brightcove platform, is a powerful tool for online experience development.

Developers who want to assemble customized online experiences can access the media libraries created by publishers and define custom visual experiences with really no limit.  Even though this is JSON-based, access to the Media APIs is not limited to AJAX clients. ActionScript clients as well have the full wealth of the Brightcove Media API at their disposal.

Let’s start by looking at a simple example application which loads a set of videos from the Brightcove Media APIs and populates them in a datagrid.

Before:  Example Application - Loading a Datagrid with Brightcove Videos

As is available in the documentation, the below application provides a fairly straight-forward approach to loading videos:

?Download find_all_videos_before.mxml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
        xmlns:mx="http://www.adobe.com/2006/mxml">
 
    <!--
        ********************************************************************************************
        SCRIPT
        ********************************************************************************************
    -->
    <mx:Script>
    <![CDATA[
        import com.adobe.serialization.json.JSON;
        import mx.collections.ArrayCollection;
        import mx.controls.Alert;
 
        /** The object used to load URLs */
        private var _loader:URLLoader;
 
        /** The path to the brightcove api services */
        private const BRIGHTCOVE_API_PATH:String = "http://api.brightcove.com/services/library";
 
        /** The publisher token to be used to make the requests */
        private var _token:String = "0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E."
 
        /** The command string to find all videos*/
        private const FIND_ALL_COMMAND_STRING:String = "find_all_videos";
 
        /** 
         * The "click" event listener for the find_all_videos button - load the videos from 
         * Brightcove convert them for JSON to native AS Objects and populate it in a datagrid
         */  
        private function onButtonClick():void {
 
            var url:String = BRIGHTCOVE_API_PATH + 
                "?command=" + 
                FIND_ALL_COMMAND_STRING +
                "&token=" +
                _token;
 
            trace('url to request: ' + url);
            var request:URLRequest = new URLRequest(url);
 
            _loader = new URLLoader();
            _loader.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            _loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
 
            try {
                _loader.load(request);
            }
            catch (error:SecurityError) {
                trace("A SecurityError has occurred.");
            }
 
        }
 
        /** "fault" event listener to the remote call to the Brightcove media APIs */ 
        private function errorHandler(event:Event):void {
 
           mx.controls.Alert.show(
              "An error occurred" + 
                  event.target.toString(),
              "An error occurred");
 
        }
 
        /** "result" event listener to the remote call to the Brightcove media APIs */ 
        private function loaderCompleteHandler(event:Event):void {
 
            //Get the returned JSON data string
            var response:String = event.target.data as String;
 
            //The list of returned videos is embedded in the "items" property
            //of the root JSON object, so we will decode to a container
            var container:Object = (JSON.decode(response) as Object);
 
            videosDataGrid.dataProvider = new ArrayCollection(container.items);
 
            //Convert the UNIX date into an AS3 Date
            for(var i:int = 0; i< videosDataGrid.dataProvider.length; i++) {
                var video:Object = videosDataGrid.dataProvider.getItemAt(i);
                var n:Number = video.publishedDate;
                video.publishedDate = new Date(n);
            }           
 
        }
 
    ]]>
    </mx:Script>
 
    <!--
    	********************************************************************************************
    	VIEW
    	********************************************************************************************
    -->
    <mx:Button id="loadButton"
        label="Load Vidoes"
        click="onButtonClick()"/>
 
    <mx:DataGrid id="videosDataGrid"
            width="100%" height="100%">
 
        <mx:columns>
            <mx:DataGridColumn 
                dataField="id" 
                headerText="ID"/>
            <mx:DataGridColumn 
                dataField="name" 
                headerText="Name"/>
            <mx:DataGridColumn 
                dataField="shortDescription" 
                headerText="Description"/>
            <mx:DataGridColumn 
                dataField="publishedDate" 
                headerText="Published Date"/>
        </mx:columns>
    </mx:DataGrid>
 
</mx:Application>

Room for Improvement

Although the above is a good start, there are many areas of improvement. 

In particular:

After the refactoring
The below code, is the example application after it has been refactored to use a Brightcove Media API wrapper.  It cleans up the client code and frees ActionScript developers to work at a higher, more spacious level of abstraction

?Download find_all_videos_after.mxml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
        xmlns:mx="http://www.adobe.com/2006/mxml">
 
    <!--
        ********************************************************************************************
        SCRIPT
        ********************************************************************************************
    -->
    <mx:Script>
    <![CDATA[
        import com.allenmanning.brightaction.api.MediaRequestErrorType;
        import mx.controls.Alert;
        import mx.collections.ArrayCollection;
        import com.allenmanning.brightaction.api.MediaRequestType;
        import com.allenmanning.brightaction.api.MediaRequest;
 
        /** The publisher token to be used to make the requests */
        private var _token:String = "0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E."
 
        /** 
         * The "click" event listener for the find_all_videos button - work with the MediaRequest
         * Object to construct a "load videos" request, and register event listeners for handling
         * the response.
         */  
        private function onButtonClick():void {
 
            var mediaRequest:MediaRequest = new MediaRequest(
                _token,
                MediaRequestType.FIND_ALL_VIDEOS);
 
            mediaRequest.addEventListener(
                MediaRequest.RESULT_NAME,
                function():void {
                    videosDataGrid.dataProvider = mediaRequest.resultData;
                }
            );
 
            mediaRequest.addEventListener(
                MediaRequest.FAULT_NAME,
                function():void {
 
                    //tyepsafe error checking, no knowledge of BC Media API Error codes here
                    if(mediaRequest.error.errorType() == MediaRequestErrorType.INVALID_TOKEN) {
                        Alert.show("This token is not valid");
                    } else {
                        Alert.show(mediaRequest.error.errorType().toString());
                    }
 
                }
            );
 
            mediaRequest.execute();
 
        }
 
   ]]>
    </mx:Script>
 
    <!--
    	********************************************************************************************
    	VIEW
    	********************************************************************************************
    -->
    <mx:Button id="loadButton"
        label="Load Vidoes"
        click="onButtonClick()"/>
 
    <mx:DataGrid id="videosDataGrid"
            width="100%" height="100%">
 
        <mx:columns>
            <mx:DataGridColumn 
                dataField="id" 
                headerText="ID"/>
            <mx:DataGridColumn 
                dataField="name" 
                headerText="Name"/>
            <mx:DataGridColumn 
                dataField="shortDescription" 
                headerText="Description"/>
            <mx:DataGridColumn 
                dataField="publishedDate" 
                headerText="Published Date"/>
        </mx:columns>
    </mx:DataGrid>
 
</mx:Application>

In this application we have pushed the concerns of the API interaction down into the MediaRequest Object. The View is only responsible with interacting with with this wrapper or Remote Proxy.

Let’s look at a couple techniques being used here:


Typesafe and simplified error handling

The below code snippet is from MediaRequest, the object is responsible for knowing how to interact with Brightcove and parse the results. Additionally, all errors, remote faults and also client-side security exceptions are treated as being the same. It makes the interaction with the client cleaner, because there is only one type of fault to listen for.

The Media Request Object, also interacts with a collaborator: MediaRequestError. This Error object is responsible for storing all errors, client-side or server-side. All of these errors and registered, documented, with the understandable MediaRequestErrorType.

?Download MediaRequest.as
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

	  	//------------------------------------------------------------------------------------------
		// Methods
		//------------------------------------------------------------------------------------------
	    /** 
	     * Execute the Brightcove Media API asynchronous request for the token based upon the given 
	     * Media Request type.  
	     * 
	     * If a result has been returned, populate this object with the result converted into native
	     * AS3 objects, not JSON, and dispatch an event notifing listeners of this object that the 
	     * request has been completed.
	     * 
	     * If a fault has been returned, store the fault in this object and dispatch a Fault event 
	     * notifying listeners that a fault has occured.
	     */
	    public function execute():void {
 
	        // initilize existing result data
	        _resultData = null;
            _error = null;
 
            var url:String = BRIGHTCOVE_API_PATH + 
                "?command=" + 
                _requestType.toString() +
                "&token=" +
                _readToken;
 
            var request:URLRequest = new URLRequest(url);
 
            _loader = new URLLoader();
            _loader.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            _loader.addEventListener(Event.COMPLETE, loaderCompleteHandler);
 
            try {
                _loader.load(request);
            } catch (error:SecurityError) {
                handleErrors(
                    new MediaRequestError(
                        MediaRequestErrorType.FLASH_SECURITY_ERROR, 
                        error));
            }
 
	    }
 
        /** Construct an error object and dispatch a fault event */
        private function handleErrors(error:MediaRequestError):void {
 
            _error = error;
            dispatchEvent(new Event(MediaRequest.FAULT_NAME));
 
        }
 
        /** "fault" event listener to the remote call to the Brightcove media APIs */ 
        private function ioErrorHandler(event:Event):void {
 
            handleErrors(new MediaRequestError(MediaRequestErrorType.IO_ERROR, event));
 
        }
 
        /**
         * Return true if the result of the call should be considerd a fault, false otherwise
         * 
         * @param result    the media API result as an ActionScript object
         */
        private function checkAndSetFault(result:Object):void {
 
            if(MediaRequestError.hasError(result)) {
 
                handleErrors(MediaRequestError.createFromResponse(result));
 
            }
 
        }
 
        /** "result" event listener to the remote call to the Brightcove media APIs */ 
        private function loaderCompleteHandler(event:Event):void {
 
            //Get the returned JSON data string
            var response:String = event.target.data as String;
 
            //The list of returned videos is embedded in the "items" property
            //of the root JSON object, so we will decode to a container
 
            //TODO Make the JSON decoding pluggable
            var result:Object = (JSON.decode(response) as Object);
 
            checkAndSetFault(result);
 
            if(_error != null) {
                return;
            }
 
            _resultData = new ArrayCollection(result.items);
 
            //Convert the UNIX date into an AS3 Date
            for(var i:int = 0; i< _resultData.length; i++) {
 
                var video:Object = _resultData.getItemAt(i);
                var n:Number = video.publishedDate;
                video.publishedDate = new Date(n);
 
            }           
 
            dispatchEvent(new Event(MediaRequest.RESULT_NAME));
 
        }


Self Documenting and Typesafe Error Handling with an AS “Enumeration”

Rather than sprinkling error parsing and checking code throughout our Brightcove ActionScript applications, defining them in a typesafe enum is a cleaner and more centralized place to document these conditions and lets other objects work with how they should be handled.

Without real Enum support, we define a set of static constants which are themselves instances a of the MediaRequestErrorType. This object defines a fault name and also registers and associated Error Code (if applicable).

The getErrorForCode() method lets us return a unqiue ErrorType object for a given error code. By using this registration-based approach, we have avoided any long conditional or awkward switch statements. As new errors are discovered, they are simply registered with this object, in a single location.

?Download MediaRequestErrorType.as
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

package com.allenmanning.brightaction.api {
 
    /**
     * An enumeration modeling the different types of Media Requests Errors
     * 
     * @author amanning
     */
    public class MediaRequestErrorType {
 
        //------------------------------------------------------------------------------------------
        // Member variables
        //------------------------------------------------------------------------------------------
        // Invalid Token was passed to the Media APIs
        public static const INVALID_TOKEN:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("INVALID_TOKEN", 210);
 
        // Request Validation Errors
        public static const VALIDATION_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("VALIDATION_ERROR", 301);
 
        // Flash Communication Security Error
        public static const FLASH_SECURITY_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("FLASH_SECURITY_ERROR");
 
        // IO Error, a problem with issuing the HTTP Get request to the media API
        public static const IO_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("IO_ERROR");
 
        // Unknown Error, either not mapped into this wrapper API, or not invalid construction on 
        // the server
        public static const UNKNOWN_ERROR:MediaRequestErrorType = 
            MediaRequestErrorType.createAndRegister("UNKNOWN_ERROR");
 
        /** The toString value for the enum */
        private var _value:String;
 
        /** Return a string representation of this type */
        public function toString():String {
 
            return _value;
 
        }
 
        /** The error code associated with the error, if any */
        private var _code:Number;
 
        public function code():Number {
 
            return _code;
 
        }
 
        /** A look-up table for all of the codes, this gets initialized in the class constructor */
        private static var _codeLookupTable:Object;
 
        //------------------------------------------------------------------------------------------
        // Constructors
        //------------------------------------------------------------------------------------------
        /**
         * Class constructor - initialize the string representation of this enum
         * 
         * @param value     The string representation of this enum
         * @param code      An associated error code, if any
         */ 
        function MediaRequestErrorType(value:String,code:Number=-1) {
 
            _value = value;
            _code = code;
 
        }
 
        //------------------------------------------------------------------------------------------
        // Methods
        //------------------------------------------------------------------------------------------
 
        /**
         * Given a value and a code, create an error type and register it with the error lookup 
         * table
         * 
         * @param value     The string representation of this enum
         * @param code      An associated error code, if any
         * @return          Registered Media Request Error type
         */
        public static function createAndRegister(
                value:String,
                code:Number=-1):MediaRequestErrorType {
 
            var errorType:MediaRequestErrorType = new MediaRequestErrorType(value,code);
 
            if(_codeLookupTable == null) {
                _codeLookupTable = new Object();
            }
 
            if(errorType.code() != -1 && !_codeLookupTable.hasOwnProperty(code)) {
 
                _codeLookupTable[code] = errorType;
 
            }
 
            return errorType;
 
        }
 
        /**
         * Given an error code, return the corresponding ErrorType object, if it exists, or null 
         * otherwise
         * 
         * @param code  the error code to look up
         * @return      the corresponding ErrorType object, if it exists, or null otherwise
         */
        public static function getErrorForCode(code:Number):MediaRequestErrorType {
 
            if(_codeLookupTable.hasOwnProperty(code)) {
 
                return _codeLookupTable[code];
 
            }
 
            return null;
 
        }
 
    }   
 
}

Where to go from here?
A working example of this can be downloaded here, along with a set of Flexunit tests supporting this wrapper.

This is just the beginning, there are many places to go from here: