ArcGIS for Android - Creating new features

There are several steps that are required to add new features to a feature layer using the ArcGIS API for Android. The following includes a summary of the editing workflow along with more detailed information and code snippets to assist you in the creation of editing tools.

What do I need to add new features?

Creating new features involves adding new geometries to a feature layer. To do this, there are various steps that need to be performed. First, you need to provide a tool with which the user can create features, which should create features of the correct geometry type for the layer. If this tool is interactive, it will need to be connected to touch events on the MapView object. If this tool is to use the GPS location for creating or tracing geometries, it will need to integrate with the LocationService class. Once the geometry is created, it can be styled according to the renderers defined in the feature layer. If the feature layer has subtypes or templates, these can be used to set the renderer and also some default attributes. Once the attributes and renderer have been set, the feature will need to be sent to the server using the feature layer's applyEdits() method. More details on these steps can be found below. A geometry editing sample has been created to show you how to do this.

Adding map touch events

It is necessary to add a listener on the MapView object to capture the location for new features and/or their vertices as the user touches the map. For points, this could be a simple OnSingleTapListener; for polygons or lines, this could be MapOnTouchListener (for freehand style drawing) or a more complex OnSingleTapListener that has logic to record when a feature edit has started and finished (maybe via a long click or double tap).

The new feature can be drawn into the graphics layer first, so the user can see the feature as it is being edited (see the draw graphics sample for more information).

If your feature layer has subtypes, templates, or domains defined, it may be useful to display these choices to the user in an Android spinner, dialog box, or view. The default renderer and attributes from a subtype or template can be used for the feature being added, saving the user from having to add this information. The ArcGISFeatureLayer class has some utility methods to help achieve this; see the createFeatureWithType() and createFeatureWithTemplate() methods. A code sample in the section below uses the createFeatureWithTemplate() method.

Applying the edits on the server

Once the feature has been captured, it can be passed to the ArcGISFeatureLayer.applyEdits() method. This asynchronous method can be used to add new features, delete features, and update existing features. Features are added as Graphic objects, which include geometry, attributes, and a renderer. Added graphics are passed in as the first argument. The feature will be given a new ObjectID on the server, so this field is not required for new features. The following method shows this:

/**
 * Adds a new feature using the defined Template;
 */
public void applyAddFeature(Geometry geometry, FeatureTemplate template, ArcGISFeatureLayer featureLayer) {

  //create a graphic using the template
  Graphic graphic = featureLayer.createFeatureWithTemplate(template, geometry);

  featureLayer.applyEdits(new Graphic[] { graphic }, null, null, new CallbackListener<FeatureEditResult[][]>() {
    
    public void onError(Throwable error) {
        // TODO implement error code
    }

    public void onCallback(FeatureEditResult[][] editResult) {
      // Check the response for success or failure
      if (editResult[0] != null && editResult[0][0] != null && editResult[0][0].isSuccess()) {
      // TODO implement success logic
    }
  });
}

A new CallbackListener needs to be created to handle the asynchronous response from the applyEdits() method. The onCallback() method receives a FeatureEditResult[ ][ ] multidimensional array object. This result object contains FeatureEditResult objects for every addition, deletion, and update. In the code above, editResult[0] would provide addition results; editResult[1], deletion results; and editResult[2], update results. FeatureEditResult is returned for every feature edit. The case above expects one result, which would be referenced by the following : editResult[0][0].

The onCallback() method is called even if there is an error with the edits, so you need to add some code like the above to check for success or failure. The onError() method will also fire after this method if there has been an error.

5/31/2012