public class

GeodatabaseFeatureServiceTable

extends GeodatabaseFeatureTable
java.lang.Object
   ↳ com.esri.core.table.FeatureTable
     ↳ com.esri.core.geodatabase.GeodatabaseFeatureTable
       ↳ com.esri.core.geodatabase.GeodatabaseFeatureServiceTable

Class Overview

Represents a feature table created from an ArcGIS service.

To display features from a feature service, first create a GeodatabaseFeatureServiceTable from a service URL, layer ID, and optionally credentials (for a secure service). If the feature service is in a difference spatial reference to the map you want to display features in, you must set the spatial reference for the table to match the map by calling setSpatialReference. Then, initialize the table using the initialize method (synchronous or asynchronous version). In Android, ensure you call the synchronous initialize method on a background thread. When the initialization is complete, check the GeodatabaseFeatureServiceTable.Status returned. You can check for initialization errors using getInitializationError().

Once you have a successfully initialized GeodatabaseFeatureServiceTable, use it to create an online FeatureLayer if it's a spatial table, i.e. hasGeometry() returns true.

Edit a feature's attributes, geometry, and attachments using the methods on GeodatabaseFeatureTable. Additionally you must call applyEdits and applyAttachmentEdits to commit your changes to the associated service.

When you are done using the feature service table, call its dispose() method to release native resources and clean up any temporary files on the machine, otherwise temporary files used by the table may be left behind on disk.

The GeodatabaseFeatureServiceTable currently does not support:

  • time aware data (you can use ArcGISFeatureLayer if you require this functionality)
  • editing relationships (you can edit records that are related but you cannot add, edit or remove relationships, foreign keys are not maintained)

The geometry of added or updated features must lie within the extent of the table. If using wrap around maps, geometries created from the map should be normalized before being used as feature geometry, by calling normalizeCentralMeridian(Geometry, SpatialReference).

Summary

Nested Classes
enum GeodatabaseFeatureServiceTable.FeatureRequestMode Defines modes that determine how the table is populated with features and whether they are cached or not. 
enum GeodatabaseFeatureServiceTable.Status Represents the initialization status. 
Fields
protected UserCredentials credentials
Public Constructors
GeodatabaseFeatureServiceTable(String url, int layerId)
Instantiates a new geodatabase feature service table from a URL and layer ID.
GeodatabaseFeatureServiceTable(String url, UserCredentials credentials, int layerId)
Instantiates a new geodatabase feature service table from a secure service URL, layer ID, and credentials for the secure service.
Public Methods
Future<List<GeodatabaseEditError>> applyAttachmentEdits(CallbackListener<List<GeodatabaseEditError>> callback)
Applies attachment edits (adds, updates and deletes) to the server.
Future<List<GeodatabaseEditError>> applyEdits(CallbackListener<List<GeodatabaseEditError>> callback)
Applies any local feature edits to the server.
void clearCache()
Deletes all features stored locally in this table, including edited features.
void dispose()
Releases native resources and cleans up any temporary files on disk created by the table.
Future<Void> fetchFeatures(long[] existingIds, double[] extent, double scale)
For internal use only.
double getBufferFactor()
Gets the buffer factor used when the table is displayed in a FeatureLayer.
String getDefinitionExpression()
Gets the definition expression used to fetch features on map interaction.
Envelope getExtent()
Returns the extent of the GeodatabaseFeatureServiceTable.
GeodatabaseFeatureServiceTable.FeatureRequestMode getFeatureRequestMode()
String getInitializationError()
Returns an error message if an exception occured during initialization; returns null if no error occured.
String[] getOutFields()
Gets the array of field names to include in the feature query used to fetch features on map interaction.
String getServiceUrl()
Gets the service URL including the service layer ID.
SpatialReference getSpatialReference()
(non-Javadoc)
GeodatabaseFeatureServiceTable.Status getStatus()
Gets the initialization status.
GeodatabaseFeatureServiceTable.Status initialize()
Initializes the table synchronously.
Future<GeodatabaseFeatureServiceTable.Status> initialize(CallbackListener<GeodatabaseFeatureServiceTable.Status> callback)
Initializes the table asynchronously.
boolean isUsingAdvancedSymbols()
Returns whether or not features are being rendered with advanced symbology.
long lookupObjectID(long oid)
Looks up the new object ID of a feature after a successful call to applyEdits(CallbackListener>).
Future<Boolean> populateFromService(QueryParameters query, boolean clearCache, CallbackListener<Boolean> callback)
Asynchronously populates the table with features based on the specified query that is sent to the feature service.
Future<List<AttachmentInfo>> queryAttachmentInfos(long featureId, CallbackListener<List<AttachmentInfo>> callback)
Query attachment information for the given feature ID.
Future<FeatureResult> queryFeatures(QueryParameters query, CallbackListener<FeatureResult> callback)
Executes a feature query and returns an iterator of features as a result of the query.
Future<long[]> queryIds(QueryParameters query, CallbackListener<long[]> callback)
Executes a feature query and returns an array of object ids that correspond to the features that have been queried.
Future<Map<Long, FeatureResult>> queryRelated(RelatedQueryParameters relatedQuery, CallbackListener<Map<Long, FeatureResult>> callback)
Performs a query to fetch related records.
void refreshFeatures()
Removes all features stored locally in this table, including edited features.
Future<InputStream> retrieveAttachment(long featureId, long attachmentId, CallbackListener<InputStream> callback)
Retrieves the attachment with the specified ID from the specified feature.
void setBufferFactor(double bufferFactor)
Sets the buffer factor used when the table is displayed in a FeatureLayer.
void setDefinitionExpression(String expression)
Sets the definition expression used to fetch features on map interaction.
void setFeatureRequestMode(GeodatabaseFeatureServiceTable.FeatureRequestMode featureRequestMode)
void setOutFields(String[] outFields)
Sets an array of field names to include in the feature query used to fetch features on map interaction.
void setSpatialReference(SpatialReference spatialReference)
Use this method if you want the features in the table to use a spatial reference different from the originating feature service.
void setUsingAdvancedSymbols(boolean useAdvancedSymbols)
Used to set whether or not features should be rendered using advanced symbology.
Protected Methods
void finalize()
List<Map<String, Object>> getAddedAttachments()
List<Map<String, Object>> getDeletedAttachments()
List<Map<String, Object>> getUpdatedAttachments()
[Expand]
Inherited Methods
From class com.esri.core.geodatabase.GeodatabaseFeatureTable
From class com.esri.core.table.FeatureTable
From class java.lang.Object

