How To: Use an ArcSDE geocoding service with ArcIMS
An ArcSDE geocoding service defines the rules and parameters for interpreting and matching address information with geographic reference data. The geocoding framework included with ArcGIS 8 provides the tools for creating, managing, and using geocoding services.
Both client-side and server-side geocoding services can be created. Server-side geocoding services require an ArcSDE server and thus provide a robust and centralized method for managing geocoding styles. ArcCatalog provides a user-friendly interface for working with these geocoding services, while ArcObjects and the ArcSDE APIs (Java and C++) provide low-level support in their respective development environment. Unfortunately, ArcIMS does not provide the ability to access server-side geocoding services.
Note, however, that ArcIMS services are often deployed using Web-based clients that communicate with an ArcIMS server through a Web server/servlet engine host. This means that communication involves implementation of a server-side Java component (servlet, bean, tag library). The ArcSDE Java API provides the tools to access a server-side geocoding service, while Java servlet technology provides the standard framework for implementing a server-side geocoding solution within a Web client.
This document provides a sample illustrating the integration of an ArcSDE geocoding service with an ArcIMS HTML Viewer using the ArcSDE Java API deployed in a custom servlet.
The ArcSDE Java class libraries are packaged in a JAR file (jsde82_sdk.jar, where "82" delineates the version of ArcSDE) and included with ArcSDE.
See the Related Information section below to download the sample sdegeo_servlet.zip. The sample contains the following files (with descriptions):
The Java classes needed to communicate with an ArcSDE geocoding service are located in the com/esri/custom directory (package). These class files can be deployed as is (see steps below) and already contain the code necessary for an HTML Viewer client to geocode an address. The classes assume that the ArcSDE geocoding service is using the "US Streets with Zone" Style and is expecting two inputs: an address and zone. The property file, sdegeo_prop, is located in the root directory and is used to reference the ArcSDE server parameters: server name, port, database, user, and password.
The source code (*.java files) is located in the build directory. If you choose, you can further develop this sample to suit your needs. Each source file contains comments to assist you in understanding the logic introduced in the code. To recompile these classes, you will need to download and extract the Java Servlet API (see Related Information) and the ArcSDE Java API (included with ArcSDE). The custom servlet (named GeoServlet.java) contains standard methods for processing incoming HTTP POST requests and forwarding content to a custom class (named GeocodeServer.java), which instantiates the proper objects needed to communicate with an ArcSDE geocode service. The GeocodeServer object returns the results to the GeoServlet servlet, and an HTTP response is sent back to the client using the same format as the ArcIMS Servlet Connector (namely the PostFrame is overwritten with a new HTML page containing a form).
The HTML Viewer specific files contain the following:
aimsClick.js - Contains the code to load the sdegeotest.htm in the TextFrame.
sdegeocode.htm - An HTML form that accepts two inputs from the user, address and zone, and one input from the developer, the ArcSDE geocoding service name. This form also submits the information to the GeoServlet servlet.
aimsCustom.js - Contains custom functions to retrieve the coordinate location of the geocoded address and create an acetate layer on the map image containing a point at that location.
Note that this sample is not supported by ESRI.
To set up this sample, you will need the following:
1) ArcIMS functioning successfully with a Web server-servlet engine
2) ArcSDE functioning successfully with an RDBMS
3) A polyline feature layer within ArcSDE containing valid address information (i.e., street number ranges, street names, zone)
4) The ArcSDE Java API JAR file
5) A single, running ArcIMS image service (preferably the image service contains the ArcSDE layer on which an ArcSDE geocoding service was created)
In this example, ArcIMS 4.0 has been configured with IIS 5.0/Tomcat 4.0.3, and ArcSDE 8.2 has been configured with Oracle 8.1.7 on Windows 2000.
- Create an ArcSDE geocoding service. Currently, this sample is only designed to work with the US Streets with Zone geocoding style. Note: The name of this geocoding service will be used in an upcoming step. See the ArcGIS Desktop Help documentation for more information.
- Create an HTML Viewer that accesses the ArcSDE dataset on which you are geocoding. Note: It is not necessary to have the layer on which you are geocoding in the same client. However, for the sample, it allows you to visualize the underlying data layer to which you are geocoding.
- The next few steps will involve editing, adding, and replacing files associated with the HTML Viewer created in step 2. Open the ArcIMSparam.js file and add the following at the top of the file:
var useSDEGeocode = true;
var sdegeox = 0;
var sdegeoy = 0;
- From the sample zip, copy toolbar.htm and sdegeocode.htm to the website root directory. Overwrite any preexisting files.
- In the website root directory, open sdegeocode.htm in a text editor and change the following lines:
postForm.action = "http://localhost/servlet/com.esri.custom.GeoServlet";
Change "localhost" to the Web server on which you have installed the ArcIMS Servlet connector.
postForm.service.value = "geocoding service name";
Set to the name of the ArcSDE geocoding service created in step 1.
Save the file.
- In Windows Explorer or another directory browser, locate the ArcIMS Servlet connector on your Web server-servlet engine where the com folder and Esrimap_prop file are located. From the sample zip, copy the com folder, which contains the GeoServlet.class and GeocodeServer.class, and the sdegeo_prop file to the same location. Overwrite any existing files. Note that the existing content of the com directory will not be deleted.
- Open the sdegeo_prop file in a text editor and change the following parameters to the ArcSDE server on which the geocoding service exists:
server=<ArcSDE Server machine name or ip address>
database=<database name, if necessary>
- Make sure that the Java SDE API JAR file (i.e., jsde82_sdk.jar) is in the servlet engine's classpath. This JAR file is included with ArcSDE. Often you can place the JAR file in the $TOMCAT_HOME\lib directory, and the Tomcat servlet engine will automatically recognize the JAR contents after restart.
- Open the HTML Viewer you created in step 2 in a browser. Click on the geocode tool at the bottom of the toolbar. The sdegeotest.htm file should be loaded into the TextFrame portion of the HTML Viewer (below the map frame). Type in a valid street address for ArcSDE on which the geocoding service was created (see step 1). The response should populate the TextFrame with the matched, standardized address, and the map image should be updated with an acetate layer containing a point where the geocoded address is geographically located. Currently, the Java SDE API can only return a single matched address.
Note: If geocoding is unsuccessful, the TextFrame will display an "Address not found" message. This may indicate that an error has occurred or the address values were unmatchable. The servlet engine logfiles may provide additional information on the precise error - see your servlet engine documentation for their specific location and content. You may also want to evaluate the address values using another interface, such as ArcMap.