feat(demo): Add StreetViewJavaHelper and demo and enable edge-to-edge (#1595)

* feat(demo): Add Java demo for Street View utility

This commit adds a new demo activity written in Java to demonstrate the usage of the Street View utility. To facilitate this, a Kotlin helper has been introduced to bridge the gap between suspend functions and Java's callback-based asynchronous model.

The key changes are:
- **`StreetViewDemoActivityJava`**: A new demo activity that shows how to check for Street View availability from Java.
- **`StreetViewHelper`**: A Kotlin object that wraps the `suspend` function `StreetViewUtils.fetchStreetViewData` and exposes it to Java consumers via a callback interface.
- **`ApiKeyValidator`**: A new utility class to check for a valid Maps API key within the demo application.
- **Unit Tests**: Added tests for `StreetViewHelper` using Robolectric, MockK, and coroutine testing libraries to verify its behavior.
- **Dependencies**: Added `mockk`, `kotlinx-coroutines-test`, and `robolectric` to the demo module's test dependencies.

* feat(demo): Enable edge-to-edge for StreetView demo activities

This commit refactors the `StreetViewDemoActivity` in both its Kotlin and Java versions to support edge-to-edge display.

The key changes include:
- Changing the base class from `Activity` to `AppCompatActivity`.
- Using `WindowCompat.setDecorFitsSystemWindows` to allow the app to draw behind the system bars.
- Adding an `OnApplyWindowInsetsListener` to the root view to apply padding for the system bars, preventing content from being obscured.
- Updating the `street_view_demo.xml` layout with an ID for the root view to facilitate the insets listener.
- Updating the copyright year.

* refactor(library): Move StreetViewJavaHelper to library module

This commit moves the `StreetViewHelper` from the `demo` module to the `library` module, making it an officially supported utility for Java consumers.

The key changes include:
- Renaming `StreetViewHelper` to `StreetViewJavaHelper` for better clarity and moving it to the `com.google.maps.android` package within the library.
- Migrating the corresponding unit tests from the `demo` to the `library` module and updating them to reflect the class rename.
- Adjusting `build.gradle.kts` files to move test dependencies (`mockk`, `coroutines-test`, `robolectric`) from the `demo` to the `library` module.
- Renaming `StreetViewDemoActivityJava` to `StreetViewDemoJavaActivity` and updating it to use the new helper from the library.
- Improving the warning message for invalid or missing API keys in the demo app.

* refactor: Remove redundant Javadoc in StreetViewDemoJavaActivity

Author: dkhawk

demo/src/main/AndroidManifest.xml

@@ -124,6 +124,9 @@
         <activity
             android:name=".StreetViewDemoActivity"
             android:exported="true" />
+        <activity
+            android:name=".StreetViewDemoJavaActivity"
+            android:exported="true" />
         <activity
             android:name=".ClusterAlgorithmsDemoActivity"
             android:exported="true" />

demo/src/main/java/com/google/maps/android/utils/demo/ApiKeyValidator.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * 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 com.google.maps.android.utils.demo;
+
+import android.content.Context;
+import android.content.pm.PackageManager;
+import android.os.Bundle;
+
+import java.util.regex.Pattern;
+
+/**
+ * A utility class to validate the Maps API key. The purpose of this check is to ensure that a
+ * developer has set a valid-looking key. This is not a definitive check, and there is a
+ * possibility of a false negative. If you are sure your key is correct, you can remove this
+ * check.
+ */
+class ApiKeyValidator {
+    private static final String REGEX = "^AIza[0-9A-Za-z-_]{35}$";
+    private static final Pattern PATTERN = Pattern.compile(REGEX);
+
+    /**
+     * Checks if the provided context has a valid Google Maps API key in its metadata.
+     *
+     * @param context The context to check for the API key.
+     * @return `true` if the context has a valid API key, `false` otherwise.
+     */
+    static boolean hasMapsApiKey(Context context) {
+        String mapsApiKey = getMapsApiKey(context);
+        return mapsApiKey != null && PATTERN.matcher(mapsApiKey).matches();
+    }
+
+    /**
+     * Retrieves the Google Maps API key from the application metadata.
+     *
+     * @param context The context to retrieve the API key from.
+     * @return The API key if found, `null` otherwise.
+     */
+    private static String getMapsApiKey(Context context) {
+        try {
+            Bundle bundle = context.getPackageManager()
+                .getApplicationInfo(context.getPackageName(), PackageManager.GET_META_DATA)
+                .metaData;
+            return bundle.getString("com.google.android.geo.API_KEY");
+        } catch (PackageManager.NameNotFoundException e) {
+            e.printStackTrace();
+            return null;
+        }
+    }
+}

demo/src/main/java/com/google/maps/android/utils/demo/MainActivity.java

@@ -87,6 +87,7 @@ protected void onCreate(Bundle savedInstanceState) {
         addDemo("Multi Layer", MultiLayerDemoActivity.class);
         addDemo("AnimationUtil sample", AnimationUtilDemoActivity.class);
         addDemo("Street View Demo", StreetViewDemoActivity.class);
+        addDemo("Street View Demo (Java)", StreetViewDemoJavaActivity.class);
     }
 
     private void addDemo(String demoName, Class<? extends Activity> activityClass) {

demo/src/main/java/com/google/maps/android/utils/demo/StreetViewDemoActivity.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,35 +17,61 @@
 package com.google.maps.android.utils.demo
 
 import android.annotation.SuppressLint
-import android.app.Activity
 import android.os.Bundle
 import android.widget.TextView
 import android.widget.Toast
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.lifecycle.lifecycleScope
 import com.google.android.gms.maps.model.LatLng
 import com.google.maps.android.StreetViewUtils
-import kotlinx.coroutines.DelicateCoroutinesApi
 import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.launch
 
-class StreetViewDemoActivity : Activity() {
+/**
+ * An activity that demonstrates how to use the [StreetViewUtils] to check for Street View
+ * availability at different locations.
+ *
+ * This activity performs the following actions:
+ * 1. Sets up the layout to fit system windows.
+ * 2. Checks if a valid Google Maps API key is present.
+ * 3. Launches a coroutine to fetch Street View data for two predefined locations.
+ * 4. Displays the results of the Street View data fetch on the screen.
+ */
+class StreetViewDemoActivity : AppCompatActivity() {
 
     @SuppressLint("SetTextI18n")
-    @OptIn(DelicateCoroutinesApi::class)
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
+        // Make the activity content fit behind the system bars.
+        WindowCompat.setDecorFitsSystemWindows(window, false)
         setContentView(R.layout.street_view_demo)
 
+        // Apply window insets to the main view to avoid content overlapping with system bars.
+        ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
+            val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
+            v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
+            insets
+        }
+
+        // Check for a valid Maps API key before proceeding.
         if (!hasMapsApiKey(this)) {
             Toast.makeText(this, R.string.bad_maps_api_key, Toast.LENGTH_LONG).show()
             finish()
+            return // Return early to prevent further execution
         }
 
-        GlobalScope.launch(Dispatchers.Main) {
+        // Launch a coroutine in the Main dispatcher to fetch Street View data and update the UI.
+        lifecycleScope.launch(Dispatchers.Main) {
+            // Fetch Street View data for the first location (which is expected to be supported).
             val response1 =
                 StreetViewUtils.fetchStreetViewData(LatLng(48.1425918, 11.5386121), BuildConfig.MAPS_API_KEY)
+            // Fetch Street View data for the second location (which is expected to be unsupported).
             val response2 = StreetViewUtils.fetchStreetViewData(LatLng(8.1425918, 11.5386121), BuildConfig.MAPS_API_KEY)
 
+            // Update the UI with the results.
             findViewById<TextView>(R.id.textViewFirstLocation).text = "Location 1 is supported in StreetView: $response1"
             findViewById<TextView>(R.id.textViewSecondLocation).text = "Location 2 is  supported in StreetView: $response2"
         }

demo/src/main/java/com/google/maps/android/utils/demo/StreetViewDemoJavaActivity.java

@@ -0,0 +1,104 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * 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 com.google.maps.android.utils.demo;
+
+import android.annotation.SuppressLint;
+import android.os.Bundle;
+import android.util.Log;
+import android.widget.TextView;
+import android.widget.Toast;
+
+import androidx.annotation.NonNull;
+import androidx.appcompat.app.AppCompatActivity;
+import androidx.core.graphics.Insets;
+import androidx.core.view.ViewCompat;
+import androidx.core.view.WindowCompat;
+import androidx.core.view.WindowInsetsCompat;
+
+import com.google.android.gms.maps.model.LatLng;
+import com.google.maps.android.Status;
+import com.google.maps.android.StreetViewJavaHelper;
+
+/**
+ * An activity that demonstrates how to use the Street View utility in Java to check for Street View
+ * availability at different locations.
+ * <p>
+ * This activity performs the following actions:
+ * 1. Sets up the layout to fit system windows.
+ * 2. Checks if a valid Google Maps API key is present.
+ * 3. Fetches Street View data for two predefined locations using asynchronous callbacks.
+ * 4. Displays the results of the Street View data fetch on the screen.
+ */
+public class StreetViewDemoJavaActivity extends AppCompatActivity {
+
+    @SuppressLint("SetTextI18n")
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        // Make the activity content fit behind the system bars.
+        WindowCompat.setDecorFitsSystemWindows(getWindow(), false);
+        setContentView(R.layout.street_view_demo);
+
+        // Apply window insets to the main view to avoid content overlapping with system bars.
+        ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main), (v, insetsCompat) -> {
+            Insets insets = insetsCompat.getInsets(WindowInsetsCompat.Type.systemBars());
+            v.setPadding(insets.left, insets.top, insets.right, insets.bottom);
+            return insetsCompat;
+        });
+
+        // Check for a valid Maps API key before proceeding.
+        if (!ApiKeyValidator.hasMapsApiKey(this)) {
+            Toast.makeText(this, R.string.bad_maps_api_key, Toast.LENGTH_LONG).show();
+            finish();
+            return; // Return early to prevent further execution
+        }
+
+        // Fetches Street View data for the first location (expected to be supported).
+        StreetViewJavaHelper.fetchStreetViewData(
+                new LatLng(48.1425918, 11.5386121),
+                BuildConfig.MAPS_API_KEY, new StreetViewJavaHelper.StreetViewCallback() {
+                    @Override
+                    public void onStreetViewResult(@NonNull Status status) {
+                        // Updates the UI with the result on the UI thread.
+                        runOnUiThread(() -> ((TextView) findViewById(R.id.textViewFirstLocation)).setText("Location 1 is supported in StreetView: " + status));
+                    }
+
+                    @Override
+                    public void onStreetViewError(@NonNull Exception e) {
+                        // Handles the error by printing stack trace and showing a toast.
+                        Log.w("SVJDemo", "Error fetching Street View data: " + e.getMessage());
+                        Toast.makeText(StreetViewDemoJavaActivity.this, "Error fetching Street View data: " + e.getMessage(), Toast.LENGTH_SHORT).show();
+                    }
+                });
+
+        // Fetches Street View data for the second location (expected to be unsupported).
+        StreetViewJavaHelper.fetchStreetViewData(new LatLng(8.1425918, 11.5386121), BuildConfig.MAPS_API_KEY, new StreetViewJavaHelper.StreetViewCallback() {
+            @Override
+            public void onStreetViewResult(@NonNull Status status) {
+                // Updates the UI with the result on the UI thread.
+                runOnUiThread(() -> ((TextView) findViewById(R.id.textViewSecondLocation)).setText("Location 2 is  supported in StreetView: " + status));
+            }
+
+            @Override
+            public void onStreetViewError(@NonNull Exception e) {
+                // Handles the error by printing stack trace and showing a toast.
+                Log.w("SVJDemo", "Error fetching Street View data: " + e.getMessage());
+                Toast.makeText(StreetViewDemoJavaActivity.this, "Error fetching Street View data: " + e.getMessage(), Toast.LENGTH_SHORT).show();
+            }
+        });
+    }
+}

demo/src/main/res/layout/street_view_demo.xml

@@ -16,6 +16,7 @@
 -->
 
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/main"
     android:orientation="vertical"
     android:layout_width="match_parent"
     android:layout_height="match_parent">

demo/src/main/res/values/strings.xml

@@ -33,5 +33,5 @@
     <string name="button_radius">Radius</string>
     <string name="button_gradient">Gradient</string>
     <string name="button_opacity">Opacity</string>
-    <string name="bad_maps_api_key">Invalid or missing Google Maps API key</string>
+    <string name="bad_maps_api_key">The Google Maps API key looks invalid or is missing. If you are sure your key is correct, you can remove this check from the demo.</string>
 </resources>

gradle/libs.versions.toml

@@ -35,6 +35,7 @@ lifecycle-viewmodel-ktx = { module = "androidx.lifecycle:lifecycle-viewmodel-ktx
 kotlin-stdlib-jdk8 = { module = "org.jetbrains.kotlin:kotlin-stdlib-jdk8", version.ref = "kotlin" }
 kotlinx-coroutines-android = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-android", version.ref = "kotlinx-coroutines" }
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
+kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "kotlinx-coroutines" }
 junit = { module = "junit:junit", version.ref = "junit" }
 mockito-core = { module = "org.mockito:mockito-core", version.ref = "mockito-core" }
 secrets-gradle-plugin = { module = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin", version.ref = "secrets-gradle-plugin" }

library/build.gradle.kts

@@ -71,6 +71,10 @@ dependencies {
     testImplementation(libs.kotlin.test)
     testImplementation(libs.truth)
     implementation(libs.kotlin.stdlib.jdk8)
+
+    testImplementation(libs.mockk)
+    testImplementation(libs.kotlinx.coroutines.test)
+    testImplementation(libs.robolectric)
 }
 
 tasks.register("instrumentTest") {

library/src/main/java/com/google/maps/android/StreetViewJavaHelper.kt

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * 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 com.google.maps.android
+
+import com.google.android.gms.maps.model.LatLng
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+
+/**
+ * A helper object to call the suspend function `fetchStreetViewData` from Java.
+ */
+object StreetViewJavaHelper {
+    /**
+     * A callback interface to receive the result of the Street View data fetch.
+     */
+    interface StreetViewCallback {
+        /**
+         * Called when the Street View data is fetched successfully.
+         *
+         * @param status The status of the Street View data.
+         */
+        fun onStreetViewResult(status: Status)
+
+        /**
+         * Called when there is an error fetching the Street View data.
+         *
+         * @param e The exception that occurred.
+         */
+        fun onStreetViewError(e: Exception)
+    }
+
+    /**
+     * Fetches Street View data for the given location and returns the result via a callback.
+     *
+     * @param latLng The location to fetch Street View data for.
+     * @param apiKey The API key to use for the request.
+     * @param callback The callback to receive the result.
+     */
+    @JvmStatic
+    fun fetchStreetViewData(latLng: LatLng, apiKey: String, callback: StreetViewCallback) {
+        CoroutineScope(Dispatchers.Main).launch {
+            try {
+                val status = StreetViewUtils.fetchStreetViewData(latLng, apiKey)
+                callback.onStreetViewResult(status)
+            } catch (e: Exception) {
+                callback.onStreetViewError(e)
+            }
+        }
+    }
+}