LocationCompat.java

/*
 * Copyright 2021 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.core.location;

import static java.util.concurrent.TimeUnit.MILLISECONDS;
import static java.util.concurrent.TimeUnit.NANOSECONDS;

import android.location.Location;
import android.os.Build.VERSION;
import android.os.Bundle;
import android.os.SystemClock;

import androidx.annotation.DoNotInline;
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import androidx.annotation.RequiresApi;

import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;

/**
 * Helper for accessing features in {@link android.location.Location}.
 */
public final class LocationCompat {

    private static final String EXTRA_IS_MOCK = "mockLocation";

    @Nullable
    private static Method sSetIsFromMockProviderMethod;

    private LocationCompat() {}

    /**
     * Return the time of this fix, in nanoseconds of elapsed real-time since system boot.
     *
     * <p>This value can be reliably compared to SystemClock.elapsedRealtimeNanos(), to calculate
     * the age of a fix and to compare location fixes. This is reliable because elapsed real-time
     * is guaranteed monotonic for each system boot and continues to increment even when the
     * system is in deep sleep (unlike getTime().
     *
     * <p>All locations generated by the LocationManager are guaranteed to have a valid elapsed
     * real-time.
     *
     * <p>NOTE: On API levels below 17, this method will attempt to provide an elapsed realtime
     * based on the difference between system time and the location time. This should be taken as a
     * best "guess" at what the elapsed realtime might have been, but if the clock used for
     * location derivation is different from the system clock, the results may be inaccurate.
     */
    public static long getElapsedRealtimeNanos(@NonNull Location location) {
        if (VERSION.SDK_INT >= 17) {
            return Api17Impl.getElapsedRealtimeNanos(location);
        } else {
            return MILLISECONDS.toNanos(getElapsedRealtimeMillis(location));
        }
    }

    /**
     * Return the time of this fix, in milliseconds of elapsed real-time since system boot.
     *
     * @see #getElapsedRealtimeNanos(Location)
     */
    public static long getElapsedRealtimeMillis(@NonNull Location location) {
        if (VERSION.SDK_INT >= 17) {
            return NANOSECONDS.toMillis(Api17Impl.getElapsedRealtimeNanos(location));
        } else {
            long timeDeltaMs = System.currentTimeMillis() - location.getTime();
            long elapsedRealtimeMs = SystemClock.elapsedRealtime();
            if (timeDeltaMs < 0) {
                // don't return an elapsed realtime from the future
                return elapsedRealtimeMs;
            } else if (timeDeltaMs > elapsedRealtimeMs) {
                // don't return an elapsed realtime from before boot
                return 0;
            } else {
                return elapsedRealtimeMs - timeDeltaMs;
            }
        }
    }

    /**
     * Returns true if this location is marked as a mock location. If this location comes from the
     * Android framework, this indicates that the location was provided by a test location provider,
     * and thus may not be related to the actual location of the device.
     *
     * <p>NOTE: On API levels below 18, the concept of a mock location does not exist. In order to
     * allow for backwards compatibility and testing however, this method will attempt to read a
     * boolean extra with the key "mockLocation" and use the result to determine whether this should
     * be considered a mock location.
     *
     * @see android.location.LocationManager#addTestProvider
     */
    public static boolean isMock(@NonNull Location location) {
        if (VERSION.SDK_INT >= 18) {
            return Api18Impl.isMock(location);
        } else {
            Bundle extras = location.getExtras();
            if (extras == null) {
                return false;
            }

            return extras.getBoolean(EXTRA_IS_MOCK, false);
        }
    }

    /**
     * Sets whether this location is marked as a mock location.
     *
     * <p>NOTE: On API levels below 18, the concept of a mock location does not exist. In order to
     * allow for backwards compatibility and testing however, this method will attempt to set a
     * boolean extra with the key "mockLocation" to mark the location as mock. Be aware that this
     * will overwrite any prior extra value under the same key.
     */
    public static void setMock(@NonNull Location location, boolean mock) {
        if (VERSION.SDK_INT >= 18) {
            try {
                getSetIsFromMockProviderMethod().invoke(location, mock);
            } catch (NoSuchMethodException e) {
                Error error = new NoSuchMethodError();
                error.initCause(e);
                throw error;
            } catch (IllegalAccessException e) {
                Error error = new IllegalAccessError();
                error.initCause(e);
                throw error;
            } catch (InvocationTargetException e) {
                throw new RuntimeException(e);
            }
        } else {
            Bundle extras = location.getExtras();
            if (extras == null) {
                extras = new Bundle();
                extras.putBoolean(EXTRA_IS_MOCK, true);
                location.setExtras(extras);
            } else {
                extras.putBoolean(EXTRA_IS_MOCK, true);
            }
        }
    }

    @RequiresApi(18)
    private static class Api18Impl {

        private Api18Impl() {}

        @DoNotInline
        static boolean isMock(Location location) {
            return location.isFromMockProvider();
        }
    }

    @RequiresApi(17)
    private static class Api17Impl {

        private Api17Impl() {}

        @DoNotInline
        static long getElapsedRealtimeNanos(Location location) {
            return location.getElapsedRealtimeNanos();
        }
    }

    private static Method getSetIsFromMockProviderMethod() throws NoSuchMethodException {
        if (sSetIsFromMockProviderMethod == null) {
            sSetIsFromMockProviderMethod = Location.class.getDeclaredMethod("setIsFromMockProvider",
                    boolean.class);
            sSetIsFromMockProviderMethod.setAccessible(true);
        }

        return sSetIsFromMockProviderMethod;
    }
}