[generator] Add support for [ObsoletedOSPlatform] (#1026)

Context: dotnet/android#7234
Add support for a new option
`generator --lang-features=obsoleted-platform-attributes`.
When used, for an API that was obsoleted in API levels greater than
our .NET 7 minimum (API-21), we will generate .NET 7's new
`[ObsoletedOSPlatform]` attribute *instead of* `[Obsolete]`:
// New
[global::System.Runtime.Versioning.ObsoletedOSPlatform ("android22.0",
@"This class is obsoleted in this android platform")]
public partial class CookieSpecParamBean : Org.Apache.Http.Params.HttpAbstractParamBean {
}
// Previous
[global::System.Obsolete (@"This class is obsoleted in this android platform")]
public partial class CookieSpecParamBean : Org.Apache.Http.Params.HttpAbstractParamBean {
}
This is useful in a .NET 7+ context because we always *compile*
against the "latest" `Mono.Android`, even if you are *targeting* an
earlier version.
For example, the use of `[Obsolete]` means that using
`CookieSpecParamBean` would always result in a CS0618 obsolete usage
warning, even when building with `$(SupportedOSPlatformVersion)`=21.
(`CookieSpecParamBean` was obsoleted in API-22.)

Author: jpobst

src/utils/XmlExtensions.cs

@@ -20,5 +20,18 @@ public static string XGetAttribute (this XPathNavigator nav, string name, string
 varattr=nav.GetAttribute(name,ns);
 returnattr!=null?attr.Trim():null;
 }
+
+publicstaticint?XGetAttributeAsIntOrNull(thisXElementelement,stringname)
+{
+varattr=element.Attribute(name);
+
+if(attr?.Valueisnull)
+returnnull;
+
+if(int.TryParse(attr.Value,outvarval))
+returnval;
+
+returnnull;
+}
 }
 }

tests/generator-Tests/Unit-Tests/CodeGeneratorTests.cs

@@ -531,6 +531,86 @@ public void ObsoleteBoundMethodAbstractDeclaration ()
 Assert.True(writer.ToString().Contains("[global::System.Obsolete (@\"This is so old!\")]"),writer.ToString());
 }
 
