Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.data

Class ServiceFeatureTable

java.lang.Object
com.esri.arcgisruntime.data.FeatureTable
com.esri.arcgisruntime.data.ArcGISFeatureTable
com.esri.arcgisruntime.data.ServiceFeatureTable
All Implemented Interfaces:
ApiKeyResource, RemoteResource, Loadable, PopupSource
public final class ServiceFeatureTable extends ArcGISFeatureTable implements RemoteResource, ApiKeyResource
A table of features that typically represent real-world objects created from an ArcGIS feature service.

An instance of this class represents the dataset of an individual layer or table in an ArcGIS map or feature service. The map or feature service may be hosted in the cloud on ArcGIS Online, or on-premises on an ArcGIS Server. To access these services you may need to provide authentication in your application.

You can construct a ServiceFeatureTable directly from the feature service using its URI or PortalItem. Alternatively, you can obtain a ServiceFeatureTable from a FeatureLayer or a FeatureTable that is part of an ArcGISMap or ArcGISScene. You can also obtain a ServiceFeatureTable directly from its service geodatabase using ServiceGeodatabase.getTable(long).

The ServiceFeatureTable adopts the loadable pattern so many of its properties are initialized asynchronously after connecting to the service. For more information, see Loadable.

Display

If FeatureTable.hasGeometry() is true, you can display the features in an ArcGISMap or ArcGISScene. To do this create a FeatureLayer from the feature table and add it to the map or scene's collection of operational layers (GeoModel.getOperationalLayers()). Spatial features are requested in the SpatialReference that matches the ArcGISMap or ArcGISScene and are displayed using the Symbol information defined by the map or feature service.

Query

You can query the data in the ServiceFeatureTable based on SQL expressions and/or spatial relationships. Use the QueryParameters object to define your spatial or attribute query and pass it to the queryFeaturesAsync(QueryParameters, QueryFeatureFields) method. If the service feature table is related to any other tables that are part of the map or scene, use the queryRelatedFeaturesAsync(ArcGISFeature, RelatedQueryParameters, QueryFeatureFields) method to query the related tables. For more information, see RelatedQueryParameters.

Edit

A ServiceFeatureTable can have editable attribute fields, feature templates (FeatureTemplate), feature types (FeatureType), and editing capabilities defined in ArcGISFeatureLayerInfo.getCapabilities(). You can create, delete, and update data in the local cache depending upon whether the service allows those operations, who owns the data, and what ownership-based access control policies are in place. Permission to edit the data is managed by the author of the feature service. Explore FeatureTable.isEditable(), FeatureTable.canAdd(), FeatureTable.canUpdate(Feature), and FeatureTable.canDelete(Feature) for information on what is permitted. If the service supports attachments (ArcGISFeatureTable.hasAttachments()), you can also view and potentially edit the attachments. If you want to apply your edits to the feature service, you must call the ServiceGeodatabase.applyEditsAsync() method on the getServiceGeodatabase(). This will ensure that the table and any tables involved in geodatabase behavior are updated. Areas that have geodatabase behavior include:

  • Composite relationships
  • Annotation feature layers
  • Utility network association deletion semantics
  • Attribute rules

Contingent Values

The ServiceFeatureTable supports querying and editing contingent values. See ArcGISFeatureTable.getContingentValues(ArcGISFeature, String) for more information.

Offline

If you wish to adopt an offline workflow, you can take areas of a ServiceFeatureTable offline using the GeodatabaseSyncTask. If you wish to take an ArcGISMap offline use the OfflineMapTask. See Build offline applications for more information.

Feature Request Mode

