English

How To: Alias the Servlet Connector using ServletExec 5.x and ArcIMS 9.x

Summary

Using a number of ArcIMS clients, such as ArcMap and ArcExplorer, users can view, query, and even save features from ArcIMS map services. However, many websites that offer map services require browser clients to enter a username and a password.

This document describes how to deploy an ArcIMS Servlet Connector in a Web application which will enable HTML browser-based clients to access map services.


Note: ArcXML-capable clients (including ArcExplorer 3+, ArcMap, and ArcPad) will not be able to access the map service. Known caveats when aliasing the Servlet Connector:
  1. If the default ArcIMS Servlet Connector is being locked down by turning on authentication, access from ArcMap to ArcIMS map services is disabled and ArcIMS Designer will fail to connect to the map services, but ArcIMS Administrator can still be used for administering the sites. When completely disabling or removing the default ArcIMS Servlet Connector, the standalone ArcIMS Administrator will fail to connect as well, since it uses the default Servlet Connector to communicate with the Application Server. If the connector has been removed or disabled, the only alternative is to deploy the Web-based map service administrative application known as Service Administrator (or "esriadmin"). Steps on how to deploy this application are located in Step 3A - Installing ArcIMS Service Administrator of the ArcIMS Installation Guide, which is available on the ArcIMS installation CD (click on install.htm) or under <ArcIMS installation>\ArcIMS\Documentation\install.htm.
  2. In certain situations, the ArcIMS Post Installation must be executed. For example, this is required when updating ArcIMS with a Service Pack. When running through a typical Post Install, the default Servlet Connector will be re-installed on the system. This will negate all of the changes made above. Hence, it is imperative that the following steps are followed when executing the Post Install for ArcIMS:
    1. For a Custom Post Install: Uncheck the option to configure the Web server/Servlet Engine
    2. For a Typical Post Install: Select the option "I will manually configure my Web server/Servlet Engine" at the Web server-Servlet Engine configuration screen.
While the technique described in this document (i.e., aliasing the Servlet Connector using a Web application) is highly effective, it may still be possible to customize ArcMap or other ArcXML-capable clients to gain access to map services. In order to do this, new location and/or name of the moved Servlet Connector would need to be identified, and the client application would need to be customized to use the moved Servlet Connector. Thorough testing is recommended.

Procedure

While there are a variety of techniques for creating a Web application, this document outlines the following approach:

  • Deploy the ArcIMS Servlet Connector in a Web application.
  • Configure the new Web application for use with your Web server.
  • Configure your Web server to use the new Web application.
  • Configure the client applications to use the new Web application.