Fields

protected UserCredentials credentials

Public Constructors

public GeodatabaseFeatureServiceTable (String url, int layerId)

Instantiates a new geodatabase feature service table from a URL and layer ID.

Parameters
url String: the service URL
layerId int: the layer ID

public GeodatabaseFeatureServiceTable (String url, UserCredentials credentials, int layerId)

Instantiates a new geodatabase feature service table from a secure service URL, layer ID, and credentials for the secure service.

Parameters
url String: the service URL
credentials UserCredentials: the credentials to access the service
layerId int: the layer ID

Public Methods

public Future<List<GeodatabaseEditError>> applyAttachmentEdits (CallbackListener<List<GeodatabaseEditError>> callback)

Applies attachment edits (adds, updates and deletes) to the server. The feature needs to exist on the server before attachment edits can be applied. Generally, this call should be made after a successful call to applyEdits(CallbackListener). Once the edits have been applied, attachments will be given a server generated ID. You can find all the attachment IDs by calling queryAttachmentInfos(long). If an exception occurs during the upload e.g. network failure then all the edits will be regarded as failed and will need to be resubmitted by calling the method again. In this case an empty list of GeodatabaseEditErrors will be returned as the entire upload has failed.

Parameters
callback CallbackListener: the callback with a list of edit errors
Returns
Future<List<GeodatabaseEditError>> the future

public Future<List<GeodatabaseEditError>> applyEdits (CallbackListener<List<GeodatabaseEditError>> callback)

Applies any local feature edits to the server. Current locally edited features can be listed using getAddedFeatures(), getUpdatedFeatures(), and getDeletedFeatures(). Once the edits have been applied, newly added features will be given the server generated object ID. You can find out the value of the new object ID by calling lookupObjectID(long). If an exception occurs during the upload, e.g. network failure, then all the edits will be regarded as failed and will need to be resubmitted by calling the method again. In this case an empty list of GeodatabaseEditErrors will be returned as the entire upload has failed.

Parameters
callback CallbackListener: the callback to execute when the edits have been applied to the server
Returns
Future<List<GeodatabaseEditError>> the future

public void clearCache ()

Deletes all features stored locally in this table, including edited features.

public void dispose ()