+[Test]
+publicvoidObsoletedOSPlatformAttributeSupport()
+{
+varxml=@"<api>
+ <package name='java.lang' jni-name='java/lang'>
+ <class abstract='false' deprecated='not deprecated' final='false' name='Object' static='false' visibility='public' jni-signature='Ljava/lang/Object;' />
+ </package>
+ <package name='com.xamarin.android' jni-name='com/xamarin/android'>
+ <class abstract='false' deprecated='This is a class deprecated since 25!' extends='java.lang.Object' extends-generic-aware='java.lang.Object' jni-extends='Ljava/lang/Object;' final='false' name='MyClass' static='false' visibility='public' jni-signature='Lcom/xamarin/android/MyClass;' deprecated-since='25'>
+ <field deprecated='This is a field deprecated since 25!' final='true' name='ACCEPT_HANDOVER' jni-signature='Ljava/lang/String;' static='true' transient='false' type='java.lang.String' type-generic-aware='java.lang.String' value='&quot;android.permission.ACCEPT_HANDOVER&quot;' visibility='public' volatile='false' deprecated-since='25'></field>
+ <constructor deprecated='This is a constructor deprecated since 25!' final='false' name='MyClass' jni-signature='()V' bridge='false' static='false' type='com.xamarin.android.MyClass' synthetic='false' visibility='public' deprecated-since='25'></constructor>
+ <method abstract='true' deprecated='This is a method deprecated since 25!' final='false' name='countAffectedRows' jni-signature='()I' bridge='false' native='false' return='int' jni-return='I' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='25'></method>
+ <method abstract='false' deprecated='This is a property getter deprecated since 25!' final='false' name='getCount' jni-signature='()I' bridge='false' native='false' return='int' jni-return='I' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='25'></method>
+ <method abstract='false' deprecated='This is a property setter deprecated since 25!' final='false' name='setCount' jni-signature='(I)V' bridge='false' native='false' return='void' jni-return='V' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='25'>
+ <parameter name='count' type='int' jni-type='I'></parameter>
+ </method>
+ </class>
+ </package>
+ </api>";
+
+options.UseObsoletedOSPlatformAttributes=true;
+
+vargens=ParseApiDefinition(xml);
+variface=gens.Single(g =>g.Name=="MyClass");
+
+generator.Context.ContextTypes.Push(iface);
+generator.WriteType(iface,string.Empty,newGenerationInfo("","","MyAssembly"));
+generator.Context.ContextTypes.Pop();
+
+// Ensure [ObsoletedOSPlatform] was written
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\", @\"This is a class deprecated since 25!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\", @\"This is a field deprecated since 25!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\", @\"This is a constructor deprecated since 25!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\", @\"This is a method deprecated since 25!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\", @\"This is a property getter deprecated since 25! This is a property setter deprecated since 25!\")]"),writer.ToString());
+}
+
+[Test]
+publicvoidObsoletedOSPlatformAttributeUnneededSupport()
+{
+varxml=@"<api>
+ <package name='java.lang' jni-name='java/lang'>
+ <class abstract='false' deprecated='not deprecated' final='false' name='Object' static='false' visibility='public' jni-signature='Ljava/lang/Object;' />
+ </package>
+ <package name='com.xamarin.android' jni-name='com/xamarin/android'>
+ <class abstract='false' deprecated='This is a class deprecated since 19!' extends='java.lang.Object' extends-generic-aware='java.lang.Object' jni-extends='Ljava/lang/Object;' final='false' name='MyClass' static='false' visibility='public' jni-signature='Lcom/xamarin/android/MyClass;' deprecated-since='19'>
+ <field deprecated='This is a field deprecated since 0!' final='true' name='ACCEPT_HANDOVER' jni-signature='Ljava/lang/String;' static='true' transient='false' type='java.lang.String' type-generic-aware='java.lang.String' value='&quot;android.permission.ACCEPT_HANDOVER&quot;' visibility='public' volatile='false' deprecated-since='0'></field>
+ <constructor deprecated='This is a constructor deprecated since empty string!' final='false' name='MyClass' jni-signature='()V' bridge='false' static='false' type='com.xamarin.android.MyClass' synthetic='false' visibility='public' deprecated-since=''></constructor>
+ <method abstract='true' deprecated='deprecated' final='false' name='countAffectedRows' jni-signature='()I' bridge='false' native='false' return='int' jni-return='I' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='25'></method>
+ <method abstract='true' deprecated='This method has an invalid deprecated-since!' final='false' name='countAffectedRows2' jni-signature='()I' bridge='false' native='false' return='int' jni-return='I' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='foo'></method>
+ <method abstract='false' deprecated='deprecated' final='false' name='getCount' jni-signature='()I' bridge='false' native='false' return='int' jni-return='I' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='22'></method>
+ <method abstract='false' deprecated='deprecated' final='false' name='setCount' jni-signature='(I)V' bridge='false' native='false' return='void' jni-return='V' static='false' synchronized='false' synthetic='false' visibility='public' deprecated-since='22'>
+ <parameter name='count' type='int' jni-type='I'></parameter>
+ </method>
+ </class>
+ </package>
+ </api>";
+
+options.UseObsoletedOSPlatformAttributes=true;
+
+vargens=ParseApiDefinition(xml);
+variface=gens.Single(g =>g.Name=="MyClass");
+
+generator.Context.ContextTypes.Push(iface);
+generator.WriteType(iface,string.Empty,newGenerationInfo("","","MyAssembly"));
+generator.Context.ContextTypes.Pop();
+
+// These should use [Obsolete] because they have always been obsolete in all currently supported versions (21+)
+Assert.True(writer.ToString().Contains("[global::System.Obsolete (@\"This is a class deprecated since 19!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Obsolete (@\"This is a field deprecated since 0!\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Obsolete (@\"This is a constructor deprecated since empty string!\")]"),writer.ToString());
+
+// This should not have a message because the default "deprecated" message isn't useful
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android25.0\")]"),writer.ToString());
+Assert.True(writer.ToString().Contains("[global::System.Runtime.Versioning.ObsoletedOSPlatform (\"android22.0\")]"),writer.ToString());
+
+// This should use [Obsolete] because the 'deprecated-since' attribute could not be parsed
+Assert.True(writer.ToString().Contains("[global::System.Obsolete (@\"This method has an invalid deprecated-since!\")]"),writer.ToString());
+}
+
 [Test]
 [NonParallelizable]// We are setting a static property on Report
 publicvoidWarnIfTypeNameMatchesNamespace()

