Find text in the map

Using the find operation, you can search an ArcGIS map service for features with attribute values that match or contain some piece of text. You can also limit the search to features in specific layers or to text in specific feature attributes. A search of this type returns a list of results for the search text provided. For each result, you can obtain the attribute value that matched the search text, the ID of the layer containing the matching feature, as well as the matching feature's ID, geometry, and full set of attributes. Use the API's FindTask class to perform this type of search in your Java applications.

A layer in a map service can be of two types: a feature layer or a raster layer. A feature layer stores geographic data in the form of shapes or vectors. A raster layer stores data in the form of imagery. The find operation works with a map service's feature layers and raster layers. However, the find operation does not query simple tables that store only attribute data and does not query feature services.

When retrieving features, you can specify an output spatial reference if you want the feature geometries to be projected into a different coordinate system. This is useful, for example, if the service's spatial reference is different from the spatial reference of the map on which you want to display the result features.

See the Find REST specification for a complete description of the input and output options of the find operation.

Use the FindTask class

To find text in a map, complete the following steps:

  1. Instantiate the FindTask class and provide the URL of the online or local service to the task's constructor.
  2. Specify the input parameters to the task.
  3. Execute the task synchronously or asynchronously.
  4. Listen for the completion of the task and process the results.

These steps are explained in further detail below.

Instantiate the FindTask class

Construct the FindTask class passing the URL of the local or online map service to be queried, and optionally user credentials if the map service is secured.

// create a FindTask with an unsecured (public) map service
FindTask findTask = new FindTask(
   "http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/"
   + "Specialty/ESRI_StatesCitiesRivers_USA/MapServer");
// provide UserCredentials as a second parameter in the constructor for a secured service

Specify the input parameters

You can define your query by setting various parameters on the FindParameters class. The FindParameters class will then be used as input to the find task when it's executed. The following are some basic guidelines:

  • Call the setSearchText() method and provide the text you want to find.
  • Call the setOutputSpatialRef() method to return geometries in the spatial reference of your map rather than the spatial reference of the queried map service.
  • Call the setLayerIds() method to restrict the search to the layers you specify.
  • Call the setSearchFields() method to restrict the search to the fields you specify.

// create a parameters instance and set some properties
FindParameters params = new FindParameters();
// e.g. retrieve search text from a text UI component
params.setSearchText(findText.getText());
// use the current JMap's spatial reference
params.setOutputSpatialRef(map.getSpatialReference());
// search only layer '0'
params.setLayerIds(new int[]{0});
// search only the named field below
params.setSearchFields(new String[]{"STATE_NAME"});

Execute the task

Execute the FindTask asynchronously or synchronously. If you execute the task asynchronously, the application will remain responsive during the execution of the task. This is the recommended method of execution for most find operations. If you execute the task synchronously (on the application thread), the application will be paused while the task is executing. This method of execution is only recommended if the find task is reliably fast and the result list is small.

Asynchronous execution

Execute a find task asynchronously using the executeAsync method, with the previously defined FindParameters class as input. You also need to define a CallbackListener into which the results will be passed as a list of FindResults. The code inside the callback listener is executed when the find task completes or throws an error.

findTask.executeAsync(params, new CallbackListener<List<FindResult>>() {
			
  @Override
  public void onError(Throwable e) {
    // handle the error as desired
  }
			
  @Override
  public void onCallback(List<FindResult> results) {
    // check the results
    if ((results == null) || results.isEmpty()) {
      System.out.println("There are no records returned");
      return;
    } 
    // process each FindResult
    ...
  }
});

Synchronous execution

Execute a find task synchronously using the execute method, with the previously defined FindParameters class as input. The result of the find task will be a list of FindResults that you can process further.

List<FindResult> findResults = findTask.execute(params); 
 
// check the results
if ((findResults == null) || findResults.isEmpty()){
  System.out.println("There are no records returned");   
  return;
} 

// process each FindResult
...

Process the results

The results of the find task are returned in a list of FindResults containing attributes and, by default, geometries. If you specified that there will be no geometry returned (using setReturnGeometry(false)), then findResult.getGeometry() and findResult.getGeometryType() will return null. Process the contents of the list of FindResults as in the following code sample:

// process each find result
for (FindResult findResult : findResults) {
  // check the geometry type
  if (null != findResult.getGeometryType() && Type.POINT == findResult.getGeometryType()){
    Geometry geometry = findResult.getGeometry(); 
    if (null != geometry){
      // display the geometry in a GraphicsLayer
      graphicsLayer.addGraphic(
        new Graphic(geometry, new SimpleMarkerSymbol(Color.RED, 8, Style.DIAMOND)));
    }
  }        
}

Sample code

To view any samples related to searching data, launch the ArcGIS Runtime SDK for Java sample viewer application installed with ArcGIS Runtime SDK for Java. Samples include an interactive find task sample complete with the source code in the Search section.