Specify minimum Android API level (+ add Animal Sniffer to verify this)

[Marcono1234]

Problem solved by the feature

The README only specifies that Java 7 is the minimum version for the latest Gson versions. However, for Android developers this information is not that helpful because Java 7 API was added in multiple different Android API levels. For example java.lang.ReflectiveOperationException added in Java 7 was only added for Android API level 19 (Android 4.4), see also #2310 (comment).

Feature description

• The README should explicitly state which Android API level is the minimum
• The build setup should verify that no newer Android APIs are used (respectively that desugaring is supported).
  This can be verified using Animal Sniffer, see:
  • Experiment with checking against *Android* Animal Sniffer signatures guava#4005
  • Android Scents for Maven
    (to be verified that these artifacts are safe; but appears they are also used by other projects, e.g. OkHttp (code))
    • https://sourceforge.net/projects/androidscents/
    • https://search.maven.org/search?q=g:net.sf.androidscents.signature
  • Animal Sniffer signatures, considering desugaring: https://github.com/open-toast/gummy-bears
    In that case would have to explicitly mention desugaring (using the latest Android build tools?) in the README

Alternatives / workarounds

none

[Marcono1234]

In 2018 usage of Android devices with API level < 19 was apparently already only at ~5% (in later years this statistic was not published on that webpage anymore). Now at the time of writing the API Version Distribution shown in Android Studio says API level < 21 is ~0,5%.
Google Play services are not updated anymore for versions < 19 either.

So maybe choosing either 19 or 21 as minimum API level might be reasonable (though note that I am not very familiar with Android development, so maybe my judgement is wrong here).
Here are some minimum API levels in other projects:

• Retrofit: 21
• OkHttp: 21
• Picasso: 21
• Protobuf: 14, respectively 19
• jsoup: 10
• JeroMQ: 28
• Λrrow: 21
• RxJava: 21
• Apollo Kotlin: 21
• Stripe Android SDK: 21

[Marcono1234]

Regarding those net.sf.androidscents.signature Animal Sniffer signature artifacts: Given that multiple of the projects listed above use them, I assume they are safe. The main problem is that this cannot be easily verified because those signature files use Java Serialization (see also mojohaus/animal-sniffer#252), so you cannot that easily verify their content and in the worst case they could allow a remote code execution attack during build.

[eamonnmcmanus]

Thanks for doing all that detailed research!

According to apilevels.com, API level 21 dates to 2014 and 99.3% of devices are at that level or greater. I think we could be pretty comfortable declaring that future Gson versions will only support that version. People who still need to support older devices can use an older version of Gson.

The Animal Sniffer serialization thing is a bit unsettling. It's probably OK, but if we really wanted to be careful I suppose we could have the check be a separate CI step that does nothing else. So in particular it couldn't modify the compiled binaries, which I would see as the main risk if the signature files were compromised.

[Marcono1234]

I have done a bit more testing; using the API level 18 signatures showed these unsupported usages:

• java.util.Objects.equals(Object, Object)
• java.util.Objects.requireNonNull(Object, String)
• java.lang.ReflectiveOperationException
• java.lang.AssertionError.<init>(String, Throwable)

Not sure if for some of them there is desugaring support. But I think either way supporting API level < 19 might be rather inconvenient.

For the API level 19 signatures no unsupported usage was found, so I assume we could also use that as minimum version at first, but at least personally I don't mind if we directly chose 21 as minimum API level instead (even if we might actually support API level 19).

It's probably OK, but if we really wanted to be careful I suppose we could have the check be a separate CI step that does nothing else. So in particular it couldn't modify the compiled binaries, which I would see as the main risk if the signature files were compromised.

That sounds like a good solution for now.