Set feature request mode | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Use different feature request modes to populate the map from a service feature table.

Screenshot of set feature request mode

Use case

Feature tables can be initialized with a feature request mode which controls how frequently features are requested and locally cached in response to panning, zooming, selecting, or querying. The feature request mode affects performance and should be chosen based on considerations such as how often the data is expected to change or how often changes in the data should be reflected to the user.

OnInteractionCache - fetches features within the current extent when needed (after a pan or zoom action) from the server and caches those features in a table on the client. Queries will be performed locally if the features are present, otherwise they will be requested from the server. This mode minimizes requests to the server and is useful for large batches of features which will change infrequently.
OnInteractionNoCache - always fetches features from the server and doesn’t cache any features on the client. This mode is best for features that may change often on the server or whose changes need to always be visible.

NOTE: No cache does not guarantee that features won’t be cached locally. Feature request mode is a performance concept unrelated to data security.
ManualCache - only fetches features when explicitly populated from a query. This mode is best for features that change minimally or when it is not critical for the user to see the latest changes.

How to use the sample

Choose a request mode by clicking on the drop down menu. Pan and zoom to see how the features update at different scales. If you choose “Manual cache”, click the “Populate” button to manually get a cache with a subset of features.

Note: The service limits requests to 2000 features.

How it works

Create a ServiceFeatureTable with a feature service URL and use it to create a FeatureLayer.
Add the feature layer to the map’s operational layers.
Set the FeatureRequestMode property of the service feature table to the desired mode (OnInteractionCache, OnInteractionNoCache, or ManualCache).
- If using ManualCache, populate the features with ServiceFeatureTable.populateFromService(...).

Relevant API

FeatureLayer
ServiceFeatureTable
ServiceFeatureTable.FeatureRequestMode

About the data

This sample uses the Trees of Portland service showcasing over 200,000 street trees in Portland, OR. Each tree point models the health of the tree (green - better, red - worse) as well as the diameter of its trunk.

Sample Code

MainActivity.kt

SetFeatureRequestModeViewModel.kt

SetFeatureRequestModeScreen.kt

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.setfeaturerequestmode

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.runtime.Composable
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
import com.esri.arcgismaps.sample.setfeaturerequestmode.screens.SetFeatureRequestModeScreen

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // authentication with an API key or named user is
        // required to access basemaps and other location services
        ArcGISEnvironment.apiKey = ApiKey.create(BuildConfig.ACCESS_TOKEN)

        enableEdgeToEdge()
        setContent {
            SampleAppTheme {
                SetFeatureRequestModeApp()
            }
        }
    }

    @Composable
    private fun SetFeatureRequestModeApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            SetFeatureRequestModeScreen(
                sampleName = getString(R.string.set_feature_request_mode_app_name)
            )
        }
    }
}

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.setfeaturerequestmode.components

import android.app.Application
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import com.arcgismaps.data.FeatureRequestMode
import com.arcgismaps.data.QueryParameters
import com.arcgismaps.data.ServiceFeatureTable
import com.arcgismaps.geometry.Envelope
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.mapping.layers.FeatureLayer
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialogViewModel
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import java.util.Collections

class SetFeatureRequestModeViewModel(application: Application) : AndroidViewModel(application) {

    // Feature table of street trees in Portland
    private val featureTable =
        ServiceFeatureTable("https://services2.arcgis.com/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Trees_of_Portland/FeatureServer/0")

    val arcGISMap =
        ArcGISMap(BasemapStyle.ArcGISTopographic).apply {
            // Set a viewpoint to downtown Portland, OR
            initialViewpoint = Viewpoint(latitude = 45.5266, longitude = -122.6219, scale = 6000.0)
            // Create a feature layer from the feature table and add it to the map
            operationalLayers.add(FeatureLayer.createWithFeatureTable(featureTable))
        }

    private var viewpoint: Viewpoint? = null

    var currentFeatureRequestMode by mutableStateOf<FeatureRequestMode>(FeatureRequestMode.OnInteractionCache)
        private set

    var isLoading by mutableStateOf(false)
        private set

    // Create a message dialog view model for handling error messages
    val messageDialogVM = MessageDialogViewModel()

