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.

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.

Procedure

• 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.

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.