Releases native resources and cleans up any temporary files on disk created by the table.

Note - you need to call this method when you are done using the table, otherwise temporary files used by the table may be left behind on disk. On Android this needs to be done at an appropriate point in your application's lifecycle, for example your Activity's onDestroy() method.

public Future<Void> fetchFeatures (long[] existingIds, double[] extent, double scale)

For internal use only.

Parameters
existingIds long
extent double
scale double
Returns
Future<Void>
Throws
IllegalArgumentException if the specified extent parameter is invalid (null is a valid value).

public double getBufferFactor ()

Gets the buffer factor used when the table is displayed in a FeatureLayer. The buffered extent is calculated as: width = (bufferFactor > 1) ? extent.width * bufferFactor : extent.width; height = (bufferFactor > 1) ? extent.height * bufferFactor : extent.height;

Returns
double the buffer factor

public String getDefinitionExpression ()

Gets the definition expression used to fetch features on map interaction.

Returns
String the definition expression

public Envelope getExtent ()

Returns the extent of the GeodatabaseFeatureServiceTable. This is the extent defined by the feature service info the table is associated with.

Note: If the spatial reference of the table does not match the spatial reference of the associated service the extent is returned in the spatial reference of the table, not the service.

Returns
Envelope the extent of the GeodatabaseFeatureServiceTable if the status of the table is INITIALIZED, otherwise null

public GeodatabaseFeatureServiceTable.FeatureRequestMode getFeatureRequestMode ()

Gets the GeodatabaseFeatureServiceTable.FeatureRequestMode of the table.

Returns
GeodatabaseFeatureServiceTable.FeatureRequestMode the FeatureRequestMode of the table.

public String getInitializationError ()

Returns an error message if an exception occured during initialization; returns null if no error occured.

Returns
String an initialization error message, or null if no error occured

public String[] getOutFields ()

Gets the array of field names to include in the feature query used to fetch features on map interaction.

Returns
String[] an array of field names.

public String getServiceUrl ()

Gets the service URL including the service layer ID.

Returns
String the service URL

public SpatialReference getSpatialReference ()

(non-Javadoc)

Returns
SpatialReference the spatial reference

public GeodatabaseFeatureServiceTable.Status getStatus ()

Gets the initialization status.

Returns
GeodatabaseFeatureServiceTable.Status the status

public GeodatabaseFeatureServiceTable.Status initialize ()

Initializes the table synchronously. In Android, this method must be called on a background thread.

Returns
GeodatabaseFeatureServiceTable.Status the status

public Future<GeodatabaseFeatureServiceTable.Status> initialize (CallbackListener<GeodatabaseFeatureServiceTable.Status> callback)

Initializes the table asynchronously. Obtain the status from the callback or from the returned Future.

Parameters
callback CallbackListener: the callback
Returns
Future<GeodatabaseFeatureServiceTable.Status> the future

public boolean isUsingAdvancedSymbols ()

Returns whether or not features are being rendered with advanced symbology.

Returns
boolean true if we are rendering features with advanced symbology

public long lookupObjectID (long oid)

Looks up the new object ID of a feature after a successful call to applyEdits(CallbackListener>). The returned ID will either be a new server generated ID or the original ID if the feature has never been added to the server.

Parameters
oid long: the object ID held locally before calling applyEdits(CallbackListener>)
Returns
long the object ID now held in the geodatabase
Throws
IllegalArgumentException if the object ID does not match a feature

public Future<Boolean> populateFromService (QueryParameters query, boolean clearCache, CallbackListener<Boolean> callback)

Asynchronously populates the table with features based on the specified query that is sent to the feature service.

Calling this method is required if the feature request mode of the table is set to MANUAL_CACHE in order to populate the table with features.

Parameters
query QueryParameters: the query that defines what features to fetch from the service. The out spatial reference in the query will be ignored and the spatial reference of the table used instead.
clearCache boolean: if set to true deletes all features from the table (including edited features) upon return of the feature query before the query results are added to the table. If set to false then features already in the table will be overridden, all other features will be appended.
callback CallbackListener: the CallbackListener that gets invoked on return of the query.
Returns
Future<Boolean> a Future that contains a boolean which if set to true, indicates a successful query, otherwise failure.
Throws
IllegalArgumentException if the query parameter is null.
IllegalArgumentException if the query parameter defines a statistics query (see setOutStatistics(OutStatistics[])).
IllegalStateException if the method is called before the table has been initialized.
IllegalStateException if the method is called and the feature request mode is not MANUAL_CACHE.

