Android project improvements

[GoogleCodeExporter]

Currently we are splitting up the Android support into multiple "-android2" and 
"-android3" projects.  The problem is that this is a poor user experience for 
Android developers because:

1. It doesn't scale as we add more classes/methods targeted at difference API 
levels.

2. It's more jars to have to manage in an already large number of jars.

3. It doesn't give us more fine-grained ability to do things like having a 
class that generally supports level 8, but include a method that only works on 
level 15.

4. The names "android2" and "android3" are confusing.  Probably better to use 
API level instead, i.e. "android8" and "android11".

5. Currently we are compiling against the minimum API level, but actually it is 
better to compile against the latest API level.  The idea is that then we can 
have code that says for example if API level is lower than 11, use this 
backwards-compatible code, but if API level is 11 or higher, use this newer 
better code.

Now, apparently the (new) proper way to determine if your Android project works 
with a specific minimum API level is to use the new Android Lint tool.  See:

http://tools.android.com/tips/lint
http://www.simpligility.com/2012/01/android-lint-available-in-the-central-reposi
tory/
http://code.google.com/p/maven-android-plugin/issues/detail?id=224
http://android-developers.blogspot.com/2012/03/updated-sdk-tools-and-adt-revisio
n-17.html

So my proposal: just have a single "-android" project.  Use the new @TargetApi 
annotation from the annotations.jar from Android to specify the target Android 
API level for the Linter tool to check against.  Use JavaDoc to clear indicate 
the target API level for every method/class the same way we use @since for 
library version (exact format for specifying this to be determined).

Original issue reported on code.google.com by yan...@google.com on 22 Jun 2012 at 12:31

[GoogleCodeExporter]

Original comment by yan...@google.com on 26 Jul 2012 at 2:42

[GoogleCodeExporter]

A couple of things I figured out:

1. We should also change the Java package names to be based on 
"com.google.api.client.extensions.android" instead of 
"com.google.api.client.extensions.android2" or 
"com.google.api.client.extensions.android3".  That means deprecating the 
existing packages with a reference to switch to the new simpler package naming.

2. In case the developer chooses to build against an older version of the 
Android SDK, they would get Proguard warnings (i.e. which cause ProGaurd to 
fail to work) about use of Java code that is not found.  We should follow the 
example of the Android support library.  See the snippet from their 
proguard.cfg:

# The support library contains references to newer platform versions.
# Don't warn about those in case this app is linking against an older
# platform version.  We know about them, and they are safe.
-dontwarn android.support.**

3. We should literally include in the zip file bundle the proguard.cfg file to 
use that includes this snippet.  Maybe call it proguard-google-http-client.txt. 
 This follows the naming of the proguard-android.txt that is included with 
Android SDK.

Original comment by yan...@google.com on 1 Aug 2012 at 8:16

[GoogleCodeExporter]

One more thought:

4. We should add a runtime check for the Android SDK build with a friendly 
message.  Make a reusable method like AndroidUtils.checkMinimumSdkLevel(int 
minimumSdkLevel) that can be called safely.  Otherwise, developers will just 
see problems like ClassNotFoundError.

Original comment by yan...@google.com on 1 Aug 2012 at 8:55

[GoogleCodeExporter]

http://codereview.appspot.com/6447084/

Original comment by yan...@google.com on 2 Aug 2012 at 9:01

• Changed state: Started

[GoogleCodeExporter]

Original comment by yan...@google.com on 17 Aug 2012 at 11:03

• Changed state: Fixed