From a15524ad5c4f3e1e8f97951b49c7db50b20d9687 Mon Sep 17 00:00:00 2001 From: Neil Fuller Date: Fri, 30 Sep 2022 17:23:02 +0100 Subject: [PATCH] API changes for device initialization / SUW The API changes for device initialization / SetUp Wizard. Besides removing @hide, this commit deletes some tests (which can now be covered by CTS) and makes minor doc and annotation updates. Bug: 236612872 Test: See associated CTS changes Test: atest core/tests/coretests/src/android/app/time/ Change-Id: I0c99c55e5e4dd339cfd226fc472ba8c8f2cf1d2f --- core/api/system-current.txt | 65 +++++++++++++++++++ .../android/app/time/TimeCapabilities.java | 2 + .../app/time/TimeCapabilitiesAndConfig.java | 2 + .../android/app/time/TimeConfiguration.java | 3 + core/java/android/app/time/TimeManager.java | 36 +++++----- core/java/android/app/time/TimeState.java | 2 + .../app/time/TimeZoneCapabilities.java | 2 - core/java/android/app/time/TimeZoneState.java | 2 + core/java/android/app/time/UnixEpochTime.java | 5 +- .../app/time/TimeConfigurationTest.java | 56 ---------------- .../android/app/time/UnixEpochTimeTest.java | 45 +------------ 11 files changed, 100 insertions(+), 120 deletions(-) delete mode 100644 core/tests/coretests/src/android/app/time/TimeConfigurationTest.java diff --git a/core/api/system-current.txt b/core/api/system-current.txt index 134b71a492724..60f0312ee7979 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -2493,11 +2493,49 @@ package android.app.time { field @NonNull public static final android.os.Parcelable.Creator CREATOR; } + public final class TimeCapabilities implements android.os.Parcelable { + method public int describeContents(); + method public int getConfigureAutoDetectionEnabledCapability(); + method public int getSetManualTimeCapability(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + + public final class TimeCapabilitiesAndConfig implements android.os.Parcelable { + method public int describeContents(); + method @NonNull public android.app.time.TimeCapabilities getCapabilities(); + method @NonNull public android.app.time.TimeConfiguration getConfiguration(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + + public final class TimeConfiguration implements android.os.Parcelable { + method public int describeContents(); + method public boolean isAutoDetectionEnabled(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + + public static final class TimeConfiguration.Builder { + ctor public TimeConfiguration.Builder(); + ctor public TimeConfiguration.Builder(@NonNull android.app.time.TimeConfiguration); + method @NonNull public android.app.time.TimeConfiguration build(); + method @NonNull public android.app.time.TimeConfiguration.Builder setAutoDetectionEnabled(boolean); + } + public final class TimeManager { method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public void addTimeZoneDetectorListener(@NonNull java.util.concurrent.Executor, @NonNull android.app.time.TimeManager.TimeZoneDetectorListener); + method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean confirmTime(@NonNull android.app.time.UnixEpochTime); + method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean confirmTimeZone(@NonNull String); + method @NonNull @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public android.app.time.TimeCapabilitiesAndConfig getTimeCapabilitiesAndConfig(); + method @NonNull @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public android.app.time.TimeState getTimeState(); method @NonNull @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public android.app.time.TimeZoneCapabilitiesAndConfig getTimeZoneCapabilitiesAndConfig(); + method @NonNull @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public android.app.time.TimeZoneState getTimeZoneState(); method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public void removeTimeZoneDetectorListener(@NonNull android.app.time.TimeManager.TimeZoneDetectorListener); + method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean setManualTime(@NonNull android.app.time.UnixEpochTime); + method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean setManualTimeZone(@NonNull String); method @RequiresPermission(android.Manifest.permission.SUGGEST_EXTERNAL_TIME) public void suggestExternalTime(@NonNull android.app.time.ExternalTimeSuggestion); + method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean updateTimeConfiguration(@NonNull android.app.time.TimeConfiguration); method @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean updateTimeZoneConfiguration(@NonNull android.app.time.TimeZoneConfiguration); } @@ -2505,10 +2543,19 @@ package android.app.time { method public void onChange(); } + public final class TimeState implements android.os.Parcelable { + method public int describeContents(); + method @NonNull public android.app.time.UnixEpochTime getUnixEpochTime(); + method public boolean getUserShouldConfirmTime(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + public final class TimeZoneCapabilities implements android.os.Parcelable { method public int describeContents(); method public int getConfigureAutoDetectionEnabledCapability(); method public int getConfigureGeoDetectionEnabledCapability(); + method public int getSetManualTimeZoneCapability(); method public void writeToParcel(@NonNull android.os.Parcel, int); field @NonNull public static final android.os.Parcelable.Creator CREATOR; } @@ -2537,6 +2584,24 @@ package android.app.time { method @NonNull public android.app.time.TimeZoneConfiguration.Builder setGeoDetectionEnabled(boolean); } + public final class TimeZoneState implements android.os.Parcelable { + method public int describeContents(); + method @NonNull public String getId(); + method public boolean getUserShouldConfirmId(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + + public final class UnixEpochTime implements android.os.Parcelable { + ctor public UnixEpochTime(long, long); + method @NonNull public android.app.time.UnixEpochTime at(long); + method public int describeContents(); + method public long getElapsedRealtimeMillis(); + method public long getUnixEpochTimeMillis(); + method public void writeToParcel(@NonNull android.os.Parcel, int); + field @NonNull public static final android.os.Parcelable.Creator CREATOR; + } + } package android.app.usage { diff --git a/core/java/android/app/time/TimeCapabilities.java b/core/java/android/app/time/TimeCapabilities.java index 76bad58e924ba..752caac0c5cde 100644 --- a/core/java/android/app/time/TimeCapabilities.java +++ b/core/java/android/app/time/TimeCapabilities.java @@ -20,6 +20,7 @@ import static android.app.time.Capabilities.CAPABILITY_NOT_APPLICABLE; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.SystemApi; import android.app.time.Capabilities.CapabilityState; import android.os.Parcel; import android.os.Parcelable; @@ -37,6 +38,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class TimeCapabilities implements Parcelable { public static final @NonNull Creator CREATOR = new Creator<>() { diff --git a/core/java/android/app/time/TimeCapabilitiesAndConfig.java b/core/java/android/app/time/TimeCapabilitiesAndConfig.java index b6a0818257572..c9a45e04227aa 100644 --- a/core/java/android/app/time/TimeCapabilitiesAndConfig.java +++ b/core/java/android/app/time/TimeCapabilitiesAndConfig.java @@ -17,6 +17,7 @@ package android.app.time; import android.annotation.NonNull; +import android.annotation.SystemApi; import android.os.Parcel; import android.os.Parcelable; @@ -27,6 +28,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class TimeCapabilitiesAndConfig implements Parcelable { public static final @NonNull Creator CREATOR = diff --git a/core/java/android/app/time/TimeConfiguration.java b/core/java/android/app/time/TimeConfiguration.java index 7d986983160ee..048f85a1e1a4f 100644 --- a/core/java/android/app/time/TimeConfiguration.java +++ b/core/java/android/app/time/TimeConfiguration.java @@ -18,6 +18,7 @@ package android.app.time; import android.annotation.NonNull; import android.annotation.StringDef; +import android.annotation.SystemApi; import android.os.Bundle; import android.os.Parcel; import android.os.Parcelable; @@ -40,6 +41,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class TimeConfiguration implements Parcelable { public static final @NonNull Creator CREATOR = @@ -155,6 +157,7 @@ public final class TimeConfiguration implements Parcelable { * * @hide */ + @SystemApi public static final class Builder { private final Bundle mBundle = new Bundle(); diff --git a/core/java/android/app/time/TimeManager.java b/core/java/android/app/time/TimeManager.java index 9f66f094786b9..e35e359424e2b 100644 --- a/core/java/android/app/time/TimeManager.java +++ b/core/java/android/app/time/TimeManager.java @@ -88,8 +88,6 @@ public final class TimeManager { /** * Returns the calling user's time capabilities and configuration. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) @NonNull @@ -107,10 +105,26 @@ public final class TimeManager { /** * Modifies the time detection configuration. * - * @return {@code true} if all the configuration settings specified have been set to the - * new values, {@code false} if none have + *

The ability to modify configuration settings can be subject to restrictions. For + * example, they may be determined by device hardware, general policy (i.e. only the primary + * user can set them), or by a managed device policy. Use {@link + * #getTimeCapabilitiesAndConfig()} to obtain information at runtime about the user's + * capabilities. * - * @hide + *

Attempts to modify configuration settings with capabilities that are {@link + * Capabilities#CAPABILITY_NOT_SUPPORTED} or {@link + * Capabilities#CAPABILITY_NOT_ALLOWED} will have no effect and a {@code false} + * will be returned. Modifying configuration settings with capabilities that are {@link + * Capabilities#CAPABILITY_NOT_APPLICABLE} or {@link + * Capabilities#CAPABILITY_POSSESSED} will succeed. See {@link + * TimeZoneCapabilities} for further details. + * + *

If the supplied configuration only has some values set, then only the specified settings + * will be updated (where the user's capabilities allow) and other settings will be left + * unchanged. + * + * @return {@code true} if all the configuration settings specified have been set to the + * new values, {@code false} if none have */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean updateTimeConfiguration(@NonNull TimeConfiguration configuration) { @@ -280,8 +294,6 @@ public final class TimeManager { /** * Returns a snapshot of the device's current system clock time state. See also {@link * #confirmTime(UnixEpochTime)} for how this information can be used. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) @NonNull @@ -306,8 +318,6 @@ public final class TimeManager { *

Returns {@code false} if the confirmation is invalid, i.e. if the time being * confirmed is no longer the time the device is currently set to. Confirming a time * in which the system already has high confidence will return {@code true}. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean confirmTime(@NonNull UnixEpochTime unixEpochTime) { @@ -329,8 +339,6 @@ public final class TimeManager { * capabilities prevents the time being accepted, e.g. if the device is currently set to * "automatic time detection". This method returns {@code true} if the time was accepted even * if it is the same as the current device time. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean setManualTime(@NonNull UnixEpochTime unixEpochTime) { @@ -353,8 +361,6 @@ public final class TimeManager { * Returns a snapshot of the device's current time zone state. See also {@link * #confirmTimeZone(String)} and {@link #setManualTimeZone(String)} for how this information may * be used. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) @NonNull @@ -379,8 +385,6 @@ public final class TimeManager { *

Returns {@code false} if the confirmation is invalid, i.e. if the time zone ID being * confirmed is no longer the time zone ID the device is currently set to. Confirming a time * zone ID in which the system already has high confidence returns {@code true}. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean confirmTimeZone(@NonNull String timeZoneId) { @@ -402,8 +406,6 @@ public final class TimeManager { * capabilities prevents the time zone being accepted, e.g. if the device is currently set to * "automatic time zone detection". {@code true} is returned if the time zone is accepted. A * time zone that is accepted and matches the current device time zone returns {@code true}. - * - * @hide */ @RequiresPermission(android.Manifest.permission.MANAGE_TIME_AND_ZONE_DETECTION) public boolean setManualTimeZone(@NonNull String timeZoneId) { diff --git a/core/java/android/app/time/TimeState.java b/core/java/android/app/time/TimeState.java index 01c869d993382..c209cde2cf496 100644 --- a/core/java/android/app/time/TimeState.java +++ b/core/java/android/app/time/TimeState.java @@ -18,6 +18,7 @@ package android.app.time; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.SystemApi; import android.os.Parcel; import android.os.Parcelable; import android.os.ShellCommand; @@ -36,6 +37,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class TimeState implements Parcelable { public static final @NonNull Creator CREATOR = new Creator<>() { diff --git a/core/java/android/app/time/TimeZoneCapabilities.java b/core/java/android/app/time/TimeZoneCapabilities.java index 2f147cef9ffe7..b647fc33055da 100644 --- a/core/java/android/app/time/TimeZoneCapabilities.java +++ b/core/java/android/app/time/TimeZoneCapabilities.java @@ -114,8 +114,6 @@ public final class TimeZoneCapabilities implements Parcelable { *

The time zone will be ignored in all cases unless the value is {@link * Capabilities#CAPABILITY_POSSESSED}. See also * {@link TimeZoneConfiguration#isAutoDetectionEnabled()}. - * - * @hide */ @CapabilityState public int getSetManualTimeZoneCapability() { diff --git a/core/java/android/app/time/TimeZoneState.java b/core/java/android/app/time/TimeZoneState.java index 8e87111986ceb..beb6dc6d1dfb2 100644 --- a/core/java/android/app/time/TimeZoneState.java +++ b/core/java/android/app/time/TimeZoneState.java @@ -18,6 +18,7 @@ package android.app.time; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.SystemApi; import android.os.Parcel; import android.os.Parcelable; import android.os.ShellCommand; @@ -36,6 +37,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class TimeZoneState implements Parcelable { public static final @NonNull Creator CREATOR = new Creator<>() { diff --git a/core/java/android/app/time/UnixEpochTime.java b/core/java/android/app/time/UnixEpochTime.java index 576bf6453ecac..3a35f3cd1acb3 100644 --- a/core/java/android/app/time/UnixEpochTime.java +++ b/core/java/android/app/time/UnixEpochTime.java @@ -19,6 +19,7 @@ package android.app.time; import android.annotation.ElapsedRealtimeLong; import android.annotation.NonNull; import android.annotation.Nullable; +import android.annotation.SystemApi; import android.os.Parcel; import android.os.Parcelable; import android.os.ShellCommand; @@ -38,6 +39,7 @@ import java.util.Objects; * * @hide */ +@SystemApi public final class UnixEpochTime implements Parcelable { @ElapsedRealtimeLong private final long mElapsedRealtimeMillis; private final long mUnixEpochTimeMillis; @@ -153,9 +155,8 @@ public final class UnixEpochTime implements Parcelable { * Creates a new Unix epoch time value at {@code elapsedRealtimeTimeMillis} by adjusting this * Unix epoch time by the difference between the elapsed realtime value supplied and the one * associated with this instance. - * - * @hide */ + @NonNull public UnixEpochTime at(@ElapsedRealtimeLong long elapsedRealtimeTimeMillis) { long adjustedUnixEpochTimeMillis = (elapsedRealtimeTimeMillis - mElapsedRealtimeMillis) + mUnixEpochTimeMillis; diff --git a/core/tests/coretests/src/android/app/time/TimeConfigurationTest.java b/core/tests/coretests/src/android/app/time/TimeConfigurationTest.java deleted file mode 100644 index 7c7cd12bcb73a..0000000000000 --- a/core/tests/coretests/src/android/app/time/TimeConfigurationTest.java +++ /dev/null @@ -1,56 +0,0 @@ -/* - * Copyright (C) 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 android.app.time; - -import static android.app.timezonedetector.ParcelableTestSupport.assertRoundTripParcelable; - -import static com.google.common.truth.Truth.assertThat; - -import androidx.test.filters.SmallTest; -import androidx.test.runner.AndroidJUnit4; - -import org.junit.Test; -import org.junit.runner.RunWith; - -@RunWith(AndroidJUnit4.class) -@SmallTest -public class TimeConfigurationTest { - - @Test - public void testBuilder() { - TimeConfiguration first = new TimeConfiguration.Builder() - .setAutoDetectionEnabled(true) - .build(); - - assertThat(first.isAutoDetectionEnabled()).isTrue(); - - TimeConfiguration copyFromBuilderConfiguration = new TimeConfiguration.Builder(first) - .build(); - - assertThat(first).isEqualTo(copyFromBuilderConfiguration); - } - - @Test - public void testParcelable() { - TimeConfiguration.Builder builder = new TimeConfiguration.Builder(); - - assertRoundTripParcelable(builder.setAutoDetectionEnabled(true).build()); - - assertRoundTripParcelable(builder.setAutoDetectionEnabled(false).build()); - } - -} diff --git a/core/tests/coretests/src/android/app/time/UnixEpochTimeTest.java b/core/tests/coretests/src/android/app/time/UnixEpochTimeTest.java index 3ab01f3d88328..e7d352cfee308 100644 --- a/core/tests/coretests/src/android/app/time/UnixEpochTimeTest.java +++ b/core/tests/coretests/src/android/app/time/UnixEpochTimeTest.java @@ -16,11 +16,9 @@ package android.app.time; -import static android.app.timezonedetector.ParcelableTestSupport.assertRoundTripParcelable; import static android.app.timezonedetector.ShellCommandTestSupport.createShellCommandWithArgsAndOptions; import static org.junit.Assert.assertEquals; -import static org.junit.Assert.assertNotEquals; import android.os.ShellCommand; @@ -31,35 +29,12 @@ import org.junit.runner.RunWith; /** * Tests for non-SDK methods on {@link UnixEpochTime}. + * + *

See also {@link android.app.time.cts.UnixEpochTimeTest} for SDK methods. */ @RunWith(AndroidJUnit4.class) public class UnixEpochTimeTest { - @Test - public void testEqualsAndHashcode() { - UnixEpochTime one1000one = new UnixEpochTime(1000, 1); - assertEqualsAndHashCode(one1000one, one1000one); - - UnixEpochTime one1000two = new UnixEpochTime(1000, 1); - assertEqualsAndHashCode(one1000one, one1000two); - - UnixEpochTime two1000 = new UnixEpochTime(1000, 2); - assertNotEquals(one1000one, two1000); - - UnixEpochTime one2000 = new UnixEpochTime(2000, 1); - assertNotEquals(one1000one, one2000); - } - - private static void assertEqualsAndHashCode(Object one, Object two) { - assertEquals(one, two); - assertEquals(one.hashCode(), two.hashCode()); - } - - @Test - public void testParceling() { - assertRoundTripParcelable(new UnixEpochTime(1000, 1)); - } - @Test(expected = IllegalArgumentException.class) public void testParseCommandLineArg_noElapsedRealtime() { ShellCommand testShellCommand = createShellCommandWithArgsAndOptions( @@ -90,22 +65,6 @@ public class UnixEpochTimeTest { UnixEpochTime.parseCommandLineArgs(testShellCommand); } - @Test - public void testAt() { - long timeMillis = 1000L; - int elapsedRealtimeMillis = 100; - UnixEpochTime unixEpochTime = new UnixEpochTime(elapsedRealtimeMillis, timeMillis); - // Reference time is after the timestamp. - UnixEpochTime at125 = unixEpochTime.at(125); - assertEquals(timeMillis + (125 - elapsedRealtimeMillis), at125.getUnixEpochTimeMillis()); - assertEquals(125, at125.getElapsedRealtimeMillis()); - - // Reference time is before the timestamp. - UnixEpochTime at75 = unixEpochTime.at(75); - assertEquals(timeMillis + (75 - elapsedRealtimeMillis), at75.getUnixEpochTimeMillis()); - assertEquals(75, at75.getElapsedRealtimeMillis()); - } - @Test public void testElapsedRealtimeDifference() { UnixEpochTime value1 = new UnixEpochTime(1000, 123L);