0 Replies Latest reply on Jul 13, 2009 9:45 AM by Jeff Dyer

    [svn:fx-trunk] 8528: This change adds support for the new API versioning solution ( see design note below).

    Jeff Dyer Level 1

      Revision: 8528

      Author:   jodyer@adobe.com

      Date:     2009-07-13 09:45:02 -0700 (Mon, 13 Jul 2009)


      Log Message:


      This change adds support for the new API versioning solution (see design note below). There are two signficant changes: 1/ActionBlockEmitter translates version (legacy "Version" and new "API" named) metadata into version markers on the annotated traits' names; and 2/AbcParser strips traits that are introduced in a larger version than the version of the code being compiled. Some helper support has been added to Context. Information about the current versions is recorded in the Flash Runtime provided APIVersions.java.


      QE: Yes. (Chris Peyer has the test plan)

      Doc: Maybe. Users and tools which want to compile code as though it was an earlier version need to know about the -api flag

      Checkintests: PASS (asc-tests PASS too, except where they were already broken)

      Reviewer: Peter D.

      Bugs: ASC-3771 - ASC needs to support versioning of Flash Runtime APIs




      API Versioning in Argo/Athena

           Jeff Dyer





           Logically, a version can be thought of as a set of bindings. There is a partial order of versions such that every version is a subset of itself and zero or more other versions. A version is said to be compatible with every other version of which it is a superset including itself.


           In AIR 2.0 (Athena, which includes Argo), the partial order is such


           FP_9_0    <   AIR_1_0

           FP_9_0    <   FP_10_0

           AIR_1_0   <   AIR_1_5

           FP_10_0   <   FP_10_1

           FP_10_0   <   AIR_1_5

           AIR_1_5   <   AIR_1_5_1

           AIR_!_5_1 <   AIR_2_0

           FP_10_1   <   AIR_2_0


           From these relations we can see, for example, that a binding introduced in FP9 will be in every other version; a binding introduced in AIR_1_0 is not in FP_9_0 but is in AIR_1_5; and a bidning introduced in AIR_2_0 is only in AIR_2_0.


           Library code definitions are of the version specified by the version metadata or by default of the smallest version (FP_9_0). Library code references are always of the largest version (in this case AIR_2_0). This means that regardless of the version it was introduced library code references can ?\226?\128?\156see?\226?\128?\157 all bindings.


           Client code is of the version it was built with as determined by the SWF version or some other application specific information.


           Only public names in the Flash runtime built-ins (avmglue and avmcore) may be versioned. Versioning names in a private, protected, internal, interface, or user defined namespace is prohibited. Note: Private names are not visible outside of the builtin code and so versioning has no effect on them; other names might be visible outside of the builtin code but are not required by targeted use cases to be versioned and therefore doing so unnecessarily complicates the implementation.


           We further limit the set of names being versioned to those whose namespaces have one of the flash runtime package names or the empty string.




           API Version Metadata


           The metadata syntax for marking a builtin API with a version is this:


           VersionMetaData := ?\226?\128?\152[?\226?\128?\152 ?\226?\128?\152API?\226?\128?\153 ?\226?\128?\152(?\226?\128?\152 VersionList ?\226?\128?\152)?\226?\128?\153 ?\226?\128?\152]?\226?\128?\153

           VersionList     := VersionList ?\226?\128?\152,?\226?\128?\153 Version

           Version         := Integer (between 660 and 666, in Argo/Athena)


           ASC configuration variables are defined to alias these integers:


           FP_9_0   660

           AIR_1_0 661                                                                               

      FP_10_0 662                                                                               

      AIR_1_5 663                                                                               

      AIR_1_5_1       664                                                                               

      FP_10_1 665                                                                               

      AIR_2_0 666


           These values are derived from an enum definition in splayer.h


           enum APIVersion {

                   APIVersionNotYetKnown = 659,