1/*****************************************************
2*
3*  Copyright 2009 Adobe Systems Incorporated.  All Rights Reserved.
4*
5*****************************************************
6*  The contents of this file are subject to the Mozilla Public License
7*  Version 1.1 (the "License"); you may not use this file except in
8*  compliance with the License. You may obtain a copy of the License at
9*  http://www.mozilla.org/MPL/
10*
11*  Software distributed under the License is distributed on an "AS IS"
12*  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
13*  License for the specific language governing rights and limitations
14*  under the License.
15*
16*
17*  The Initial Developer of the Original Code is Adobe Systems Incorporated.
18*  Portions created by Adobe Systems Incorporated are Copyright (C) 2009 Adobe Systems
19*  Incorporated. All Rights Reserved.
20*
21*****************************************************/
22package org.osmf.traits
23{
24	import flash.events.EventDispatcher;
25
26	/**
27	 * A MediaTraitBase is the encapsulation of a trait or capability that's
28	 * inherent to a MediaElement.  The sum of all traits on a media element
29	 * define the overall capabilities of the media element.
30	 *
31	 * <p>Media traits are first-class members of the object model for a
32	 * number of reasons:</p>
33	 * <ul>
34	 * <li>
35	 * Traits allow us to isolate common aspects of different media types into
36	 * reusable building blocks.  For example, music and video may share a
37	 * common implementation for audio.  An "audio" trait can encapsulate
38	 * that common implementation in such a way that it can be used for both
39	 * media types, while still providing a uniform interface to these
40	 * different media types.
41	 * </li>
42	 * <li>
43	 * Different media elements may have their capabilities change dynamically
44	 * over time, and traits allow us to isolate these capabilities in such
45	 * a way that we can clearly express that dynamism.  For example, a video
46	 * player might not initially be "viewable", due to its need to be loaded
47	 * before playback can begin.  Rather than express this dynamism through
48	 * changes to a set of methods on a monolithic media class, we can express
49	 * it through the presence or absence of a trait instance on a lighter
50	 * weight media class.
51	 * </li>
52	 * <li>Traits make compositioning scalable.  (Compositioning is the ability
53	 * to temporally and spatially composite collections of media.)  If traits
54	 * represent the overall vocabulary of the media framework, then we can
55	 * implement compositioning primarily in terms of the traits, rather than
56	 * in terms of the media that aggregate those traits.  This approach allows
57	 * developers to create new media implementations that can easily integrate
58	 * with the compositioning parts of the framework without requiring changes
59	 * to that framework.  Our working assumption, of course, is that most (if
60	 * not all) media will generally share the same vocabulary, which can be
61	 * expressed through a core set of media traits.
62	 * </li>
63	 * <li>Traits allow for uniform, media-agnostic <i>client</i> classes.  For
64	 * example, if a client class is capable of rendering the "display object" trait,
65	 * then it's capable of rendering any and all media that host that trait. </li>
66	 * </ul>
67	 *
68	 * <p>It's important to be aware of the relationship between a media trait
69	 * and a media element.  Some media trait implementations will be tightly
70	 * coupled to a specific type of media element, while others will be
71	 * generic enough to work with any media element.  For example, an
72	 * implementation of a "play" trait that works with video is typically
73	 * going to be specific to one class of media elements, namely the class
74	 * that plays video, since the playback operations will be specific to the
75	 * underlying implementation of video (i.e. NetStream).  On the other hand,
76	 * an implementation of a "display object" trait might be able to work with
77	 * any media element, since DisplayObjectTrait will use the same underlying
78	 *  media implementation (DisplayObject) for any media element.</p>
79	 *
80	 *  @langversion 3.0
81	 *  @playerversion Flash 10
82	 *  @playerversion AIR 1.5
83	 *  @productversion OSMF 1.0
84	 */
85	public class MediaTraitBase extends EventDispatcher
86	{
87		/**
88		 * Constructor.
89		 *
90		 * @param traitType The MediaTraitType for this trait.  All possible values
91		 * are described on the MediaTraitType enumeration.
92		 *
93		 *  @langversion 3.0
94		 *  @playerversion Flash 10
95		 *  @playerversion AIR 1.5
96		 *  @productversion OSMF 1.0
97		 */
98		public function MediaTraitBase(traitType:String)
99		{
100			super();
101
102			_traitType = traitType;
103		}
104
105		/**
106		 * The MediaTraitType for this trait.
107		 *
108		 *  @langversion 3.0
109		 *  @playerversion Flash 10
110		 *  @playerversion AIR 1.5
111		 *  @productversion OSMF 1.0
112		 */
113		public function get traitType():String
114		{
115			return _traitType;
116		}
117
118		/**
119		 * Disposes of any resources used by this trait.  Called by the framework
120		 * whenever a trait is removed from a MediaElement.
121		 *
122		 * <p>Subclasses should override to do any disposal logic specific to their
123		 * implementation.</p>
124		 *
125		 *  @langversion 3.0
126		 *  @playerversion Flash 10
127		 *  @playerversion AIR 1.5
128		 *  @productversion OSMF 1.0
129		 */
130		public function dispose():void
131		{
132		}
133
134		private var _traitType:String;
135	}
136}