Writing backward compatible Android code

Question

I am writing an application that uses some functions and classes that are available only at the last API level - 16, but I want it to run without errors on devices with API level 15.

Let me use a few examples. New class: Android.widget.Advanceable and new / renamed method: View.setBackground() :

I can do something like this:

 Advanceable myAdvanceable = ...; if (android.os.Build.VERSION.SDK_INT >= 16) { myView.setBackground(...); myAdvanceable.advance(); } else { myView.setBackgroundDrawable(...); // The old function name. // Don't bother advancing advanceables. } 

And if I installed minSdk from 15, but the goal of building is 16 (i.e. in Project Properties → Android), it will actually compile without errors. At least for a while. Eclipse is a bit stochastic regarding errors and sometimes says: "setBackground () is only available at API level> = 16" or similar, but if I just clear the project, then these errors will magically disappear.

So my question is: am I allowed to do this? Will the code crash if I run it on a device of level 15 API? Will it just crash if it really gets to code 16? Why doesn't Eclipse stop me from creating it?

Change 1

Thanks for the answers, I think the question really should be: why I won’t warn me about using the new APIs?

I have this in my manifest, and I use API level 16 functions, but it still doesn't warn me:

 <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="16"/> 

Also, I'm still not sure when entire classes are new to the API level, like Advanceable . In particular, if I use them as member variables.

Edit 2

The answer was “Eclipse buggy like hell,” but Nico’s answer also helped a lot.

Answer 1

Inline Api errors are new to ADT, Eclipse launches Lint (and I think something else is possible) to parse your code and put these errors / warnings in a line. The same goes for the xml layout when you have warnings or hints about optimization or best practices. You can use annotations to suppress these errors in a class or in a specific method.

@TargetApi (16)
@SuppressLint ("NewApi")

There is a problem in the code example given here, in addition to checking the API level, you have an Advanceable instance in the code that will not work in API <16, therefore API level checking is only useful when calling new methods, but you cannot reference new API classes outside IF block.

One approach that I found acceptable is to create an abstract class and two implementations, and then you can use the factory class with static methods to create the correct implementation.

For example, to create a view that uses some of the new API classes and methods inside, you need to:

1 - Create an abstract class:

 public abstract class CustomView { public abstract void doSomething(); } 

• Common implementation compatible with all APIs
• Define an abstract method here to share the implementation.

2 - Inherited implementation

 public class CustomLegacyView extends CustomView { public void doSomething(){ //implement api < 16 } } 

• implement an abstract method for API <16

3 - implementation of API 16

 @TargetApi(16) public class CustomL16View extends CustomView { Advanceable myAdvanceable; public void doSomething(){ //implement api >= 16 } } 

• Use @TargetApi annotation (16)
• implement an abstract method for API> = 16
• Here you can refer to level 16 classes (but not in CustomView).

4 - factory class

 public class ViewFactory { public static CustomView getCustomView(Context context) { if (android.os.Build.VERSION.SDK_INT >= Build.VERSION_CODES.JELLY_BEAN) { return new CustomL16View(context); }else{ return new CustomLegacyView(context); } } } 

Answer 2

It is common practice to use a newer build target and ensure that the new API is called under the right circumstances. Google even added the @TargetApi() annotation with ADT 17 to indicate local overrides for conditionally loaded code.

See the Lint API check for more details.

Answer 3

1. You have the Target Api and Minimum SDK attributes to determine which device you are using , and this will be the smallest version of Api it will run on.

2. Target Api will be the one on which the application works with full functions , while the Minimum SDK will make the application run on it using <some compromises, since there may be chances that a lower version of the API does not have functions that are in higher versions .