feat: implement Java sample parity, animations, and interaction handlers

- Implement verified Java sample parity fixes across Camera, VisibleRegion, Marker, Boundaries, DatasetStyling, CloudStyling, GroundOverlay, and TileOverlay
- Simulate Fowler / Rattlesnake GPX track and add modern runtime permission launcher in LocationSourceDemoActivity
- Polish layouts, touch targets, and coordinate displays across Java sample activities

Author: dkhawk

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/AdvancedMarkersDemoActivity.java

@@ -13,6 +13,10 @@
 // limitations under the License.
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import android.graphics.Color;
 import android.os.Bundle;
 import android.util.Log;
@@ -46,6 +50,18 @@
  * possibilities.
  */
 // [START maps_android_sample_marker_advanced]
+@Sample(
+    id = "advanced_markers",
+    title = "Advanced Markers & Pins",
+    description = "Modern PinConfig pins, custom glyphs, badge icon views, and collision behavior.",
+    category = "Markers & Overlays",
+    complexity = Complexity.ADVANCED,
+    tags = {"#markers", "#advancedmarkers", "#pinconfig", "#collision", "#badges", "#mapid"},
+    purpose = "Demonstrates Cloud-backed Advanced Markers with custom colors, pin glyphs, collision behaviors, and custom View icons.",
+    successCriteria = "Custom colored pins and badge icon views render sharply at correct anchor points with collision handling.",
+    failureIndicators = "Pins render as default red markers (missing Map ID), collision behavior ignored, or badge text blurry.",
+    framework = Framework.JAVA_VIEWS
+)
 public class AdvancedMarkersDemoActivity extends SamplesBaseActivity implements OnMapReadyCallback {
 
     private static final LatLng SINGAPORE = new LatLng(1.3521, 103.8198);
@@ -152,13 +168,17 @@ public void onMapReady(GoogleMap map) {
         pinConfigBuilder.setBackgroundColor(Color.MAGENTA);
         PinConfig pinConfig = pinConfigBuilder.build();
 
-        // Use the  PinConfig instance to set the icon for AdvancedMarkerOptions.
+        // Use the PinConfig instance to set the icon for AdvancedMarkerOptions.
         AdvancedMarkerOptions advancedMarkerOptions = new AdvancedMarkerOptions()
                 .icon(BitmapDescriptorFactory.fromPinConfig(pinConfig))
-                .position(KUALA_LUMPUR);
+                .position(KUALA_LUMPUR)
+                .title("Kuala Lumpur (Magenta Pin)");
 
         // Pass the AdvancedMarkerOptions instance to addMarker().
         Marker marker = map.addMarker(advancedMarkerOptions);
+        if (marker != null) {
+            marker.showInfoWindow();
+        }
 
         // This sample changes the border color of the advanced marker
         PinConfig.Builder pinConfigBuilder2 = PinConfig.builder();
@@ -167,7 +187,8 @@ public void onMapReady(GoogleMap map) {
 
         AdvancedMarkerOptions advancedMarkerOptions2 = new AdvancedMarkerOptions()
                 .icon(BitmapDescriptorFactory.fromPinConfig(pinConfig2))
-                .position(JAKARTA);
+                .position(JAKARTA)
+                .title("Jakarta (Blue Border)");
 
         Marker marker2 = map.addMarker(advancedMarkerOptions2);
 
@@ -182,7 +203,8 @@ public void onMapReady(GoogleMap map) {
 
         AdvancedMarkerOptions advancedMarkerOptions3 = new AdvancedMarkerOptions()
                 .icon(BitmapDescriptorFactory.fromPinConfig(pinConfig3))
-                .position(BANGKOK);
+                .position(BANGKOK)
+                .title("Bangkok (Text Glyph 'A')");
 
         Marker marker3 = map.addMarker(advancedMarkerOptions3);
 
@@ -194,7 +216,8 @@ public void onMapReady(GoogleMap map) {
 
         AdvancedMarkerOptions advancedMarkerOptions4 = new AdvancedMarkerOptions()
                 .icon(BitmapDescriptorFactory.fromPinConfig(pinConfig4))
-                .position(MANILA);
+                .position(MANILA)
+                .title("Manila (Transparent Cutout Glyph)");
 
         Marker marker4 = map.addMarker(advancedMarkerOptions4);
 
@@ -203,7 +226,8 @@ public void onMapReady(GoogleMap map) {
         int collisionBehavior = AdvancedMarkerOptions.CollisionBehavior.REQUIRED_AND_HIDES_OPTIONAL;
         AdvancedMarkerOptions advancedMarkerOptions5 = new AdvancedMarkerOptions()
                 .position(HO_CHI_MINH_CITY)
-                .collisionBehavior(collisionBehavior);
+                .collisionBehavior(collisionBehavior)
+                .title("Ho Chi Minh City (Collision Behavior)");
 
         Marker marker5 = map.addMarker(advancedMarkerOptions5);
     }

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/BasicMapDemoActivity.java

@@ -14,6 +14,11 @@
 
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
+import com.google.android.gms.maps.CameraUpdateFactory;
 import com.google.android.gms.maps.GoogleMap;
 import com.google.android.gms.maps.OnMapReadyCallback;
 import com.google.android.gms.maps.SupportMapFragment;
@@ -28,8 +33,28 @@
  * This shows how to create a simple activity with a map and a marker on the map.
  */
 // [START maps_android_sample_basic_map]
+@Sample(
+    id = "basic_map",
+    title = "Basic Map",
+    description = "Fundamental map instantiation, lifecycle binding, and default camera centering.",
+    category = "Map Initialization",
+    complexity = Complexity.SNIPPET,
+    tags = {"#map", "#init", "#lifecycle", "#quickstart"},
+    apiCalls = {
+        "SupportMapFragment.getMapAsync(OnMapReadyCallback)",
+        "GoogleMap.addMarker(MarkerOptions)",
+        "GoogleMap.moveCamera(CameraUpdate)"
+    },
+    purpose = "Demonstrates clean, minimal map instantiation using SupportMapFragment.",
+    successCriteria = "The map loads default vector tiles cleanly centered at the initial coordinates with working gestures.",
+    failureIndicators = "Grey tiles (missing API key or auth mismatch), crash on back navigation, or map failing to unpause.",
+    framework = Framework.JAVA_VIEWS
+)
 public class BasicMapDemoActivity extends SamplesBaseActivity implements OnMapReadyCallback {
 
+    private static final LatLng SYDNEY = new LatLng(-33.862, 151.21);
+    private static final float ZOOM_LEVEL = 13.0f;
+
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
@@ -43,12 +68,12 @@ protected void onCreate(Bundle savedInstanceState) {
 
     /**
      * This is where we can add markers or lines, add listeners or move the camera. In this case,
-     * we
-     * just add a marker near Africa.
+     * we move the camera to Sydney and add a marker at Sydney.
      */
     @Override
     public void onMapReady(GoogleMap map) {
-        map.addMarker(new MarkerOptions().position(new LatLng(0, 0)).title("Marker"));
+        map.moveCamera(CameraUpdateFactory.newLatLngZoom(SYDNEY, ZOOM_LEVEL));
+        map.addMarker(new MarkerOptions().position(SYDNEY).title("Sydney"));
     }
 }
 // [END maps_android_sample_basic_map]

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/CameraClampingDemoActivity.java

@@ -15,6 +15,10 @@
 
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import com.google.android.gms.maps.CameraUpdateFactory;
 import com.google.android.gms.maps.GoogleMap;
 import com.google.android.gms.maps.GoogleMap.OnCameraIdleListener;
@@ -30,6 +34,18 @@
 /**
  * This shows how to constrain the camera to specific boundaries and zoom levels.
  */
+@Sample(
+    id = "camera_clamping",
+    title = "Camera Clamping & Bounds",
+    description = "Constraining camera viewport to LatLngBounds and dynamic min/max zoom limits.",
+    category = "Camera Controls",
+    complexity = Complexity.SIMPLE,
+    tags = {"#camera", "#clamping", "#bounds", "#zoomlimits", "#latlngbounds"},
+    purpose = "Demonstrates restricting camera panning to a specific bounding box (Adelaide/Pacific) and zoom slider limits.",
+    successCriteria = "User cannot pan the camera outside the clamped region; zoom sliders enforce min/max bounds immediately.",
+    failureIndicators = "Camera pans outside bounding box or resetting bounds fails when selecting 'Reset Bounds'.",
+    framework = Framework.JAVA_VIEWS
+)
 public class CameraClampingDemoActivity extends SamplesBaseActivity
         implements OnMapReadyCallback, OnCameraIdleListener, GoogleMap.OnCameraMoveListener {
 

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/CameraDemoActivity.java

@@ -15,6 +15,10 @@
 
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import android.graphics.Color;
 import android.os.Bundle;
 import android.util.Log;
@@ -37,13 +41,32 @@
 import com.google.android.gms.maps.SupportMapFragment;
 import com.google.android.gms.maps.model.CameraPosition;
 import com.google.android.gms.maps.model.LatLng;
+import com.google.android.gms.maps.model.MarkerOptions;
 import com.example.common_ui.databinding.CameraDemoBinding;
 import com.google.android.gms.maps.model.PolylineOptions;
 
 /**
  * This shows how to change the camera position for the map.
  */
 // [START maps_camera_events]
+@Sample(
+    id = "camera_demo",
+    title = "Camera Controls & Animation",
+    description = "Programmatic camera panning, zooming, tilt, bearing, and smooth animations.",
+    category = "Camera Controls",
+    complexity = Complexity.SIMPLE,
+    tags = {"#camera", "#animation", "#bearing", "#tilt", "#zoom", "#pan"},
+    apiCalls = {
+        "GoogleMap.animateCamera(CameraUpdate)",
+        "GoogleMap.moveCamera(CameraUpdate)",
+        "GoogleMap.addMarker(MarkerOptions)",
+        "CameraUpdateFactory.newCameraPosition(CameraPosition)"
+    },
+    purpose = "Demonstrates programmatic camera movements, animated transitions, tilt angles, and bearing rotations.",
+    successCriteria = "Buttons animate camera smoothly with custom durations, stops, and rotation angles.",
+    failureIndicators = "Jerky animations, unexpected camera jumps, or tilt angle exceeding platform constraints.",
+    framework = Framework.JAVA_VIEWS
+)
 public class CameraDemoActivity extends SamplesBaseActivity implements
         OnCameraMoveStartedListener,
         OnCameraMoveListener,
@@ -140,7 +163,11 @@ public void onMapReady(GoogleMap googleMap) {
         // [END_EXCLUDE]
 
         // Show Sydney
-        map.moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(-33.87365, 151.20689), 10));
+        LatLng sydneyLatLng = new LatLng(-33.87365, 151.20689);
+        LatLng bondiLatLng = new LatLng(-33.891614, 151.276417);
+        map.moveCamera(CameraUpdateFactory.newLatLngZoom(sydneyLatLng, 10));
+        map.addMarker(new MarkerOptions().position(sydneyLatLng).title("Sydney"));
+        map.addMarker(new MarkerOptions().position(bondiLatLng).title("Bondi Beach"));
     }
 
     public GoogleMap getMap() {

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/CircleDemoActivity.java

@@ -14,6 +14,10 @@
 
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import android.graphics.Color;
 import android.graphics.Point;
 import android.location.Location;
@@ -56,6 +60,18 @@
 /**
  * This shows how to draw circles on a map.
  */
+@Sample(
+    id = "circles",
+    title = "Circles & Geodesic Radii",
+    description = "Drawing geographic circles with dynamic center drag, radius sliders, and stroke styling.",
+    category = "Shapes & Geometry",
+    complexity = Complexity.SIMPLE,
+    tags = {"#shapes", "#circles", "#radius", "#geodesic"},
+    purpose = "Demonstrates drawing circles with radius defined in meters and dynamic updates via seekbars.",
+    successCriteria = "Adjusting radius slider dynamically updates circle boundary in real-time.",
+    failureIndicators = "Circle distorted or radius math inaccurate across high latitudes.",
+    framework = Framework.JAVA_VIEWS
+)
 public class CircleDemoActivity extends SamplesBaseActivity
     implements OnSeekBarChangeListener, OnMarkerDragListener, OnMapLongClickListener,
     OnItemSelectedListener, OnMapReadyCallback, MapProvider {

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/CloudBasedMapStylingDemoActivity.java

@@ -16,9 +16,12 @@
 
 import android.os.Bundle;
 import androidx.appcompat.app.AppCompatActivity;
+import com.example.common_ui.R;
+import com.google.android.gms.maps.CameraUpdateFactory;
 import com.google.android.gms.maps.GoogleMap;
 import com.google.android.gms.maps.OnMapReadyCallback;
 import com.google.android.gms.maps.SupportMapFragment;
+import com.google.android.gms.maps.model.LatLng;
 
 /**
  * This shows how to use Cloud-based Map Styling in a simple Activity. For more information on how
@@ -40,29 +43,31 @@ protected void onCreate(Bundle savedInstanceState) {
 
         // The underlying style the map will use has been set in the layout
         // `cloud_styling_basic_demo` under the SupportMapFragment's `map:mapId` attribute.
-        setContentView(com.example.common_ui.R.layout.cloud_styling_basic_demo);
+        setContentView(R.layout.cloud_styling_basic_demo);
         SupportMapFragment mapFragment =
-            (SupportMapFragment) getSupportFragmentManager().findFragmentById(com.example.common_ui.R.id.map);
+            (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
         mapFragment.getMapAsync(this);
 
         setUpButtonListeners();
-        applyInsets(findViewById(com.example.common_ui.R.id.map_container));
+        applyInsets(findViewById(R.id.map_container));
     }
 
     @Override
     public void onMapReady(GoogleMap map) {
         this.map = map;
         map.setMapType(currentMapType);
+        LatLng montBlanc = new LatLng(45.8326, 6.8652);
+        map.moveCamera(CameraUpdateFactory.newLatLngZoom(montBlanc, 11.5f));
     }
 
     private void setUpButtonListeners() {
-        findViewById(com.example.common_ui.R.id.styling_normal_mode).setOnClickListener(
+        findViewById(R.id.styling_normal_mode).setOnClickListener(
             v -> setMapType(GoogleMap.MAP_TYPE_NORMAL));
-        findViewById(com.example.common_ui.R.id.styling_satellite_mode).setOnClickListener(
+        findViewById(R.id.styling_satellite_mode).setOnClickListener(
             v -> setMapType(GoogleMap.MAP_TYPE_SATELLITE));
-        findViewById(com.example.common_ui.R.id.styling_hybrid_mode).setOnClickListener(
+        findViewById(R.id.styling_hybrid_mode).setOnClickListener(
             v -> setMapType(GoogleMap.MAP_TYPE_HYBRID));
-        findViewById(com.example.common_ui.R.id.styling_terrain_mode).setOnClickListener(
+        findViewById(R.id.styling_terrain_mode).setOnClickListener(
             v -> setMapType(GoogleMap.MAP_TYPE_TERRAIN));
     }
 

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/DataDrivenBoundariesActivity.java

@@ -13,6 +13,10 @@
 // limitations under the License.
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import static java.lang.Math.round;
 
 import android.graphics.Color;
@@ -58,6 +62,18 @@
  * https://developers.google.com/maps/documentation/android-sdk/dds-boundaries/overview
  */
 // [START maps_android_data_driven_styling_boundaries]
+@Sample(
+    id = "data_driven_boundaries",
+    title = "Data-Driven Boundaries",
+    description = "Dynamic styling and click handlers for administrative boundaries (Localities, States, Countries).",
+    category = "Data-Driven Styling",
+    complexity = Complexity.ADVANCED,
+    tags = {"#boundaries", "#datadriven", "#featurelayer", "#locality", "#choropleth"},
+    purpose = "Demonstrates styling administrative boundaries dynamically via FeatureLayer and capturing boundary clicks.",
+    successCriteria = "Boundaries render with custom stroke and fill colors; tapping a region highlights its polygon.",
+    failureIndicators = "Boundary layer is null (requires vector map / Map ID) or click listener not firing.",
+    framework = Framework.JAVA_VIEWS
+)
 public class DataDrivenBoundariesActivity extends SamplesBaseActivity implements OnMapReadyCallback,
         FeatureLayer.OnFeatureClickListener, PopupMenu.OnMenuItemClickListener {
     private static final String TAG = DataDrivenBoundariesActivity.class.getName();
@@ -119,8 +135,16 @@ protected void onCreate(Bundle savedInstanceState) {
 
         mapFragment.getMapAsync(this);
 
-        findViewById(R.id.button_hawaii).setOnClickListener(view -> centerMapOnLocation(HANA_HAWAII, 11f));
-        findViewById(R.id.button_us).setOnClickListener(view -> centerMapOnLocation(CENTER_US, 1f));
+        findViewById(R.id.button_hawaii).setOnClickListener(view -> {
+            localityEnabled = true;
+            updateStyles();
+            centerMapOnLocation(HANA_HAWAII, 11f);
+        });
+        findViewById(R.id.button_us).setOnClickListener(view -> {
+            adminAreaEnabled = true;
+            updateStyles();
+            centerMapOnLocation(CENTER_US, 3.8f);
+        });
 
         applyInsets(findViewById(R.id.map_container));
 

ApiDemos/project/java-app/src/main/java/com/example/mapdemo/DataDrivenDatasetStylingActivity.java

@@ -13,6 +13,10 @@
 // limitations under the License.
 package com.example.mapdemo;
 
+import com.example.common_ui.catalog.Sample;
+import com.example.common_ui.catalog.Complexity;
+import com.example.common_ui.catalog.Framework;
+
 import android.graphics.Color;
 import android.os.Bundle;
 import android.util.Log;
@@ -55,6 +59,18 @@
  * This is meant to work with the datasets in the res/raw directory.
  */
 // [START maps_android_data_driven_styling_datasets]
+@Sample(
+    id = "data_driven_datasets",
+    title = "Data-Driven Dataset Styling",
+    description = "Styling custom geospatial datasets uploaded to Google Cloud Platform based on attributes.",
+    category = "Data-Driven Styling",
+    complexity = Complexity.ADVANCED,
+    tags = {"#datasets", "#datadriven", "#clouddata", "#attributes", "#filtering"},
+    purpose = "Demonstrates loading a Cloud Dataset FeatureLayer and applying dynamic style rules based on feature properties.",
+    successCriteria = "Dataset points and polygons display distinct styling according to attribute values.",
+    failureIndicators = "Dataset ID invalid or attributes fail to filter correctly.",
+    framework = Framework.JAVA_VIEWS
+)
 public class DataDrivenDatasetStylingActivity extends SamplesBaseActivity implements OnMapReadyCallback, FeatureLayer.OnFeatureClickListener {
     private record DataSet(
             String label,