The following procedure explains how to create a Web application in ServletExec that will contain a custom version of the ArcIMS Servlet Connector. These instructions assume version 5.x is being used. Substitute the version in use and directory names as necessary.
 
  1. Copy the Servlet Connector into a new Web application.
    1. Copy the file arcimsservletconnector.war file from <ArcIMS installation directory>\ArcIMS\Connectors\Servlet and paste it into <drive>:\Program Files\NewAtlanta\ServletExec ISAPI\webapps\default.
    2. Rename the file to ARCIMS.war. The name of the file will be the URL prefix used for the ArcIMS Servlet Connector in the future. The example used here is ARCIMS.
      Warning:   
      The naming is case sensitive.
    3. Restart the IIS Admin and WWW Publishing services.
      Note:
      This re-initializes ServletExec and auto-deploys the web application.
  2. Configure the Web application.
    1. In a text editor open the web.xml file for the created web application. This is found in <ServletExec Installation Directory>\ServletExec ISAPI\ServletExec Data\default\arcims\WAR\WEB-INF\web.xml
    2. Within the web.xml file, replace the existing text with the lines below:
      <?xml version="1.0" encoding="UTF-8"?>
      
      <!DOCTYPE web-app PUBLIC 
      
      "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
      "http://java.sun.com/dtd/web-app_2_3.dtd">
      
      <web-app>
      
        <servlet>
      
          <servlet-name>ims</servlet-name>
      
          <servlet-class>
      
            com.esri.esrimap.Esrimap
      
          </servlet-class>
      
        </servlet>
      
        <servlet>
      
          <servlet-name>sorry</servlet-name>
      
          <servlet-class>
      
            sorryServlet
      
          </servlet-class>
      
        </servlet>
      
        <servlet-mapping>
      
          <servlet-name>ims</servlet-name>
      
          <url-pattern>
      
            /ims
      
          </url-pattern>
      
        </servlet-mapping>
      
        <servlet-mapping>
      
          <servlet-name>sorry</servlet-name>
      
          <url-pattern>
      
            /servlet/com.esri.esrimap.Esrimap
      
          </url-pattern>
      
        </servlet-mapping>
      
        <!-- need wildcard pattern too -->
      
        <servlet-mapping>
      
          <servlet-name>sorry</servlet-name>
      
          <url-pattern>
      
            /servlet/com.esri.esrimap.Esrimap/*
      
          </url-pattern>
      
        </servlet-mapping>
      
      </web-app>
      Note:
      This configuration points toward a servlet called "sorryServlet" which does not exist. If an attempts is made to connect to ArcIMS with the default servlet name (com.esri.esrimap.Esrimap), a file-not-found response (404 message) will be returned. If preferred, an existing servlet can be substituted such as HelloWorldExample or SnoopServlet in the servlet-class tag, or create a sorryServlet class or a JSP page that displays an error message.
    3. Save and close the web.xml file.
  3. Configure ServletExec and ArcIMS.
    1. Navigate to <ServletExec Installation Directory>\ServletExec ISAPI\ServletExec Data\default\ARCIMS\WAR\WEB-INF\classes and open the ESRImap_prop file in a text editor.
    2. Change appServerMachine=APPSERVER to appServerMachine=<machine name> where <machine name> is the name of the machine where the ArcIMS Application server is installed.
    3. Restart the IIS Admin and WWW Publishing services.
  4. Test the new servlet configuration. To test the new servel configuration, open a browser and type the following into the Address (location) field:
    http://<servername>/ARCIMS/ims?Cmd=ConnectorPing
    and
    http://<servername>/ARCIMS/ims?Cmd=AppserverPing
    where <servername> is your server name (or IP address), "ARCIMS" is the Web application URL prefix (the folder name) you created, "ims" is the servlet-name (specified in the web.xml file).
    Warning:   
    The prefix and name are case-sensitive.
    A simple response should be received with the ArcIMS build number. If not, check the Web application URL and settings (case sensibility), and the Servlet Connector properties in the web.xml file.
  5. For the client applications to use the servlet alias, they must be modified so that they reference the new URL path and servlet name.
    1. For each client application locate and open the files indicated in a text editor:

      HTML Viewer: ArcIMSparam.js, Authorize.htm, aimsMap.js, and aimsXML.js

      Java Viewer: default.axl

      Custom viewers: open any files that refer to the ArcIMS servlet connector.
    2. Change each occurrence of:
      /servlet/com.esri.esrimap.Esrimap
      to
      /ARCIMS/ims
      where ARCIMS is the Web application URL prefix and ims is the servlet name specified earlier.
      Note:
      The prefix and name are case-sensitive.
    3. Save and close the modified file(s).
  6. Test each client application to make sure it works with the new servlet path.
  7. Restrict the default Servlet Connector.
    1. In a text editor, open the Esrimap_prop file found in the default Connector directory (typically C:Program Files\New Atlanta\ServletExec ISAPI\Servlets). Change the line

      authenticate=False
      to
      authenticate=True
    2. Save and close the Esrimap_prop file.
    3. Stop and restart the IIS Admin service (and all related services, such as the World Wide Web Publishing service). This will cause ServletExec to re-load the modified Esrimap_prop file.
    4. Attempt to connect to the ArcIMS server with ArcMap, ArcExplorer, or ArcPad to ensure that these cannot load map services.
      Warning:   
      This will prevent any connection to map services via the default copy of the Servlet Connector. If a connecting client has not been configured as described in Step D above, the connection will be refused. This also includes ArcIMS Designer.
      Warning:   
      After these settings, the ArcIMS Diagnostics tests will show "ArcIMS Error 004 - Servlet Connector cannot read ACL file". This is due to the ArcIMS Servlet Connector unable to read the ACL file since it does not exist. You should still be able to login to ArcIMS Administrator despite this error.