ArcGIS Runtime SDK for Java - Finding text in the map

The Find task allows you to search an ArcGIS Server or local map service for features with attribute values that match or contain an input value. The input value must be text and cannot be a geometry or shape.

The Find task also allows searching for text in specified layers and fields. Each result in the results set includes its value, feature ID, field name, layer ID, layer name, geometry, geometry type, and attributes in the form of name-value pairs.

A layer in a map or feature 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 task works with feature layers and with raster layers. The Find task 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 features to be projected into a different coordinate system. This is useful, for instance, if the service's spatial reference is different from the spatial reference of the map on which you want to display the features.

See the REST Specification http://resources.arcgis.com/en/help/rest/apiref/ for a fuller description of the input and output options.

Using the Find task

There are 4 key steps to using the Find task:

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

Instantiate the Find task

Construct the FindTask class passing the URL of the local or online map service to be queried.

 
FindTask findTask = new FindTask("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer");

Specify the input parameters to the task

You can then define your query by setting various parameters on a FindParameters class. This FindParameters class will then be used as input to the FindTask when it is executed. Here are some basic guidelines:

call the setSearchText() method and provide the text to search for.
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.

 
FindParameters params = new FindParameters();
params.setSearchText(findText.getText());
params.setOutputSpatialRef(map.getSpatialReference());
params.setLayerIds(new int[]{0});//search only the Cities layer
params.setSearchFields(new String[]{"STATE_NAME"});//search only the named field

Execute the task asynchronously

Asynchronous execution of the Find task is performed using the executeAsync method using 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. If you execute the task asynchronously, the application will remain responsive during the execution of the task. You will need to setup a call back listener to respond when the task completes or errors. This is the recommended method of execution for most queries.

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

Execute the task synchronously

Synchronous execution of the Find task is performed using the execute method using the previously defined FindParameters class as input. If you execute the task synchronously, the application will be paused whilst the task is executing. The results of the FindTask will be a List of FindResults. This method of execution is only recommended if the Find is reliably fast and the result list is small.

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 have specified that there will be no geometry returned (setReturnGeometry(false)) then findResult.getGeometry() and findResult.getGeometryType() will return null. All that remains is for you to process the contents of the List of FindResults.

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

Sample code

To view any samples related to searching data please launch the ArcGIS Runtime for Java sample application, installed with the ArcGIS Runtime SDK for Java, and explore the interactive samples and their code in the Search > Find section.

2/7/2013