Add AndroidVersions

Commit [xamarin-android/8e7d37bb][xa8e] contains a sign of
duplication: in order to use a `Mono.Android.dll` binding assembly,
not only do we need to *build* the binding assembly, but we *also*
need to update `Xamarin.Android.Build.Utilities.dll`/etc. to "know"
about the new binding version (to map API level to
`$(TargetFrameworkVersion)`).

[xa8e]: dotnet/android@8e7d37bb

Even "better" (worse), if the new API level is a *preview*, there is
no *consistent* API level. For example, with API-O, `android.jar`
isn't at:

	$(AndroidSdkDirectory)\platforms\android-@API_LEVEL@\android.jar

where `@API_LEVEL@` is 26 (because various codepaths require that the
"api level" be an integer). Instead, it's installed at:

	$(AndroidSdkDirectory)\platforms\android-O\android.jar

where `O` is the "id" of the preview API level.

This "id" is "leaky", in turn requiring that
`Xamarin.Android.Build.Tasks.dll` *also* be updated to deal with the
mappings.

Even "better" (worse), if we *forget* to cross all our our 't's and
dot all of our 'i's, we'll have a binding assembly which can't be
used. (Which is why we needed [xamarin-android/8e7d37bb][xe8e];
without it, the API-O binding can't be used!)

This is all obviously madness. ;-)

[xamarin-android/8942eca0][xa89] contains a fix:

[xa89]: dotnet/android@8942eca

 1. The build system is updated to create a new `AndroidApiInfo.xml`
    file within the `$(TargetFrameworkVersion)` directory.
    This contains all the information needed to map Android API
    levels to Ids and Android OS versions and
    `$(TargetFrameworkVersion)` values:

    ```xml
    <AndroidApiInfo>
      <Id>10</Id>
      <Level>10</Level>
      <Name>Gingerbread</Name>
      <Version>v2.3</Version>
    </AndroidApiInfo>
    ```

 2. Add a new `Xamarin.Android.Build.Utilities.AndroidVersions` type
    was added which parses the `AndroidApiInfo.xml` files.

The advantage to all this is that we can support new API level
bindings by just building a new `Mono.Android.dll` and placing an
`AndroidApiInfo.xml` into the appropriate location (next to
`Mono.Android.dll`). No further code changes would be required.

This is all well and good...but it's not entirely useful if *only*
Xamarin.Android makes use of this functionality. The IDEs also need
to be updated to make use of these files.

Copy over `Xamarin.Android.Build.Utilities.AndroidVersions` into the
**xamarin-android-tools** repo as
`Xamarin.Android.Tools.AndroidVersions`, so that we have a path for
eventual IDE support of the new paradigm.

Author: jonpryor

src/Xamarin.Android.Tools.AndroidSdk/AndroidSdk.cs

@@ -20,13 +20,7 @@ public static void Refresh (string androidSdkPath = null, string androidNdkPath
 				sdk.Initialize (androidSdkPath ?? sdk.PreferedAndroidSdkPath, androidNdkPath ?? sdk.PreferedAndroidNdkPath,
 					javaSdkPath ?? sdk.PreferedJavaSdkPath);
 				if (IsInstalled) {
-					var levels = GetInstalledPlatformVersions ().Select (l => l.ApiLevel.ToString ()).ToArray ();
-					string levelList;
-					if (levels == null || levels.Length == 0)
-						levelList = "(none)";
-					else
-						levelList = string.Join (", ", levels);
-					AndroidLogger.LogInfo (null, "Found Android SDK. API levels: {0}", levelList);
+					AndroidLogger.LogInfo (null, "Found Android SDK.");
 				} else {
 					AndroidLogger.LogInfo (null, "Did not find Android SDK");
 				}
@@ -80,13 +74,6 @@ static Version TryParseVersion (string v)
 			return null;
 		}
 