tools/generator/CodeGenerationOptions.cs

@@ -66,6 +66,7 @@ public SymbolTable SymbolTable {
 publicboolSupportNestedInterfaceTypes{get;set;}
 publicboolSupportNullableReferenceTypes{get;set;}
 publicboolUseShallowReferencedTypes{get;set;}
+publicboolUseObsoletedOSPlatformAttributes{get;set;}
 publicboolRemoveConstSugar=>BuildingCoreAssembly;
 
 bool?buildingCoreAssembly;

tools/generator/CodeGenerator.cs

@@ -83,6 +83,7 @@ static void Run (CodeGeneratorOptions options, DirectoryAssemblyResolver resolve
 SupportDefaultInterfaceMethods=options.SupportDefaultInterfaceMethods,
 SupportNestedInterfaceTypes=options.SupportNestedInterfaceTypes,
 SupportNullableReferenceTypes=options.SupportNullableReferenceTypes,
+UseObsoletedOSPlatformAttributes=options.UseObsoletedOSPlatformAttributes,
 };
 varresolverCache=newTypeDefinitionCache();
 

tools/generator/CodeGeneratorOptions.cs

@@ -53,6 +53,7 @@ public CodeGeneratorOptions ()
 publicboolSupportNestedInterfaceTypes{get;set;}
 publicboolSupportNullableReferenceTypes{get;set;}
 publicboolUseLegacyJavaResolver{get;set;}
+publicboolUseObsoletedOSPlatformAttributes{get;set;}
 
 publicXmldocStyleXmldocStyle{get;set;}=XmldocStyle.IntelliSense;
 
@@ -102,12 +103,13 @@ public static CodeGeneratorOptions Parse (string[] args)
 "SDK Platform {VERSION}/API level.",
  v =>opts.ApiLevel=v},
 {"lang-features=",
-"For internal use. (Flags: interface-constants,default-interface-methods,nullable-reference-types)",
+"For internal use. (Flags: interface-constants,default-interface-methods,nested-interface-types,nullable-reference-types,obsoleted-platform-attributes)",
  v =>{
 opts.SupportInterfaceConstants=v?.Contains("interface-constants")==true;
 opts.SupportDefaultInterfaceMethods=v?.Contains("default-interface-methods")==true;
 opts.SupportNestedInterfaceTypes=v?.Contains("nested-interface-types")==true;
 opts.SupportNullableReferenceTypes=v?.Contains("nullable-reference-types")==true;
+opts.UseObsoletedOSPlatformAttributes=v?.Contains("obsoleted-platform-attributes")==true;
 }},
 {"preserve-enums",
 "For internal use.",

tools/generator/Java.Interop.Tools.Generator.Importers/XmlApiImporter.cs

@@ -155,6 +155,7 @@ public static Ctor CreateCtor (GenBase declaringType, XElement elem, CodeGenerat
 ApiAvailableSince=declaringType.ApiAvailableSince,
 CustomAttributes=elem.XGetAttribute("customAttributes"),
 Deprecated=elem.Deprecated(),
+DeprecatedSince=elem.XGetAttributeAsIntOrNull("deprecated-since"),
 GenericArguments=elem.GenericArguments(),
 Name=elem.XGetAttribute("name"),
 Visibility=elem.Visibility()
@@ -200,6 +201,7 @@ public static Field CreateField (GenBase declaringType, XElement elem, CodeGener
 varfield=newField{
 ApiAvailableSince=declaringType.ApiAvailableSince,
 DeprecatedComment=elem.XGetAttribute("deprecated"),
+DeprecatedSince=elem.XGetAttributeAsIntOrNull("deprecated-since"),
 IsAcw=true,
 IsDeprecated=elem.XGetAttribute("deprecated")!="not deprecated",
 IsDeprecatedError=elem.XGetAttribute("deprecated-error")=="true",
@@ -237,6 +239,7 @@ public static Field CreateField (GenBase declaringType, XElement elem, CodeGener
 publicstaticGenBaseSupportCreateGenBaseSupport(XElementpkg,XElementelem,CodeGenerationOptionsopt,boolisInterface)
 {
 varsupport=newGenBaseSupport{
+DeprecatedSince=elem.XGetAttributeAsIntOrNull("deprecated-since"),
 IsAcw=true,
 IsDeprecated=elem.XGetAttribute("deprecated")!="not deprecated",
 IsGeneratable=true,
@@ -348,6 +351,7 @@ public static Method CreateMethod (GenBase declaringType, XElement elem, CodeGen
 ArgsType=elem.Attribute("argsType")?.Value,
 CustomAttributes=elem.XGetAttribute("customAttributes"),
 Deprecated=elem.Deprecated(),
+DeprecatedSince=elem.XGetAttributeAsIntOrNull("deprecated-since"),
 ExplicitInterface=elem.XGetAttribute("explicitInterface"),
 EventName=elem.Attribute("eventName")?.Value,
 GenerateAsyncWrapper=elem.Attribute("generateAsyncWrapper")!=null,

tools/generator/Java.Interop.Tools.Generator.ObjectModel/Field.cs

@@ -9,6 +9,7 @@ public class Field : ApiVersionsSupport.IApiAvailability, ISourceLineInfo
 publicstringAnnotation{get;set;}
 publicintApiAvailableSince{get;set;}
 publicstringDeprecatedComment{get;set;}
+publicint?DeprecatedSince{get;set;}
 publicboolIsAcw{get;set;}
 publicboolIsDeprecated{get;set;}
 publicboolIsDeprecatedError{get;set;}

tools/generator/Java.Interop.Tools.Generator.ObjectModel/GenBase.cs

@@ -251,6 +251,8 @@ public bool ContainsProperty (string name, bool check_ifaces, bool check_base_if
 
 publicstringDeprecatedComment=>support.DeprecatedComment;
 
+publicint?DeprecatedSince=>support.DeprecatedSince;
+
 IEnumerable<GenBase>Descendants(IList<GenBase>gens)
 {
 foreach(vardirectDescendantsingens.Where(x =>x.BaseGen==this)){

tools/generator/Java.Interop.Tools.Generator.ObjectModel/GenBaseSupport.cs

@@ -7,6 +7,7 @@ public class GenBaseSupport
 publicboolIsAcw{get;set;}
 publicboolIsDeprecated{get;set;}
 publicstringDeprecatedComment{get;set;}
+publicint?DeprecatedSince{get;set;}
 publicboolIsGeneratable{get;set;}
 publicboolIsGeneric{get;set;}
 publicboolIsObfuscated{get;set;}

tools/generator/Java.Interop.Tools.Generator.ObjectModel/MethodBase.cs

@@ -18,6 +18,7 @@ protected MethodBase (GenBase declaringType)
 publicstringAssemblyName{get;set;}
 publicGenBaseDeclaringType{get;}
 publicstringDeprecated{get;set;}
+publicint?DeprecatedSince{get;set;}
 publicGenericParameterDefinitionListGenericArguments{get;set;}
 publicboolIsAcw{get;set;}
 publicboolIsValid{get;privateset;}