NOTE For all library APIs that wrap or provide parity with platform APIs, we
prefer to follow modern API guidelines; however, developers may choose to
prioritize parity with the platform APIs over adherence to modern guidelines.
For example, if the platform API being wrapped has incorrect Executor and
Callback ordering according to the API Guidelines, the corresponding library
API should re-order the arguments.
Static shims (ex. ViewCompat) {#static-shim}
When to use?
- Platform class exists at module's
minSdkVersion - Compatibility implementation does not need to store additional metadata
- Class should be added to the
androidx.core:corelibrary - Class name must be
<PlatformClass>Compat - Package name must be
androidx.<feature>.<platform.package> - Superclass must be
Object
- Class must be non-instantiable, i.e. constructor is private no-op
- Static fields and static methods must match match signatures with
<PlatformClass>- Static fields that can be inlined, ex. integer constants, must not be shimmed
- Public method names must match platform method names
- Public methods must be static and take
<PlatformClass>as first parameter (except in the case of static methods on the platform class, as shown below) - Implementation may delegate to
<PlatformClass>methods when available
The following sample provides static helper methods for the platform class
android.os.Process.
package androidx.core.os;
/**
* Helper for accessing features in {@link Process}.
*/
public final class ProcessCompat {
private ProcessCompat() {
// This class is non-instantiable.
}
/**
* [Docs should match platform docs.]
*
* Compatibility behavior:
* <ul>
* <li>SDK 24 and above, this method matches platform behavior.
* <li>SDK 16 through 23, this method is a best-effort to match platform behavior, but may
* default to returning {@code true} if an accurate result is not available.
* <li>SDK 15 and below, this method always returns {@code true} as application UIDs and
* isolated processes did not exist yet.
* </ul>
*
* @param [match platform docs]
* @return [match platform docs], or a value based on platform-specific fallback behavior
*/
public static boolean isApplicationUid(int uid) {
if (Build.VERSION.SDK_INT >= 24) {
return Api24Impl.isApplicationUid(uid);
} else if (Build.VERSION.SDK_INT >= 16) {
// Fall back to using reflection on private APIs.
// ...
} else {
return true;
}
}
}Wrapper (ex. AccessibilityNodeInfoCompat) {#wrapper}
When to use?
- Platform class may not exist at module's
minSdkVersion - Compatibility implementation may need to store additional metadata
- Needs to integrate with platform APIs as return value or method argument
- Note: Should be avoided when possible, as using wrapper classes makes it
very difficult to deprecate classes and migrate source code when the
minSdkVersionis raised
- Class name must be
<PlatformClass>Compat - Package name must be
androidx.core.<platform.package> - Superclass must not be
<PlatformClass>
- Class may have public constructor(s) to provide parity with public
PlatformClassconstructors- Constructor used to wrap
PlatformClassmust not be public
- Constructor used to wrap
- Class must implement a static
PlatformClassCompat toPlatformClassCompat(PlatformClass)method to wrapPlatformClasson supported SDK levels- If class does not exist at module's
minSdkVersion, method must be annotated with@RequiresApi(<sdk>)for SDK version where class was introduced
- If class does not exist at module's
- Class should be added to the
androidx.core:corelibrary - Class must implement a
PlatformClass toPlatformClass()method to unwrapPlatformClasson supported SDK levels- If class does not exist at module's
minSdkVersion, method must be annotated with@RequiresApi(<sdk>)for SDK version where class was introduced
- If class does not exist at module's
- Implementation may delegate to
PlatformClassmethods when available (see below note for caveats)
The following sample wraps a hypothetical platform class ModemInfo that was
added to the platform SDK in API level 23:
public final class ModemInfoCompat {
// Only guaranteed to be non-null on SDK_INT >= 23. Note that referencing the
// class itself directly is fine -- only references to class members need to
// be pushed into static inner classes.
private final Object wrappedObj;
/**
* [Copy platform docs for matching constructor.]
*/
public ModemInfoCompat() {
if (SDK_INT >= 23) {
wrappedObj = Api23Impl.create();
} else {
wrappedObj = null;
}
}
@RequiresApi(23)
private ModemInfoCompat(@NonNull ModemInfo obj) {
mWrapped = obj;
}
/**
* Provides a backward-compatible wrapper for {@link ModemInfo}.
* <p>
* This method is not supported on devices running SDK < 23 since the platform
* class will not be available.
*
* @param info platform class to wrap
* @return wrapped class, or {@code null} if parameter is {@code null}
*/
@RequiresApi(23)
@NonNull
public static ModemInfoCompat toModemInfoCompat(@NonNull ModemInfo info) {
return new ModemInfoCompat(obj);
}
/**
* Provides the {@link ModemInfo} represented by this object.
* <p>
* This method is not supported on devices running SDK < 23 since the platform
* class will not be available.
*
* @return platform class object
* @see ModemInfoCompat#toModemInfoCompat(ModemInfo)
*/
@RequiresApi(23)
@NonNull
public ModemInfo toModemInfo() {
return mWrapped;
}
/**
* [Docs should match platform docs.]
*
* Compatibility behavior:
* <ul>
* <li>API level 23 and above, this method matches platform behavior.
* <li>API level 18 through 22, this method ...
* <li>API level 17 and earlier, this method always returns false.
* </ul>
*
* @return [match platform docs], or platform-specific fallback behavior
*/
public boolean isLteSupported() {
if (SDK_INT >= 23) {
return Api23Impl.isLteSupported(mWrapped);
} else if (SDK_INT >= 18) {
// Smart fallback behavior based on earlier APIs.
// ...
}
// Default behavior.
return false;
}
}Note that libraries written in Java should express conversion to and from the
platform class differently than Kotlin classes. For Java classes, conversion
from the platform class to the wrapper should be expressed as a static method,
while conversion from the wrapper to the platform class should be a method on
the wrapper object:
@NonNull
public static ModemInfoCompat toModemInfoCompat(@NonNull ModemInfo info);
@NonNull
public ModemInfo toModemInfo();In cases where the primary library is written in Java and has an accompanying
-ktx Kotlin extensions library, the following conversion should be provided as
an extension function:
fun ModemInfo.toModemInfoCompat() : ModemInfoCompatWhereas in cases where the primary library is written in Kotlin, the conversion should be provided as an extension factory:
class ModemInfoCompat {
fun toModemInfo() : ModemInfo
companion object {
@JvmStatic
@JvmName("toModemInfoCompat")
fun ModemInfo.toModemInfoCompat() : ModemInfoCompat
}
}When to use?
- Platform class may exist at module's
minSdkVersion - Does not need to integrate with platform APIs
- Does not need to coexist with platform class, ex. no potential
importcollision due to both compatibility and platform classes being referenced within the same source file
Implementation requirements
- Class name must be
<PlatformClass> - Package name must be
androidx.<platform.package> - Superclass must not be
<PlatformClass> - Class must not expose
PlatformClassin public API- In exceptional cases, a released standalone class may add conversion
between itself and the equivalent platform class; however, new classes
that support conversion should follow the Wrapper
guidelines. In these cases, use a
toPlatform<PlatformClass>andstatic toCompat<PlatformClass>method naming convention.
- In exceptional cases, a released standalone class may add conversion
between itself and the equivalent platform class; however, new classes
that support conversion should follow the Wrapper
guidelines. In these cases, use a
- Implementation may delegate to
PlatformClassmethods when available
When to use
- General purpose library with minimal interaction with Android types
- or when abstraction around types can be used (e.g. Room's SQLite wrapper)
- Lib used in parts of app with minimal Android dependencies
- ex. Repository, ViewModel
- When Android dependency can sit on top of common library
- Clear separation between android dependent and independent parts of your library
- Clear that future integration with android dependencies can be layered separately
Examples:
The Paging Library pages data from DataSources (such as DB content from Room or network content from Retrofit) into PagedLists, so they can be presented in a RecyclerView. Since the included Adapter receives a PagedList, and there are no other Android dependencies, Paging is split into two parts - a no-android library (paging-common) with the majority of the paging code, and an android library (paging-runtime) with just the code to present a PagedList in a RecyclerView Adapter. This way, tests of Repositories and their components can be tested in host-side tests.
Room loads SQLite data on Android, but provides an abstraction for those that want to use a different SQL implementation on device. This abstraction, and the fact that Room generates code dynamically, means that Room interfaces can be used in host-side tests (though actual DB code should be tested on device, since DB impls may be significantly different on host).