/*****************************************************
*
* Copyright 2009 Adobe Systems Incorporated. All Rights Reserved.
*
*****************************************************
* The contents of this file are subject to the Mozilla Public License
* Version 1.1 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
* License for the specific language governing rights and limitations
* under the License.
*
*
* The Initial Developer of the Original Code is Adobe Systems Incorporated.
* Portions created by Adobe Systems Incorporated are Copyright (C) 2009 Adobe Systems
* Incorporated. All Rights Reserved.
*
*****************************************************/
package org.osmf.media
{
import __AS3__.vec.Vector;
import flash.events.EventDispatcher;
import flash.utils.Dictionary;
import org.osmf.elements.ProxyElement;
import org.osmf.events.MediaFactoryEvent;
import org.osmf.events.PluginManagerEvent;
import org.osmf.media.pluginClasses.PluginManager;
import org.osmf.utils.OSMFStrings;
/**
* Dispatched when the MediaFactory has successfully loaded a plugin.
*
* @eventType org.osmf.events.MediaFactoryEvent.PLUGIN_LOAD
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="pluginLoad", type="org.osmf.events.MediaFactoryEvent")]
/**
* Dispatched when the MediaFactory has failed to load a plugin due to an error.
*
* @eventType org.osmf.events.MediaFactoryEvent.PLUGIN_LOAD_ERROR
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="pluginLoadError", type="org.osmf.events.MediaFactoryEvent")]
/**
* Dispatched when the MediaFactory has created a MediaElement.
*
* @eventType org.osmf.events.MediaFactoryEvent.MEDIA_ELEMENT_CREATE
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
[Event(name="mediaElementCreate", type="org.osmf.events.MediaFactoryEvent")]
/**
* MediaFactory represents a factory class for media elements.
*
* <p>The factory operation takes a MediaResourceBase as input and produces a MediaElement
* as output.</p>
* <p>The MediaFactory maintains a list of MediaFactoryItem objects,
* each of which encapsulates all the information necessary to create
* a specific MediaElement. The MediaFactory relies on
* the canHandleResourceFunction method of each MediaFactoryItem to find a
* MediaFactoryItem object that can handle the specified MediaResourceBase.</p>
*
* <p>The factory interface also exposes methods for querying for specific MediaFactoryItem
* objects, and for loading plugins (which hold MediaFactoryItem objects).</p>
*
* @see MediaFactoryItem
* @see MediaResourceBase
* @see MediaElement
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*
* @includeExample MediaFactoryExample.as -noswf
*/
public class MediaFactory extends EventDispatcher
{
/**
* Constructor.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function MediaFactory()
{
super();
allItems = new Dictionary();
}
/**
* Adds the specified MediaFactoryItem to the factory.
* After the MediaFactoryItem has been added, for any MediaResourceBase
* that this MediaFactoryItem can handle, the factory will be able to create
* the corresponding media element.
*
* If a MediaFactoryItem with the same ID already exists in this
* factory, the new MediaFactoryItem object replaces it.
*
* @param item The MediaFactoryItem to add.
*
* @throws ArgumentError If the argument is <code>null</code> or if the argument
* has a <code>null</code> ID field.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function addItem(item:MediaFactoryItem):void
{
if (item == null || item.id == null)
{
throw new ArgumentError(OSMFStrings.getString(OSMFStrings.INVALID_PARAM));
}
var items:Vector.<MediaFactoryItem> = findOrCreateItems(item.type);
// Make sure to overwrite any duplicate.
var existingIndex:int = getIndexOfItem(item.id, items);
if (existingIndex != -1)
{
items[existingIndex] = item;
}
else
{
items.push(item);
}
}
/**
* Removes the specified MediaFactoryItem from the factory.
*
* If no such MediaFactoryItem exists in this factory, does nothing.
*
* @param item The MediaFactoryItem to remove.
*
* @throws ArgumentError If the argument is <code>null</code> or if the argument
* has a <code>null</code> ID field.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function removeItem(item:MediaFactoryItem):void
{
if (item == null || item.id == null)
{
throw new ArgumentError(OSMFStrings.getString(OSMFStrings.INVALID_PARAM));
}
var items:Vector.<MediaFactoryItem> = allItems[item.type];
if (items != null)
{
var existingIndex:int = items.indexOf(item);
if (existingIndex != -1)
{
items.splice(existingIndex, 1);
}
}
}
/**
* The number of MediaFactoryItems managed by the factory.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function get numItems():int
{
var numItems:int = 0;
for each (var type:String in MediaFactoryItemType.ALL_TYPES)
{
var items:Vector.<MediaFactoryItem> = allItems[type];
if (items != null)
{
numItems += items.length;
}
}
return numItems;
}
/**
* Gets the MediaFactoryItem at the specified index.
*
* @param index The index in the list from which to retrieve the MediaFactoryItem.
*
* @return The MediaFactoryItem at that index or <code>null</code> if there is none.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function getItemAt(index:int):MediaFactoryItem
{
var result:MediaFactoryItem = null;
if (index >= 0)
{
for each (var type:String in MediaFactoryItemType.ALL_TYPES)
{
var items:Vector.<MediaFactoryItem> = allItems[type];
if (items != null)
{
if (index < items.length)
{
result = items[index];
break;
}
else
{
// Not in this list, try the next.
index -= items.length;
}
}
}
}
return result;
}
/**
* Returns the MediaFactoryItem with the specified ID or <code>null</code> if the
* specified MediaFactoryItem does not exist in this factory.
*
* @param The ID of the MediaFactoryItem to retrieve.
*
* @return The MediaFactoryItem with the specified ID or <code>null</code> if the specified
* MediaFactoryItem does not exist in this factory.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function getItemById(id:String):MediaFactoryItem
{
var result:MediaFactoryItem = null;
for each (var type:String in MediaFactoryItemType.ALL_TYPES)
{
var items:Vector.<MediaFactoryItem> = allItems[type];
if (items != null)
{
var existingIndex:int = getIndexOfItem(id, items);
if (existingIndex != -1)
{
result = items[existingIndex];
break;
}
}
}
return result;
}
/**
* Load a plugin identified by the specified resource. The MediaFactory will not
* reload the plugin if it has already been loaded. Upon successful loading, the
* MediaFactoryItems within the plugin's PluginInfo property will be added to
* this MediaFactory, and a MediaFactoryEvent.PLUGIN_LOAD event will be dispatched.
* OtherwiseIf the load fails, a MediaFactoryEvent.PLUGIN_LOAD_ERROR event will be
* dispatched.
*
* @param resource MediaResourceBase representing the plugin. For remote (dynamic)
* plugins, use an URLResource pointing to the remote SWF to load. For local
* (static) plugins, use a PluginInfoResource.
*
* @throws ArgumentError If resource is null or resource is neither an URLResource
* nor a PluginInfoResource.
*
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function loadPlugin(resource:MediaResourceBase):void
{
createPluginManager();
pluginManager.loadPlugin(resource);
}
/**
* Returns a MediaElement that can be created based on the specified
* MediaResourceBase.
* <p>Returns <code>null</code> if the factory cannot
* find a MediaFactoryItem object
* capable of creating such a MediaElement in this factory.</p>
*
* @param resource The MediaResourceBase for which a corresponding
* MediaElement should be created.
*
* @return The MediaElement that was created or <code>null</code> if no such
* MediaElement could be created from the resource.
*
* @langversion 3.0
* @playerversion Flash 10
* @playerversion AIR 1.5
* @productversion OSMF 1.0
*/
public function createMediaElement(resource:MediaResourceBase):MediaElement
{
// Make sure we have a plugin manager before creating a MediaElement, so
// that it will catch the mediaElementCreate event.
createPluginManager();
// Note that proxies are resolved before creation callbacks are called:
// if a media element is proxied, then the creation callback will be invoked
// with the root proxy, not the wrapped media element.
//
// We attempt to create a MediaElement of the STANDARD type.
var mediaElement:MediaElement = createMediaElementByResource(resource, MediaFactoryItemType.STANDARD);
if (mediaElement != null)
{
var proxyElement:MediaElement =
createMediaElementByResource
( mediaElement.resource
, MediaFactoryItemType.PROXY
, mediaElement /* element to wrap */
);
// If we have a corresponding ProxyElement, then instead of
// returning the STANDARD MediaElement, we instead return that
// PROXY element as the wrapper for the STANDARD element.
mediaElement = (proxyElement != null ? proxyElement : mediaElement);
// Inform clients of the creation.
dispatchEvent
( new MediaFactoryEvent
( MediaFactoryEvent.MEDIA_ELEMENT_CREATE
, false
, false
, null
, mediaElement
)
);
}
return mediaElement;
}
// Protected
//
/**
* Returns the most appropriate MediaFactoryItem for the specified resource
* out of the MediaFactoryItems in the specified list.
*
* This method is invoked when <code>createMediaElement</code> is invoked
* with a resource that more than one MediaFactoryItem can handle. Subclasses
* can override to select the most appropriate one.
*
* The default behavior is to select the first item which is not "native" to
* the framework, under the theory that plugins ought to take precedence over
* core media types. It makes this decision based on the presence or absence
* of an id value which starts with "org.osmf".
*/
protected function resolveItems(resource:MediaResourceBase, items:Vector.<MediaFactoryItem>):MediaFactoryItem
{
if (resource == null || items == null)
{
return null;
}
var firstNativeItem:MediaFactoryItem = null;
for (var i:int = 0; i < items.length; i++)
{
var item:MediaFactoryItem = items[i] as MediaFactoryItem;
if (item.id.indexOf("org.osmf") == -1)
{
// Non-native, we'll take it.
return item;
}
else if (firstNativeItem == null)
{
firstNativeItem = item;
}
}
return firstNativeItem;
}
// Internals
//
private function findOrCreateItems(type:String):Vector.<MediaFactoryItem>
{
if (allItems[type] == null)
{
allItems[type] = new Vector.<MediaFactoryItem>();
}
return allItems[type] as Vector.<MediaFactoryItem>;
}
private function createMediaElementByResource
( resource:MediaResourceBase
, itemType:String
, wrappedElement:MediaElement=null
):MediaElement
{
var mediaElement:MediaElement = null;
var items:Vector.<MediaFactoryItem> = getItemsByResource(resource, allItems[itemType]);
if (itemType == MediaFactoryItemType.STANDARD)
{
var item:MediaFactoryItem = resolveItems(resource, items) as MediaFactoryItem;
if (item != null)
{
mediaElement = invokeMediaElementCreationFunction(item);
}
}
else if (itemType == MediaFactoryItemType.PROXY)
{
var nextElementToWrap:MediaElement = wrappedElement;
// Create our chain of proxies, starting from the bottom so
// that we can assign the base wrapped element. (Note that
// we iterate from the end to the beginning simply to make
// it easier to assign the wrappedElement in our for loop.
// In the future, we may want to provide control for the
// ordering to the client through some type of resolver method.
for (var i:int = items.length; i > 0; i--)
{
var proxyItem:MediaFactoryItem = items[i-1] as MediaFactoryItem;
var proxyElement:ProxyElement = invokeMediaElementCreationFunction(proxyItem) as ProxyElement;
if (proxyElement != null)
{
proxyElement.proxiedElement = nextElementToWrap;
nextElementToWrap = proxyElement;
}
}
mediaElement = nextElementToWrap;
}
if (mediaElement != null)
{
mediaElement.resource = resource;
}
return mediaElement;
}
private static function getItemsByResource(resource:MediaResourceBase, items:Vector.<MediaFactoryItem>):Vector.<MediaFactoryItem>
{
var results:Vector.<MediaFactoryItem> = new Vector.<MediaFactoryItem>();
for each (var item:MediaFactoryItem in items)
{
if (item.canHandleResourceFunction(resource))
{
results.push(item);
}
}
return results;
}
private static function getIndexOfItem(id:String, items:Vector.<MediaFactoryItem>):int
{
for (var i:int = 0; i < items.length; i++)
{
var item:MediaFactoryItem = items[i] as MediaFactoryItem;
if (item.id == id)
{
return i;
}
}
return -1;
}
private function onPluginLoad(event:PluginManagerEvent):void
{
dispatchEvent(new MediaFactoryEvent(MediaFactoryEvent.PLUGIN_LOAD, false, false, event.resource));
}
private function onPluginLoadError(event:PluginManagerEvent):void
{
dispatchEvent(new MediaFactoryEvent(MediaFactoryEvent.PLUGIN_LOAD_ERROR, false, false, event.resource));
}
private function invokeMediaElementCreationFunction(item:MediaFactoryItem):MediaElement
{
var mediaElement:MediaElement = null;
try
{
mediaElement = item.mediaElementCreationFunction();
}
catch (error:Error)
{
// Swallow, the creation function is wrongly specified.
// We'll just return a null MediaElement.
}
return mediaElement;
}
private function createPluginManager():void
{
if (pluginManager == null)
{
pluginManager = new PluginManager(this);
pluginManager.addEventListener(PluginManagerEvent.PLUGIN_LOAD, onPluginLoad);
pluginManager.addEventListener(PluginManagerEvent.PLUGIN_LOAD_ERROR, onPluginLoadError);
}
}
private var pluginManager:PluginManager;
private var allItems:Dictionary;
// Keys are: String (MediaFactoryItemType)
// Values are: Vector.<MediaFactoryItem>
}
}