public Future<List<AttachmentInfo>> queryAttachmentInfos (long featureId, CallbackListener<List<AttachmentInfo>> callback)

Query attachment information for the given feature ID.

Parameters
featureId long: the feature id
callback CallbackListener: the callback
Returns
Future<List<AttachmentInfo>> the future

public Future<FeatureResult> queryFeatures (QueryParameters query, CallbackListener<FeatureResult> callback)

Executes a feature query and returns an iterator of features as a result of the query. The query is executed locally against the table or remotely against the server depending on the following criteria:

  • If the feature request mode is MANUAL_CACHE the query is always executed locally against the table.
  • If the feature request mode is ON_INTERACTION_CACHE then the query is executed locally if it is a spatial query and the geometry is within the current map extent . If the query is executed against the server the results of the query are imported into the table.
  • If the feature request mode is ON_INTERACTION_NO_CACHE the query is always executed remotely against the server. The results of the query are imported into the table, existing features are deleted (including edited features).

Parameters
query QueryParameters: the input query. The out spatial reference in the query will be ignored and the spatial reference of the table used instead.
callback CallbackListener: a CallbackListener that is invoked upon return of the query.
Returns
Future<FeatureResult> a Future that contains the result of the query.
Throws
IllegalStateException if the method is called before the table has been initialized.

public Future<long[]> queryIds (QueryParameters query, CallbackListener<long[]> callback)

Executes a feature query and returns an array of object ids that correspond to the features that have been queried. The query is executed locally against the table or remotely against the server depending on the following criteria:

  • If the feature request mode is MANUAL_CACHE the query is always executed locally against the table.
  • If the feature request mode is ON_INTERACTION_CACHE then the query is executed locally if it is a spatial query and the geometry is within the current map extent . If the query is executed against the server the results of the query are imported into the table.
  • If the feature request mode is ON_INTERACTION_NO_CACHE the query is always executed remotely against the server. The results of the query are imported into the table, existing features are deleted (including edited features).

Parameters
query QueryParameters: the input query. The out spatial reference in the query will be ignored and the spatial reference of the table used instead.
callback CallbackListener: a CallbackListener that is invoked upon return of the query.
Returns
Future<long[]> a Future that contains the object ids that correspond to the features that have been queried.
Throws
IllegalStateException if the method is called before the table has been initialized.

public Future<Map<Long, FeatureResult>> queryRelated (RelatedQueryParameters relatedQuery, CallbackListener<Map<Long, FeatureResult>> callback)

Performs a query to fetch related records. See queryRelated(RelatedQueryParameters, CallbackListener>) for further details.

Note - the related query is performed against the server, local related queries against the table are currently not supported, i.e. even if the feature request mode of the related table is MANUAL_CACHE the query will hit the server.

The results of the query are imported into the related table before being returned. If the feature request mode of the related table is ON_INTERACTION_NO_CACHE existing features (including edited features) are deleted before the new features are imported into the related table.

Parameters
relatedQuery RelatedQueryParameters: query parameters. If the input object id's are not specified, then the result is empty.
callback CallbackListener: the callback to handle any failure and process result.
Returns
Future<Map<Long, FeatureResult>> a map of object id in the source table to features of the related table.
Example:
 
 // get all buildings in a parcel with area of building < 1000
 RelatedQueryParameters relatedQuery = new RelatedQueryParameters();
 relatedQuery.setObjectIds(new long[] {10}); // parcel id = 10
 relatedQuery.setRelationshipId(0); // relationship id from parcel to building = 0
 relatedQuery.setDefinitionExpression("AREA < 1000");
 
 Future<Map<Long, FeatureResult>> resultFuture = 
   featureTable.queryRelated(relatedQuery, new CallbackListener<Map<Long, FeatureResult>>() {
   
  public void onError(Throwable e) {
    e.printStackTrace();
   }
  
  public void onCallback(Map result) {
    ...
  }
 });
 
 Map<Long, FeatureResult> result = resultFuture.get();
 for (Map.Entry<Long, FeatureResult> entry : result.entrySet()) {
   long id = entry.getKey(); // parcel id
   while (Object o : entry.getValue().get()) {
     Feature feature = (Feature) o; // building
     Map<String, Object> attrs = feature.getAttributes();
   }
 }
 
 
Throws
IllegalStateException if the method is called before the table has been initialized.
IllegalStateException if the related table specified by setRelationshipId(int) does not exist. This exception is either thrown out of Future.get() or passed back via CallbackListener.onError().
IllegalStateException if the related table could not be initialized. This exception is either thrown out of Future.get() or passed back via CallbackListener.onError().

public void refreshFeatures ()

Removes all features stored locally in this table, including edited features. If the table is currently used with a FeatureLayer in a map and the table's feature request mode is ON_INTERACTION_CACHE then the table will be refreshed with features re-fetched within the current extent of the map.

public Future<InputStream> retrieveAttachment (long featureId, long attachmentId, CallbackListener<InputStream> callback)

Retrieves the attachment with the specified ID from the specified feature.

Parameters
featureId long: the ID of the feature to retrieve the attachment from
attachmentId long: the ID of the attachment to retrieve
callback CallbackListener: the callback called when the attachment is retrieved
Returns
Future<InputStream> the future can be used to cancel the operation or obtain the result

public void setBufferFactor (double bufferFactor)

Sets the buffer factor used when the table is displayed in a FeatureLayer. The buffered extent is calculated as: width = (bufferFactor > 1) ? extent.width * bufferFactor : extent.width; height = (bufferFactor > 1) ? extent.height * bufferFactor : extent.height;

Parameters
bufferFactor double: the new buffer factor

public void setDefinitionExpression (String expression)

Sets the definition expression used to fetch features on map interaction.

Note: This definition expression is only applied to the internal query that is executed to fetch features on map interaction. It does not get applied to explicit feature queries using {#link #queryFeatures} or {#link #queryIds}.

Parameters
expression String: the new definition expression

public void setFeatureRequestMode (GeodatabaseFeatureServiceTable.FeatureRequestMode featureRequestMode)

Sets the GeodatabaseFeatureServiceTable.FeatureRequestMode of this table.

Note - The feature request mode is determined automatically if its state is UNDEFINED when the table gets initialized. Depending on the type of feature service layer the mode will automatically be set to:

  • ON_INTERACTION_CACHE if the feature service layer represents a spatial table (type "Feature Layer")
  • MANUAL_CACHE if the feature service layer represents a non-spatial table (type "Table")
You can enforce a specific feature request mode by setting it before initialization.

Parameters
featureRequestMode GeodatabaseFeatureServiceTable.FeatureRequestMode: the FeatureRequestMode to be set on the table.
Throws
IllegalStateException if this method is called when the layer has been initialized or errored, i.e. getStatus() returns a status other than UNINITIALIZED.

public void setOutFields (String[] outFields)

Sets an array of field names to include in the feature query used to fetch features on map interaction. If not specified all fields will be queried. The ObjectId field will always be returned, no matter if it is specified in the array of field names or not.

Note: Calling this method only affects the fields of features that are imported into the table as the user interacts with the map. If the user queries features explicitly from the service, using queryFeatures(QueryParameters, CallbackListener) or queryIds(QueryParameters, CallbackListener), the output fields need to be set via setOutFields(String[]).

If the table is added to a FeatureLayer and the renderer of the layer is dependent on some fields, those fields should also be specified in this array. For example, when the layer has a Unique Value Render which is using the value of field "FieldA" to create the symbol of graphics, "FieldA" must be specified in the output field list, otherwise the graphics may not be properly rendered.

Parameters
outFields String: an array of field names.
Throws
IllegalStateException if the method is called before the table has been initialized.

public void setSpatialReference (SpatialReference spatialReference)

Use this method if you want the features in the table to use a spatial reference different from the originating feature service.

Parameters
spatialReference SpatialReference: the spatial reference
Throws
IllegalStateException if this method is called after the table has been initialized.

public void setUsingAdvancedSymbols (boolean useAdvancedSymbols)

Used to set whether or not features should be rendered using advanced symbology. This method should be called before calling initialize().

Parameters
useAdvancedSymbols boolean: set true to render features using advanced symbology

Protected Methods

protected void finalize ()

Throws
Throwable

protected List<Map<String, Object>> getAddedAttachments ()

Returns
List<Map<String, Object>>

protected List<Map<String, Object>> getDeletedAttachments ()

Returns
List<Map<String, Object>>

protected List<Map<String, Object>> getUpdatedAttachments ()

Returns
List<Map<String, Object>>