Spatial Query REST SOE


Purpose
This sample shows a server object extension (SOE) that queries and clips features within a buffer distance and summarizes the resulting area based on a given attribute. The SOE is exposed as a representational state transfer (REST) Web service. It works with map services only.
All the information needed to deploy the SOE is included in this sample encapsulated in a .soe file. Deploying the SOE from this file does not require you to open Visual Studio. However, you can open the Visual Studio solution included with this sample to explore the coding patterns used in the SOE.
This sample also includes a simple JavaScript application that consumes the SOE. It lets the user specify a buffer distance and a point on the map. In response, the application draws the clipped geometries and displays a summarized table of areas for the clipped polygons, based on vegetation type. The application assumes you have deployed the SOE on the Yellowstone sample map from the .NET ArcObjects software development kit (SDK). Instructions for testing the SOE based with this dataset are given below.
The instructions below assume that you have installed the developer kit on the machine running ArcGIS Server Manager. If you installed the developer kit on some other machine, you'll need to copy the .soe file to the machine running Manager, or otherwise make the .soe file visible to Manager by placing it in a shared folder.

How to use

See How to use ArcGIS samples for help on compiling, setting up the debugger, and running the sample. If the sample has associated data, you will find that the sample's zip file includes a "data" folder alongside the language folders. However, you will need to update the sample to point to the location of the data once you have extracted all the files.

Deploy the SOE
  1. Log in to ArcGIS Server Manager and click Site.
  2. Click Extensions.
  3. Click Add Extension.
  4. Click Browse and navigate to the .soe file, which by default is located at <ArcGIS DeveloperKit install location>\Samples\ArcObjectsNet\ServerSpatialQueryRESTSOE\CSharp\SpatialQueryREST\bin\Debug\SpatialQueryREST.soe.
  5. Click OK.

Enable the SOE on a service
  1. Start ArcMap and click File > Open.
  2. Browse to or type the location of Yellowstone.mxd, which is located in <ArcGIS Developer Kit Location>\Samples\data\Yellowstone.
  3. Click File > Share As > Service.
  4. Click Save a service definition and click Next.
  5. Choose "No available connection" and check "Include data in service definition when publishing".
  6. Change the Server type to ArcGIS Server.
  7. Leave the Service name as Yellowstone and click Next.
  8. Choose a location where you want to save the service definition, then click Continue.
  9. Click Stage to create the service definition. In the success message, note the path of your service definition (.sd).
  10. Copy the Yellowstone.sd file to the machine running ArcGIS Server Manager.
  11. On the machine running ArcGIS Server Manager, log in to Manager and click Services.
  12. If necessary, click the Manage Services tab.
  13. Click Publish Service.
  14. Click Browse, browse to the location of Yellowstone.sd on the local machine, and click Open. Then click Next.
  15. Accept the default properties for the service by clicking Next.
  16. Click Publish. This creates the USA map service.
  17. On the Services tab of Manager, select the USA map service, then select Capabilities. In the list of available capabilities, find SpatialQueryREST and check the box to enable it. If there is a list of available operations allowed, select all of them.
  18. Click Capabilities and click SpatialQueryREST (be careful not to uncheck the box). You are now viewing the properties page for the service. Ensure that the LayerName is "veg" (no quotes) and that the FieldName is "PRIMARY_" (no quotes).
  19. Click Save, then Restart to restart the service.

Test the SOE in the ArcGIS Server Services Directory
  1. Clear the Representational State Transfer (REST) cache of your Services directory. You can find cache clearing options if you open a web browser and log into http://<server name>:6080/arcgis/rest/admin. Click REST Cache, then click Clear Cache Now.
  2. Access your services directory by opening http://<server name>:6080/arcgis/rest/services in a Web browser.
  3. Click Yellowstone, scroll down to the bottom of the page, and click SpatialQueryREST. You’re now at the root resource page of your SOE.
  4. Click the one operation available, SpatialQuery. You can test this operation by adding some simple JavaScript Object Notation (JSON) parameters in the input boxes.
  5. Type {x:544000,y:4900000} in the location box.
  6. Type 5000 in the distance box.
  7. Click either the SpatialQuery (GET) or SpatialQuery (POST) button. You should see a long JSON response containing the clipped polygon geometries from the spatial query. Scroll to the bottom of the response and you’ll see a list of the total areas for each vegetation type.

Use the SOE in a JavaScript application
  1. Using a text editor, such as Notepad, open the SpatialQueryRESTClient.html file included with this sample. This is a sample application built with the ArcGIS application programming interface (API) for JavaScript that uses the SOE. You must have Internet access to successfully run this application.
  2. Find the line of code, var soeURL = "http://<server name>:6080/arcgis/rest/services/Yellowstone/MapServer/exts/SpatialQueryREST/SpatialQuery";
  3. If necessary, replace the uniform resource locator (URL) in the preceding line of code with the REST URL to your SOE.
  4. Find the line of code, var dynamicMapServiceLayer = new esri.layers.ArcGISDynamicMapServiceLayer("http://<server name>:6080/arcgis/rest/services/Yellowstone/MapServer");
  5. If necessary, replace the URL in the preceding line of code with the REST URL to your Yellowstone map service.
  6. Save the file.
  7. Double-click the SpatialQueryRESTClient.html file in Windows Explorer to run it.
  8. Type a buffer distance, such as 5000, then click anywhere on the map. After a few seconds, you'll see the buffered and clipped features displayed on the map, along with a table summarizing the area of each vegetation type.

SpatialQueryREST\SpatialQueryREST.cs The SOE code
SpatialQueryREST\bin\Debug\SpatialQueryREST.soe The deployable SOE file
SpatialQueryRESTClient.html JavaScript client application for the SOE
Download the C# files

Download the files for all languages

See Also:

Walkthrough: What's in the REST SOE
How to develop the REST SOE
How to register the REST SOE
How to develop a property page for the REST SOE
How to enable and test the REST SOE on a service
How to use the REST SOE in a Web application