From b03c8c508dcbbef364e624ad5bc0ab6fa6733dc7 Mon Sep 17 00:00:00 2001 From: Nick Pelly Date: Tue, 14 Aug 2012 19:13:47 -0700 Subject: Add documentation for com.android.location.provider shared library. Change-Id: I222d61811c88272e84a85512623210c0238337e5 --- location/lib/README.txt | 30 ++++++++++++++++++++++ .../android/location/provider/GeocodeProvider.java | 10 +++++--- .../location/provider/LocationProviderBase.java | 18 ++++++++++--- .../provider/ProviderPropertiesUnbundled.java | 8 +++--- .../provider/ProviderRequestUnbundled.java | 8 +++--- 5 files changed, 61 insertions(+), 13 deletions(-) create mode 100644 location/lib/README.txt (limited to 'location') diff --git a/location/lib/README.txt b/location/lib/README.txt new file mode 100644 index 0000000..400a7dd --- /dev/null +++ b/location/lib/README.txt @@ -0,0 +1,30 @@ +This library (com.android.location.provider.jar) is a shared java library +containing classes required by unbundled location providers. + +--- Rules of this library --- +o This library is effectively a PUBLIC API for unbundled location providers + that may be distributed outside the system image. So it MUST BE API STABLE. + You can add but not remove. The rules are the same as for the + public platform SDK API. +o This library can see and instantiate internal platform classes (such as + ProviderRequest.java), but it must not expose them in any public method + (or by extending them via inheritance). This would break clients of the + library because they cannot see the internal platform classes. + +This library is distributed in the system image, and loaded as +a shared library. So you can change the implementation, but not +the interface. In this way it is like framework.jar. + +--- Why does this library exists? --- + +Unbundled location providers (such as the NetworkLocationProvider) +can not use internal platform classes. + +So ideally all of these classes would be part of the public platform SDK API, +but that doesn't seem like a great idea when only applications with a special +signature can implement this API. + +The compromise is this library. + +It wraps internal platform classes (like ProviderRequest) with a stable +API that does not leak the internal classes. diff --git a/location/lib/java/com/android/location/provider/GeocodeProvider.java b/location/lib/java/com/android/location/provider/GeocodeProvider.java index 666bb02..d7a34af 100644 --- a/location/lib/java/com/android/location/provider/GeocodeProvider.java +++ b/location/lib/java/com/android/location/provider/GeocodeProvider.java @@ -25,12 +25,14 @@ import android.location.IGeocodeProvider; import java.util.List; /** - * An abstract superclass for geocode providers that are implemented - * outside of the core android platform. - * Geocode providers can be implemented as services and return the result of + * Base class for geocode providers implemented as unbundled services. + * + *

Geocode providers can be implemented as services and return the result of * {@link GeocodeProvider#getBinder()} in its getBinder() method. * - * @hide + *

IMPORTANT: This class is effectively a public API for unbundled + * applications, and must remain API stable. See README.txt in the root + * of this package for more information. */ public abstract class GeocodeProvider { diff --git a/location/lib/java/com/android/location/provider/LocationProviderBase.java b/location/lib/java/com/android/location/provider/LocationProviderBase.java index 53b0cae..b0e5d2c 100644 --- a/location/lib/java/com/android/location/provider/LocationProviderBase.java +++ b/location/lib/java/com/android/location/provider/LocationProviderBase.java @@ -34,10 +34,22 @@ import com.android.internal.location.ILocationProvider; import com.android.internal.location.ProviderProperties; import com.android.internal.location.ProviderRequest; - /** - * Base class for location providers implemented as services. - * @hide + * Base class for location providers implemented as unbundled services. + * + *

The network location provider must export a service with action + * "com.android.location.service.v2.NetworkLocationProvider" + * and a valid minor version in a meta-data field on the service, and + * then return the result of {@link #getBinder()} on service binding. + * + *

The fused location provider must export a service with action + * "com.android.location.service.FusedLocationProvider" + * and a valid minor version in a meta-data field on the service, and + * then return the result of {@link #getBinder()} on service binding. + * + *

IMPORTANT: This class is effectively a public API for unbundled + * applications, and must remain API stable. See README.txt in the root + * of this package for more information. */ public abstract class LocationProviderBase { private final String TAG; diff --git a/location/lib/java/com/android/location/provider/ProviderPropertiesUnbundled.java b/location/lib/java/com/android/location/provider/ProviderPropertiesUnbundled.java index c8bdda4..9ee4df2 100644 --- a/location/lib/java/com/android/location/provider/ProviderPropertiesUnbundled.java +++ b/location/lib/java/com/android/location/provider/ProviderPropertiesUnbundled.java @@ -19,9 +19,11 @@ package com.android.location.provider; import com.android.internal.location.ProviderProperties; /** - * This class is a public API for unbundled providers, - * that hides the (hidden framework) ProviderProperties. - *

Do _not_ remove public methods on this class. + * This class is an interface to Provider Properties for unbundled applications. + * + *

IMPORTANT: This class is effectively a public API for unbundled + * applications, and must remain API stable. See README.txt in the root + * of this package for more information. */ public final class ProviderPropertiesUnbundled { private final ProviderProperties mProperties; diff --git a/location/lib/java/com/android/location/provider/ProviderRequestUnbundled.java b/location/lib/java/com/android/location/provider/ProviderRequestUnbundled.java index 3ff19ca..3605381 100644 --- a/location/lib/java/com/android/location/provider/ProviderRequestUnbundled.java +++ b/location/lib/java/com/android/location/provider/ProviderRequestUnbundled.java @@ -23,9 +23,11 @@ import android.location.LocationRequest; import com.android.internal.location.ProviderRequest; /** - * This class is a public API for unbundled providers, - * that hides the (hidden framework) ProviderRequest. - *

Do _not_ remove public methods on this class. + * This class is an interface to Provider Requests for unbundled applications. + * + *

IMPORTANT: This class is effectively a public API for unbundled + * applications, and must remain API stable. See README.txt in the root + * of this package for more information. */ public final class ProviderRequestUnbundled { private final ProviderRequest mRequest; -- cgit v1.1