    init {
        viewModelScope.launch {
            arcGISMap.load().onFailure { error ->
                messageDialogVM.showMessageDialog(
                    "Failed to load map",
                    error.message.toString()
                )
            }
        }
    }

    /**
     * Called when the viewpoint of the map changes.
     */
    fun onViewpointChange(viewpoint: Viewpoint) {
        this.viewpoint = viewpoint
    }

    /**
     * Called when the feature request mode is changed.
     */
    fun onCurrentFeatureRequestModeChanged(featureRequestMode: FeatureRequestMode) {
        currentFeatureRequestMode = featureRequestMode
        featureTable.featureRequestMode = featureRequestMode
    }

    /**
     * Demonstrates how to manually fetch features from the service feature table using the current viewpoint.
     */
    fun fetchCacheManually() {

        // Show the progress indicator
        isLoading = true

        // Create query to select all tree features
        val queryParams = QueryParameters().apply {
            // Query for all tree conditions except "dead" with coded value '4' within the visible extent
            whereClause = "Condition < '4'"
            geometry = viewpoint?.targetGeometry as Envelope
        }

        // Setting this to * means all features
        val outfields: List<String> = Collections.singletonList("*")

        viewModelScope.launch(Dispatchers.IO) {
            // Get queried features from service feature table and clear previous cache
            featureTable.populateFromService(
                parameters = queryParams,
                clearCache = true,
                outFields = outfields
            ).onSuccess {
                // hide the loading ProgressBar
                isLoading = false
            }
        }
    }
}

/* Copyright 2025 Esri
 *
 * 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.esri.arcgismaps.sample.setfeaturerequestmode.screens

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.material3.Button
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.data.FeatureRequestMode
import com.arcgismaps.toolkit.geoviewcompose.MapView
import com.esri.arcgismaps.sample.sampleslib.components.DropDownMenuBox
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialog
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
import com.esri.arcgismaps.sample.setfeaturerequestmode.components.SetFeatureRequestModeViewModel

/**
 * Main screen layout for the sample app
 */
@Composable
fun SetFeatureRequestModeScreen(sampleName: String) {

    val mapViewModel: SetFeatureRequestModeViewModel = viewModel()

    val featureRequestModes = listOf(
        FeatureRequestMode.OnInteractionCache, FeatureRequestMode.OnInteractionNoCache, FeatureRequestMode.ManualCache
    )

    Scaffold(topBar = { SampleTopAppBar(title = sampleName) }, content = {
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(it),
        ) {
            MapView(
                modifier = Modifier
                    .fillMaxSize()
                    .weight(1f),
                arcGISMap = mapViewModel.arcGISMap,
                onViewpointChangedForBoundingGeometry = { boundingGeometry ->
                    mapViewModel.onViewpointChange(boundingGeometry)
                },
            )
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .padding(8.dp),
                horizontalArrangement = Arrangement.SpaceEvenly,
                verticalAlignment = Alignment.CenterVertically,
            ) {
                DropDownMenuBox(
                    textFieldLabel = "Feature request mode:",
                    textFieldValue = mapViewModel.currentFeatureRequestMode.javaClass.simpleName,
                    dropDownItemList = featureRequestModes.map { it.javaClass.simpleName },
                    onIndexSelected = { index -> mapViewModel.onCurrentFeatureRequestModeChanged(featureRequestModes[index]) })
                Button(
                    onClick = { mapViewModel.fetchCacheManually() },
                    // Only enable the button when the feature request mode is set to manual cache
                    enabled = mapViewModel.currentFeatureRequestMode == FeatureRequestMode.ManualCache
                ) {
                    if (mapViewModel.isLoading) {
                        CircularProgressIndicator(
                            modifier = Modifier.requiredSize(24.dp),
                            color = androidx.compose.ui.graphics.Color.White
                        )
                    } else {
                        Text(
                            modifier = Modifier,
                            text = "Populate",
                        )
                    }
                }
            }
        }

        mapViewModel.messageDialogVM.apply {
            if (dialogStatus) {
                MessageDialog(
                    title = messageTitle, description = messageDescription, onDismissRequest = ::dismissDialog
                )
            }
        }
    })
}