-		// it was useful when android-21 was android-L, or android-23 was android-MNC.
-		// We will use this when similar preview release is out.
-		static string ToApiName (int apiLevel)
-		{
-			return apiLevel.ToString ();
-		}
-
 		static string ValidatePath (string path)
 		{
 			if (String.IsNullOrEmpty (path))
@@ -96,30 +83,33 @@ static string ValidatePath (string path)
 
 		public static string GetPlatformDirectory (int apiLevel)
 		{
-			return Path.Combine (AndroidSdkPath, "platforms", "android-" + ToApiName (apiLevel));
+			return GetPlatformDirectoryFromId (apiLevel.ToString ());
 		}
 
-		public static string GetPlatformDirectory (string osVersion)
+		public static string GetPlatformDirectoryFromId (string id)
 		{
-			var level = AndroidVersion.TryOSVersionToApiLevel (osVersion);
-			if (level == 0)
-				return null;
-			return GetPlatformDirectory (level);
+			return Path.Combine (AndroidSdkPath, "platforms", "android-" + id);
 		}
 
-		public static bool IsPlatformInstalled (int apiLevel)
+		public static string TryGetPlatformDirectoryFromApiLevel (string apiLevel, AndroidVersions versions)
 		{
-			return apiLevel != 0 && Directory.Exists (GetPlatformDirectory (apiLevel));
+			var id  = versions.GetIdFromApiLevel (apiLevel);
+			var dir = GetPlatformDirectoryFromId (id);
+
+			if (Directory.Exists (dir))
+				return dir;
+
+			var level   = versions.GetApiLevelFromId (id);
+			dir         = level.HasValue ? GetPlatformDirectory (level.Value) : null;
+			if (dir != null && Directory.Exists (dir))
+				return dir;
+
+			return null;
 		}
 
-		public static IEnumerable<AndroidVersion> GetInstalledPlatformVersions ()
+		public static bool IsPlatformInstalled (int apiLevel)
 		{
-			var knownAndInstalledSdkLevels = AndroidVersion.KnownVersions.Where (v => IsPlatformInstalled (v.ApiLevel));
-
-			return knownAndInstalledSdkLevels.Where (version => {
-				var apiLevel = MonoDroidSdk.GetApiLevelForFrameworkVersion (version.OSVersion);
-				return MonoDroidSdk.IsSupportedFrameworkLevel (apiLevel);
-			});
+			return apiLevel != 0 && Directory.Exists (GetPlatformDirectory (apiLevel));
 		}
 
 		public static bool IsInstalled {

src/Xamarin.Android.Tools.AndroidSdk/AndroidVersion.cs

@@ -1,108 +1,84 @@
 using System;
+using System.IO;
+using System.Xml.Linq;
 
 namespace Xamarin.Android.Tools
 {
 	public class AndroidVersion
 	{
-		public static readonly int MaxApiLevel = 24;
+		// Android API Level. *Usually* corresponds to $(AndroidSdkPath)/platforms/android-$(ApiLevel)/android.jar
+		public  int             ApiLevel                { get; private set; }
 
-		public AndroidVersion (int apilevel, string osVersion)
-		{
-			this.ApiLevel = apilevel;
-			this.OSVersion = osVersion;
-		}
+		// Android API Level ID. == ApiLevel on stable versions, will be e.g. `N` for previews: $(AndroidSdkPath)/platforms/android-N/android.jar
+		public  string          Id                      { get; private set; }
 
-		AndroidVersion (int apilevel, string osVersion, string codeName, Version version)
-		{
-			this.ApiLevel = apilevel;
-			// TODO: remove osVersion from parameter list and generate from version
-			this.OSVersion = osVersion;
-			this.CodeName = codeName;
-			this.Version = version;
-		}
+		// Name of an Android release, e.g. "Oreo"
+		public  string          CodeName                { get; private set; }
 
-		public int ApiLevel { get; private set; }
-		public string OSVersion { get; private set; }
-		public string CodeName { get; private set; }
-		public Version Version { get; private set; }
+		// Android version number, e.g. 8.0
+		public string           OSVersion               { get; private set; }
 
-		public static int OSVersionToApiLevel (string osVersion)
-		{
-			int ret = TryOSVersionToApiLevel (osVersion);
-			if (ret == 0)
-				throw new ArgumentOutOfRangeException ("OS version not recognized: " + osVersion);
-			return ret;
-		}
+		// Xamarin.Android $(TargetFrameworkVersion) value, e.g. 8.0
+		public Version          TargetFrameworkVersion  { get; private set; }
 
-		public static int TryOSVersionToApiLevel (string frameworkVersion)
+		// TargetFrameworkVersion *with* a leading `v`, e.g. "v8.0"
+		public string           FrameworkVersion        { get; private set; }
+
+		// Is this API level stable? Should be False for non-numeric Id values.
+		public bool             Stable                  { get; private set; }
+
+		// Alternate Ids for a given API level. Allows for historical mapping, e.g. API-11 has alternate ID 'H'.
+		internal    string[]    AlternateIds            { get; set; }
+
+		public AndroidVersion (int apiLevel, string osVersion, string codeName = null, string id = null, bool stable = true)
 		{
-			// Use MonoDroidSdk.GetApiLevelForFrameworkVersion because that will translate XA versions >= 5.xx to the correct api level
-			var apiLevelText = MonoDroidSdk.GetApiLevelForFrameworkVersion (frameworkVersion);
-			int apiLevel;
-			int.TryParse (apiLevelText, out apiLevel);
-			return apiLevel;
+			if (osVersion == null)
+				throw new ArgumentNullException (nameof (osVersion));
+
+			ApiLevel                = apiLevel;
+			Id                      = id ?? ApiLevel.ToString ();
+			CodeName                = codeName;
+			OSVersion               = osVersion;
+			TargetFrameworkVersion  = Version.Parse (osVersion);
+			FrameworkVersion        = "v" + osVersion;
+			Stable                  = stable;
 		}
 
-		public static string ApiLevelToOSVersion (int apiLevel)
+		public override string ToString ()
 		{
-			string ret = TryApiLevelToOSVersion (apiLevel);
-			if (ret == null)
-				throw new ArgumentOutOfRangeException ("API level not recognized: " + apiLevel);
-			return ret;
+			return $"(AndroidVersion: ApiLevel={ApiLevel} Id={Id} OSVersion={OSVersion} CodeName='{CodeName}' TargetFrameworkVersion={TargetFrameworkVersion} Stable={Stable})";
 		}
 
-		public static string TryApiLevelToOSVersion (int apiLevel)
+		public static AndroidVersion Load (Stream stream)
 		{
-			var osVersion = MonoDroidSdk.GetFrameworkVersionForApiLevel (apiLevel.ToString ());
-			if (!string.IsNullOrEmpty (osVersion))
-				return osVersion.TrimStart ('v');
-			return null;
+			var doc = XDocument.Load (stream);
+			return Load (doc);
 		}
 
-		public static string TryOSVersionToCodeName (string frameworkVersion)
+		public static AndroidVersion Load (string uri)
 		{
-			// match on API level, the framework version might not match what we have here (>= XA 5.x uses a different version scheme)
-			var apiLevel = TryOSVersionToApiLevel (frameworkVersion);
-
-			foreach (AndroidVersion version in KnownVersions)
-				if (version.ApiLevel == apiLevel)
-					return version.CodeName;
-			return null;
+			var doc = XDocument.Load (uri);
+			return Load (doc);
 		}
 
-		public static string TryFrameworkVersionToOSVersion (string frameworkVersion)
+		// Example:
+		// <AndroidApiInfo>
+		//   <Id>26</Id>
+		//   <Level>26</Level>
+		//   <Name>Oreo</Name>
+		//   <Version>v8.0</Version>
+		//   <Stable>True</Stable>
+		// </AndroidApiInfo>
+		static AndroidVersion Load (XDocument doc)
 		{
-			// match on API level, the framework version might not match what we have here (>= XA 5.x uses a different version scheme)
-			var apiLevel = TryOSVersionToApiLevel (frameworkVersion);
+			var id      = (string) doc.Root.Element ("Id");
+			var level   = (int) doc.Root.Element ("Level");
+			var name    = (string) doc.Root.Element ("Name");
+			var version = (string) doc.Root.Element ("Version");
+			var stable  = (bool) doc.Root.Element ("Stable");
 
-			foreach (AndroidVersion version in KnownVersions)
-				if (version.ApiLevel == apiLevel)
-					return version.OSVersion;
-			return null;
+			return new AndroidVersion (level, version.TrimStart ('v'), name, id, stable);
 		}
-
-		public static AndroidVersion[] KnownVersions = new[] {
-			new AndroidVersion (4,  "1.6",   "Donut",                   new Version (1, 6)),
-			new AndroidVersion (5,  "2.0",   "Eclair",                  new Version (2, 0)),
-			new AndroidVersion (6,  "2.0.1", "Eclair",                  new Version (2, 0, 1)),
-			new AndroidVersion (7,  "2.1",   "Eclair",                  new Version (2, 1)),
-			new AndroidVersion (8,  "2.2",   "Froyo",                   new Version (2, 2)),
-			new AndroidVersion (10, "2.3",   "Gingerbread",             new Version (2, 3)),
-			new AndroidVersion (11, "3.0",   "Honeycomb",               new Version (3, 0)),
-			new AndroidVersion (12, "3.1",   "Honeycomb",               new Version (3, 1)),
-			new AndroidVersion (13, "3.2",   "Honeycomb",               new Version (3, 2)),
-			new AndroidVersion (14, "4.0",   "Ice Cream Sandwich",      new Version (4, 0)),
-			new AndroidVersion (15, "4.0.3", "Ice Cream Sandwich",      new Version (4, 0, 3)),
-			new AndroidVersion (16, "4.1",   "Jelly Bean",              new Version (4, 1)),
-			new AndroidVersion (17, "4.2",   "Jelly Bean",              new Version (4, 2)),
-			new AndroidVersion (18, "4.3",   "Jelly Bean",              new Version (4, 3)),
-			new AndroidVersion (19, "4.4",   "Kit Kat",                 new Version (4, 4)),
-			new AndroidVersion (20, "4.4.87", "Kit Kat + Wear support", new Version (4, 4, 87)),
-			new AndroidVersion (21, "5.0",   "Lollipop",                new Version (5, 0)),
-			new AndroidVersion (22, "5.1",   "Lollipop",                new Version (5, 1)),
-			new AndroidVersion (23, "6.0",   "Marshmallow",             new Version (6, 0)),
-			new AndroidVersion (24, "7.0",   "Nougat",                  new Version (7, 0)),
-		};
 	}
 }