The ServiceFeatureTable.FeatureRequestMode determines whether ServiceFeatureTable features are cached locally (for quicker access by map and scene layers) and whether queries are performed on the local cache or on the server. Consider which of these 3 modes is appropriate for your application:

  • ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE - User interactions (pan or zoom) with the MapView or SceneView request features from the server and cache them locally for the duration of the session. Subsequent interactions with the MapView or SceneView will refresh this local cache. Queries are executed on the local cache or (if requested features are not resident in the cache) on the server. If the network connection is lost then the application can still operate with the local cache. This is the default mode.
  • ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_NO_CACHE - Your application will display or query features directly from the server. They are not cached locally. This mode ensures that you are working against the latest data, but it has a high network bandwidth since it goes to the server for all interactions (pans, zooms, selects, or queries).
  • ServiceFeatureTable.FeatureRequestMode.MANUAL_CACHE - Your application must explicitly call populateFromServiceAsync(QueryParameters, boolean, Iterable) to query the feature service and cache the resulting features in the ServiceFeatureTable. All queries are made against this local cache. You must adopt this mode for tables that contain non-spatial records (see ServiceFeatureTable.getHasGeometry()).
Since:
100.0.0
See Also:

  • Constructor Details

    • ServiceFeatureTable

      public ServiceFeatureTable(String uri)
      Creates a new service feature table object from a given URI. To use a request configuration, call setRequestConfiguration(com.esri.arcgisruntime.io.RequestConfiguration) after this constructor and before loading this table. To use a credential, call setCredential(Credential) after this constructor and before loading this table.
      Parameters:
      uri - the URI of an individual layer or table in an ArcGIS map or feature service
      Throws:
      IllegalArgumentException - if uri is null or empty
      Since:
      100.0.0

    • ServiceFeatureTable

      public ServiceFeatureTable(ServiceFeatureTable table, RelationshipInfo relationshipInfo)
      Creates a ServiceFeatureTable instance that relates to the given table based on the given relationship information.
      Parameters:
      table - the related table
      relationshipInfo - the relationship information defining the relationship between this new table and the given table
      Throws:
      IllegalArgumentException - if table or relationshipInfo are null
      Since:
      100.1.0

    • ServiceFeatureTable

      public ServiceFeatureTable(PortalItem portalItem, long layerId)
      Creates a new service feature table instance from a feature service portal item.
      Parameters:
      portalItem - an ArcGIS feature service PortalItem
      layerId - the layer id of an individual layer in the ArcGIS feature service represented by the PortalItem
      Throws:
      IllegalArgumentException - if portalItem is null
      Since:
      100.3.0

    • ServiceFeatureTable

      public ServiceFeatureTable(PortalItem portalItem)
      Creates a new service feature table object from an ArcGIS feature service or feature layer portal item.

      If the portal item is a feature service, the ServiceFeatureTable will be created from the first layer on the service. If the portal item is a feature layer, the ServiceFeatureTable will be created from the feature layer.

      Parameters:
      portalItem - an ArcGIS feature service or feature layer PortalItem
      Throws:
      IllegalArgumentException - if portalItem is null
      Since:
      100.14.0
      See Also:

  • Method Details

    • getUri

      public String getUri()
      Returns the URI used to create the table.
      Specified by:
      getUri in interface RemoteResource
      Returns:
      the URI used to create the table.
      Since:
      100.0.0

    • setRequestConfiguration

      public void setRequestConfiguration(RequestConfiguration requestConfiguration)
      Sets configuration parameters used for network requests sent using this table object. The global RequestConfiguration is used if no RequestConfiguration is set or null is set
      Specified by:
      setRequestConfiguration in interface RemoteResource
      Parameters:
      requestConfiguration - object containing the parameters to use
      Since:
      100.0.0

    • getRequestConfiguration

      public RequestConfiguration getRequestConfiguration()
      Gets the RequestConfiguration object in use by this table. If null is returned, then that indicates that the global RequestConfiguration is used instead.
      Specified by:
      getRequestConfiguration in interface RemoteResource
      Returns:
      the RequestConfiguration object or null if none has been set
      Since:
      100.0.0
      See Also:

    • setCredential

      public void setCredential(Credential credential)
      Sets the credential used to authenticate the user with the service feature table.
      Specified by:
      setCredential in interface RemoteResource
      Parameters:
      credential - the credential used to authenticate the user with the service feature table
      Since:
      100.0.0

    • getCredential

      public Credential getCredential()
      Gets the credential used to authenticate the user with the service feature table.
      Specified by:
      getCredential in interface RemoteResource
      Returns:
      the credential used to authenticate the user with the service feature table
      Since:
      100.0.0

    • getBufferFactor

      public double getBufferFactor()
      Gets the factor used to calculate a buffered extent around the current visible area when requesting features from a service.

      New features are requested from the service if the visible area of the MapView exceeds the buffered extent. A change in the visible area can result from any user interaction with the MapView, such as a pan or zoom action. The buffer factor is applied when the ServiceFeatureTable.FeatureRequestMode is in either ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE or ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_NO_CACHE.

      The default value is 2 (twice the current extent). The maximum value is 10. If it is set to 0 or 1, the buffered extent will equal the visible map area.

      Returns:
      the factor used to calculate a buffered extent around the current visible area when requesting features from a service
      Since:
      100.0.0
      See Also:

    • setBufferFactor

      public void setBufferFactor(double bufferFactor)
      Sets the factor used to calculate a buffered extent around the current visible area when requesting features from a service.

      New features are requested from the service if the visible area of the MapView exceeds the buffered extent. A change in the visible area can result from any user interaction with the MapView, such as a pan or zoom action. The buffer factor is applied when the ServiceFeatureTable.FeatureRequestMode is in either ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE or ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_NO_CACHE.

      The maximum value is 10. If it is set to 0 or 1, the buffered extent will equal the visible map area.

      The buffered extent is calculated as: 

       
 width = bufferFactor : extent.width; 
 height = bufferFactor : extent.height;
      Parameters:
      bufferFactor - the factor used to calculate a buffered extent around the current visible area when requesting features from a service
      Since:
      100.0.0

    • getExtent

      public Envelope getExtent()
      Returns the extent that the table represents, this can be used to determine the extent within which data can be edited. ServiceFeatureTables in manual cache mode will return the extent of the features which have been cached, all other modes will return the extent of the layer/table defined by the service (from ArcGISFeatureLayerInfo.getExtent().
      Overrides:
      getExtent in class FeatureTable
      Returns:
      the extent
      Since:
      100.0.0
      See Also:

    • getFeatureRequestMode

      public ServiceFeatureTable.FeatureRequestMode getFeatureRequestMode()
      Gets the feature request mode, which defines when features and non-spatial records are requested from the feature service.

      The default mode is ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE.

      Returns:
      the feature request mode
      Since:
      100.0.0
      See Also:

    • setFeatureRequestMode

      public void setFeatureRequestMode(ServiceFeatureTable.FeatureRequestMode featureRequestMode)
      Sets the feature request mode, which defines when features and non-spatial records are requested from the feature service.
      Parameters:
      featureRequestMode - the feature request mode
      Throws:
      IllegalArgumentException - if the input is null
      Since:
      100.0.0
      See Also:

    • applyEditsAsync

      public ListenableFuture<List<FeatureEditResult>> applyEditsAsync()
      Applies edits that have been added to this table including attachment edits in one call. This returns edit results for each feature, each result includes attachment results for that feature.

      Uploads any changes to the local table to the feature service.

      ServiceFeatureTable.applyEditsAsync() is meant to be used for single table workflows or tables without geodatabase behavior (see below). If an edit on this table can cause an edit to another table due to geodatabase behavior, it is highly recommended to use ServiceGeodatabase.applyEditsAsync() instead to prevent data inconsistency, so that dependent edits are all applied or none are (if an error occurs).

      For example, when tables have a composite relationship, applying the delete of a destination feature in a composite relationship deletion will only delete the destination feature on the server, therefore causing inconsistency in the data.

      Areas which have geodatabase behavior:

      • Composite relationships
      • Annotation feature layers
      • Utility network association deletion semantics
      • Attribute rules
      Returns:
      a ListenableFuture representing the resulting list of edit results and indicating if the operation isDone(); also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to IOException if a network request fails
      Since:
      100.0.0

    • clearCache

      public void clearCache(boolean keepLocalEdits)
      Clears all the features in the local table. Caches will only exist in certain modes.
      Parameters:
      keepLocalEdits - true if you need to retain edits in the local cache
      Since:
      100.0.0

    • populateFromServiceAsync

      public ListenableFuture<FeatureQueryResult> populateFromServiceAsync(QueryParameters query, boolean clearCache, Iterable<String> outFields)
      Queries the feature service and places the resulting features in the local table, which is cached for the duration of the session. The ServiceFeatureTable must have its ServiceFeatureTable.FeatureRequestMode set to ServiceFeatureTable.FeatureRequestMode.MANUAL_CACHE.

      This method is useful for non-geographic data. It's also helpful when you want to avoid accessing the service for a feature whose geometry is in the current extent of the map or scene.

      Specifying null or an empty List for outfields results in the minimum set of fields being used to populate the local table. This is the same set of fields described for ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE or ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_NO_CACHE.

      Parameters:
      query - options for controlling the operation
      clearCache - true, if you want to clear the local cache before populating the local table. False, if you want to append the features to the local table.
      outFields - each string is the name of a field to be used when populating the cache. If the iterable contains the single element "*", then all fields will be used. If the ObjectID field string name is not provided as part of the iterable, no features will be returned for this method.
      Returns:
      a ListenableFuture represents the result of the query; the results will replace or be appended to this table. The ListenableFuture indicates if the query isDone(); also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to IOException if a network request fails
      Throws:
      IllegalArgumentException - if the input is null
      ArcGISRuntimeException - if the query execution failed
      IllegalStateException - if the feature request mode is not MANUAL_CACHE
      Since:
      100.0.0

    • queryFeaturesAsync

      public ListenableFuture<FeatureQueryResult> queryFeaturesAsync(QueryParameters query)
      Asynchronously queries features from this table's cache and/or from the service used to create this table. If the FeatureRequestMode is MANUAL_CACHE then the query will always be performed locally. If the FeatureRequestMode is ON_INTERACTION_CACHE then queries that contain geometries which are within an extent that has been cached will be performed locally, otherwise they will be performed on the server. If the FeatureRequestMode is ON_INTERACTION_NOCACHE the query will always be performed on the server.
      Overrides:
      queryFeaturesAsync in class FeatureTable
      Parameters:
      query - query parameters to be used
      Returns:
      a ListenableFuture represents the result of the query. The ListenableFuture indicates if the query isDone(); also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to IOException if a network request fails
      Throws:
      ArcGISRuntimeException - if the query execution failed
      Since:
      100.0.0

    • queryFeaturesAsync

      public ListenableFuture<FeatureQueryResult> queryFeaturesAsync(QueryParameters queryParameters, ServiceFeatureTable.QueryFeatureFields queryFields)
      Asynchronously queries features from this table's cache and/or from the feature service used to create this table.

      If the request mode of the table is ServiceFeatureTable.FeatureRequestMode.MANUAL_CACHE, then the query is always performed on the local table.

      If the mode is ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_CACHE, then the query is performed on the local cache, provided that the geometries of the features are within an extent that has been cached; otherwise, the query is performed on the server.

      If the mode is ServiceFeatureTable.FeatureRequestMode.ON_INTERACTION_NO_CACHE, the query is always performed on the server.

      The ServiceFeatureTable.QueryFeatureFields constants control which fields will be included with the returned features. The options are:

      Note that you can query any attribute defined by the feature service's table. If the attribute is not in the set of attributes in your local table, the query will be performed on the server.

      Parameters:
      queryParameters - options for controlling the operation.
      queryFields - options for controlling what fields are in the features of the query result
      Returns:
      a ListenableFuture representing the result of the query. The ListenableFuture indicates if the query operation isDone(); also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to IOException if a network request fails
      Throws:
      IllegalArgumentException - if the queryParameters or queryFields are null
      Since:
      100.0.0

    • queryRelatedFeaturesAsync

      public ListenableFuture<List<RelatedFeatureQueryResult>> queryRelatedFeaturesAsync(ArcGISFeature feature, RelatedQueryParameters relatedQueryParameters, ServiceFeatureTable.QueryFeatureFields queryFields)
      Queries for related features in this service feature table using the provided parameters and query feature fields. See queryFeaturesAsync(QueryParameters, QueryFeatureFields) for more details.
      Parameters:
      feature - feature for which to query related features
      relatedQueryParameters - related query parameters to be used
      queryFields - enumeration indicating which fields to return from the query
      Returns:
      a ListenableFuture representing the resulting list of RelatedFeatureQueryResults and indicating if the query operation isDone(); also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to IOException if a network request fails
      Throws:
      IllegalArgumentException - if the feature, relatedQueryParameters, or queryFields are null
      Since:
      100.1.0

    • setDefinitionExpression

      public void setDefinitionExpression(String definitionExpression)
      Sets an expression (SQL where clause) to filter features queried in this table.

      The definition expression string uses the SQL-92 where clause syntax (https://en.wikipedia.org/wiki/SQL-92). Be sure to escape special characters in the expression string as required for your platform. The DATE keyword expects the date format yyyy-mm-dd and the TIMESTAMP keyword expects the time stamp format yyyy-mm-dd hh:mm:ss. For more information, see the ArcGIS Blog article Querying Feature Services Date-Time Queries.

      Parameters:
      definitionExpression - an expression (SQL where clause) to filter features queried in this table
      Since:
      100.2.0
      See Also:

    • getDefinitionExpression

      public String getDefinitionExpression()
      Gets an expression (SQL where clause) to filter features queried in this table.
      Returns:
      the definition expression for filtering the features queried in this table; or empty if it is set to null
      Since:
      100.2.0
      See Also:

    • getGeodatabaseVersion

      public String getGeodatabaseVersion()
      Gets the service geodatabase version name.

      This property is populated if the ServiceFeatureTable is provided by a layer or a table in a web map or if the ServiceFeatureTable is created using ServiceGeodatabase.getTable(long).

      The default geodatabase version has the string value "sde.DEFAULT".

      Returns:
      the service geodatabase version name
      Since:
      100.3.0

    • setGeodatabaseVersion

      public void setGeodatabaseVersion(String version)
      Sets the service geodatabase version name.
      Parameters:
      version - the service geodatabase version name
      Since:
      100.3.0

    • getItem

      public Item getItem()
      Gets the item associated with this table.
      Returns:
      the associated item or null if there is no associated item
      Since:
      100.3.0
      See Also:

    • undoLocalEditsAsync

      public ListenableFuture<Void> undoLocalEditsAsync()
      Undoes all of the local edits since the last server acknowledgement.

      The ServiceFeatureTable.undoLocalEditsAsync() method is meant to be used for single table workflows or tables without geodatabase behavior (see below). If the service which the table belongs to has geodatabase behavior (see below), it is highly recommended to to use ServiceGeodatabase.undoLocalEditsAsync(). Undoing edits in one table can cause data inconsistencies between the local cache and the service if ServiceFeatureTable.undoLocalEditsAsync() is used.

      For example, when tables have a composite relationship, undoing only the origin feature would violate the composite relationship rule that an origin and destination feature must be either deleted together or not at all.

      Areas which have geodatabase behavior:

      • Composite relationships
      • Annotation feature layers
      • Utility network association deletion semantics
      • Attribute rules
      Returns:
      a ListenableFuture to undo all of the local edits asynchronously. Add a listener to the Future to know when the task is done.
      Since:
      100.3.0

    • loadOrRefreshFeaturesAsync

      public ListenableFuture<Void> loadOrRefreshFeaturesAsync(Iterable<Feature> features)
      Loads all attributes and geometries for features that have not been loaded and fetches attributes and geometries for previously loaded features.

      Features returned from queryFeaturesAsync(QueryParameters, QueryFeatureFields) or queryRelatedFeaturesAsync(ArcGISFeature, RelatedQueryParameters, QueryFeatureFields) may be in the minimally loaded state (minimum attributes required for rendering and no m-values). To load all attributes, pass an Iterable of the features to this method.

      Any feature requested, but not returned, by the server will have its object id cleared (set to an invalid negative value) to indicate it is no longer associated with the service feature table.

      After calling this method, any non-applied edits on the table will be lost.

      This method will not refresh feature attachments. Use ArcGISFeature.fetchAttachmentsAsync() to retrieve attachments.

      All features loaded or refreshed by this method will have m-values if defined by the service. Note that an m-value may be NaN.

      Parameters:
      features - the features to be loaded or refreshed
      Returns:
      a ListenableFuture to reload or refetch the features asynchronously. Add a listener to the Future to know when the task is done.
      Throws:
      IllegalArgumentException - if features is null
      Since:
      100.3.0

    • getServiceGeodatabase

      public ServiceGeodatabase getServiceGeodatabase()
      Gets the ServiceGeodatabase this service feature table is part of.

      This property is populated if the ServiceFeatureTable is provided by a layer or a table in a web map or if the ServiceFeatureTable is created using ServiceGeodatabase.getTable(long).

      Returns:
      the ServiceGeodatabase this service feature table is part of, or null
      Since:
      100.9.0

    • getApiKey

      public String getApiKey()
      Description copied from interface: ApiKeyResource
      Gets the API key to access API key enabled services and resources in ArcGIS Online.

      An API key is a unique long-lived access token that is used to authenticate and monitor requests to ArcGIS location services and private portal items. You can create and manage an API key using your portal when you sign in with an ArcGIS Location Platform account or an ArcGIS Online account with administrator access or a custom role that has the Generate API keys privilege. To learn how to create and manage API keys, go to the Create an API Key tutorial. You must ensure that your API key has the correct privileges to access secure resources.

      In addition to setting an API key at a global level for your application using ArcGISRuntimeEnvironment.setApiKey(String), you can call ApiKeyResource.setApiKey(String) on any class that implements ApiKeyResource. When you call setApiKey(String) on an APIKeyResource, it will override the default key at the global level (the key returned by ArcGISRuntimeEnvironment.getApiKey(), in other words), enabling more granular usage telemetry and management for ArcGIS Online resources used by your app.

      Classes that expose an API key property by implementing APIKeyResource include:

      Specified by:
      getApiKey in interface ApiKeyResource
      Returns:
      the API key to access API key enabled services and resources in ArcGIS Online
      See Also:

    • setApiKey

      public void setApiKey(String apiKey)
      Description copied from interface: ApiKeyResource
      Sets the API key to access API key enabled services and resources in ArcGIS Online.

      An API key is a unique key used to authorize access to specific services and resources in ArcGIS Online. It is also used to monitor access to those services. An API key is created and managed in the ArcGIS developer dashboard and is tied to a specific ArcGIS account.

      In addition to setting an API key at a global level for your application using ArcGISRuntimeEnvironment.setApiKey(String), you can call setApiKey(String) on any class that implements ApiKeyResource. When you call setApiKey(String) on an APIKeyResource, it will override the default key at the global level (the key returned by ArcGISRuntimeEnvironment.getApiKey(), in other words), enabling more granular usage telemetry and management for ArcGIS Online resources used by your app.

      Classes that expose an API key property by implementing APIKeyResource include:

      Specified by:
      setApiKey in interface ApiKeyResource
      Parameters:
      apiKey - the API key to access API key enabled services and resources in ArcGIS Online
      See Also: