Edit features

You can let users edit features while online (connected) or offline (disconnected). Editing includes adding new features, deleting features, and updating existing features by changing their geometry (location or shape), attributes, or attachments. There are two models for editing features: feature table editing and feature layer editing. This topic focuses on feature table editing. For an introduction to editing and the editing models, see Editing.

Whether you are online or offline, the workflow to edit features is similar. In both cases, you need to do the following:

  1. Create a feature table—In a connected workflow, create it from a feature service. In a disconnected workflow, create it from a geodatabase you generated with a sync-enabled feature service before you went offline, as described in Create an offline map.
  2. Create a feature layer from the feature table and add the layer to the map.
  3. Perform any edits against the feature table (add, update, and delete features and feature attachments).
  4. Commit your edits—In a connected workflow, apply any edits you make to the feature service right away. In a disconnected workflow, sync all your edits back to the service once you have a network connection, as described in Sync offline edits.

In a connected workflow, the type of feature table you create and edit is a GeodatabaseFeatureServiceTable. In a disconnected workflow, the type of feature table you create and edit is a GeodatabaseFeatureTable. The class hierarchy between these is as follows:

FeatureTable UML diagram

The methods to add, update, and delete features and feature attachments are common to FeatureTable and GeodatabaseFeatureTable. Therefore, all the methods you have at your disposal to edit in an offline workflow are also available for an online workflow, since GeodatabaseFeatureServiceTable inherits GeodatabaseFeatureTable. The GeodatabaseFeatureServiceTable used in connected editing provides additional methods to apply feature edits and attachment edits back to the service. You should apply any edits to the service as soon as you have made them on your feature table.

To update or delete features, your app should enable users to select features on the map, as described below in Select features.

Create a feature table

Before you can edit features, you need to obtain feature data from a feature service. In an online workflow, create a feature table from a feature service right before you want to edit features, for example, on application load. In an offline workflow, generate a geodatabase from a sync-enabled feature service while you have a network connection, in preparation for editing features offline. When offline, create feature tables from the geodatabase to edit the features locally. In both cases, check the capabilities of the feature service to ensure the editing capability is available.

Online

In an online workflow, create a geodatabase feature service table from a feature service. You can then create a feature layer using this feature table. Once you add the feature layer to a map, features in the map extent are added to the feature service table and can be edited. As you pan and zoom the map (that is, change the map extent), more features are retrieved from the feature service and added to the geodatabase feature service table.

Note:

The number of features you see when you initially visit a new area of the map is limited by the feature service's MaxRecordCount property (the default value for this property is 1,000). Pan and zoom to query the service for more features. Once features are retrieved from the service and visible in your map, they are available in your geodatabase feature service table for editing and querying.

featureServiceTable = 
  new GeodatabaseFeatureServiceTable(FEATURE_SERVICE_URL, LAYER_ID);
// you can set the spatial reference of the table here
// if not set, the service's spatial reference will be used
featureServiceTable.setSpatialReference(SpatialReference.create(102100));

// initialize the table asynchronously
featureServiceTable.initialize(
  new CallbackListener<GeodatabaseFeatureServiceTable.Status>() {

  @Override
  public void onError(Throwable e) {
    // report/handle error as desired
    System.out.println(featureServiceTable.getInitializationError());
  }

  @Override
  public void onCallback(Status status) {
    if (status == Status.INITIALIZED) {
      // ...create a FeatureLayer from the GeodatabaseFeatureServiceTable...
    }
  }
});

As shown above, once you create a GeodatabaseFeatureServiceTable instance, you can set the table's spatial reference by calling setSpatialReference. This must be done before you call the initialize method on the table. If you do not explicitly set the spatial reference of the table this way, the spatial reference of the service will be used. However, if your map is in a difference spatial reference than your GeodatabaseFeatureServiceTable, your features will not appear on the map, so it is good practice to always set the spatial reference explicitly.

You can set your table's spatial reference to the spatial reference of your map once the map is initialized by setting an OnStatusChanged callback on the MapView:

map.setOnStatusChangedListener(new OnStatusChangedListener() {
  private static final long serialVersionUID = 1L;
  @Override
  public void onStatusChanged(Object source, STATUS status) {
    if(source == map && STATUS.INITIALIZED == status) {
      SpatialReference mapSR = event.getMap().getSpatialReference();
      featureServiceTable = new GeodatabaseFeatureServiceTable(FEATURE_SERVICE_URL, LAYER_ID);
      // set the table's spatial reference to be the same as the map's
      featureServiceTable.setSpatialReference(mapSR);
      // ...initialize GeodatabaseFeatureServiceTable...
    }
  }
});

Offline

In an offline workflow, generate a geodatabase from a sync-enabled feature service while you have a network connection. Follow the geodatabase generation process described in Create an offline map. This process results in a geodatabase stored locally on disk. The geodatabase contains one or more feature tables, one for each service layer or service table that you requested in the geodatabase generation process. When offline, create geodatabase feature tables (GeodatabaseFeatureTable class) from the geodatabase, for example, on application load. The features in the geodatabase feature tables are available for editing whether you create a feature layer or not, but in most cases you'll want to create a feature layer from the feature tables to display the features on a map. Also, consider generating an offline basemap to give the feature data some geographical context when your users edit offline, as described in Include a basemap.

The following code sample shows how to create a feature table from a local geodatabase:

// Open the local geodatabase file
Geodatabase geodatabase = new Geodatabase(PATH_TO_GEODATABASE);

// Get the feature table created from the service layer specified in 'LAYER_ID'
GeodatabaseFeatureTable geodatabaseFeatureTable = geodatabase.getGeodatabaseFeatureTableByLayerId(LAYER_ID);

// Create a FeatureLayer from the GeodatabaseFeatureTable and then use the layer...

Note:

The Geodatabase constructor used above throws a FileNotFoundException if the geodatabase file cannot be found. You must surround this line with a try-catch block, if the surrounding method itself does not declare that it throws this exception.

Add layers to the map

Display the features contained in the feature table in a map so your users can view and edit them. Create a feature layer from the feature table and add the layer to a map. The feature layer, once added to a map, takes care of displaying the features contained in your feature table that fall within the map extent displayed. When you make edits to features in the table, these edits are visible right away in the associated feature layer and map, but not yet committed back to the service.

The following code sample shows how to create a feature layer from a feature table:

private Geodatabase geodatabase = null;
private GeodatabaseFeatureTable geodatabaseFeatureTable;
private FeatureLayer featureLayer;

//open the local geodatabase file
geodatabase = new Geodatabase(PATH_TO_GEODATABASE);

//open the layer in the geodatabase created from the service layer specified in 'LAYER_ID'
geodatabaseFeatureTable =  geodatabase.getGeodatabaseFeatureTableByLayerId(LAYER_ID);

//create a feature layer and add it to the map
featureLayer = new FeatureLayer(geodatabaseFeatureTable);        
map.addLayer(featureLayer);

Add features

To add or insert new features into a geodatabase table, create the geometry (for example, point, line, or polygon) and attributes for the new feature, and then call the addFeature method. This method returns the unique feature ID of the added feature, which you can store for later use, such as if you want to modify the geometry or attributes of this particular feature later on. Adding a feature to a geodatabase table is shown in the code below:

//make a map of attributes
Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("TYPDAMAGE", "Minor");
attributes.put("PRIMCAUSE" , "Earthquake");
attributes.put("TYPDAMAGE_INT", new Integer(3));

try {
  //Create a feature with these attributes at the given point
  GeodatabaseFeature gdbFeature = new GeodatabaseFeature(attributes, point, geodatabaseFeatureTable);

  //Add the feature into the geodatabase table returning the new feature ID
  long fid = geodatabaseFeatureTable.addFeature(gdbFeature);

  String geomStr = geodatabaseFeatureTable.getFeature(fid).getGeometry().toString();
  Log.d(TAG, "added fid = " + fid + " " + geomStr);
} catch (TableException e) {
  // report errors, e.g. to console
  Log.e(TAG, "", e);
}

Update features

Features can be updated with the updateFeature method on the GeodatabaseFeatureTable.

The code sample below shows a method that updates a point feature in the geodatabase feature table with a new point geometry, changing its location on the map.

public void updateFeature(long featureID, Point newLocation) {
  try {
    //calls the API method updateFeature taking a feature ID and the new geometry
    gdbFeatureTable.updateFeature(featureID, newLocation);
  } catch (TableException e) {
    // report/handle exception
    Log.e(TAG, "", e);
  }
}

Delete features

Features are deleted using the unique ID of the feature you want to delete. This unique ID can be stored when you add a feature to a geodatabase table or can be obtained, for example, through a query on the table. If you have selected the features to delete, the following line of code removes them from the layer:

geodatabaseFeatureTable.deleteFeatures(featureLayer.getSelectionIDs());

Select features

In a typical map application involving editing, users should be able to select features to edit. You can programmatically select features in a feature layer using their unique IDs. You can obtain feature IDs by performing a query on the feature table from which the feature layer was created, or by letting your users tap the map and obtain the IDs of any features within a certain pixel tolerance around the tapped point. The following code sample shows how to use a single tap event listener on the map to select tapped features:

mMapView.setOnSingleTapListener(new OnSingleTapListener() {
  private static final long serialVersionUID = 1L;

  public void onSingleTap(float x, float y) {
    // gets the first 1000 features at the clicked point on the map, within 5 pixels
    long[] selectedFeatures = featureLayer.getFeatureIDs(x, y, 5, 1000);
    // select the features
    featureLayer.selectFeatures(selectedFeatures, false);
  }
}

Commit your edits

Committing your feature table edits to the feature service is different depending on whether your workflow is fully connected or disconnected.

Online

In a fully connected workflow, you should apply feature edits and attachment edits back to the service as you make them. That way, anyone else using the same feature service will have access to your changes right away.

To commit your local feature edits to the service, call the applyEdits method. Optionally, you can list the current locally edited features by using getAddedFeatures(), getUpdatedFeatures(), and getDeletedFeatures(). Changes to the features returned by those three methods will be committed to the service on a call to applyEdits. 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 passing the locally held object ID to the method lookupObjectID, before calling applyEdits. The applyEdits method is asynchronous; any errors from this method call will be returned in a callback as a list of GeodatabaseEditError objects.

To commit your local feature attachment edits to the service, call the applyAttachmentEdits method. A feature needs to exist on the server before attachment edits for this feature can be applied. Generally, you should call applyAttachmentEdits after a successful call to applyEdits. The applyAttachmentEdits method is asynchronous; any errors from this method call will be returned in a callback as a list of GeodatabaseEditError objects.

Note:

For descriptions of errors that can arise during edit commits, go to the Apply Edits (Feature Service) topic and click the error code link in the Description section.

Offline

In a disconnected workflow, commit all edits back to the service, and optionally pull the latest changes from the service back to your geodatabase through a sync operation, as described in Sync offline edits. Syncing requires a network connection; therefore, do this when you are back online. Note that the edits that are last committed to the service will overwrite previously committed edits, even if committed edits were made at a later time.

Related topics