English

How To: Alias the Servlet Connector using Tomcat for ArcIMS 9

Summary

Instructions provided describe how to alias the Servlet Connector using Tomcat and ArcIMS 9.0. Using a number of ArcIMS clients, such as ArcMap and ArcExplorer, users can view, query, and even save features from ArcIMS map services. In most cases, this can be prevented by enabling authentication for IMS map services. However, in certain cases, entering a user name and password is less than desirable for public Web sites.

The only alternative is to alias the servlet connector. This enables browser-based clients, such as the HTML Viewer, to access map services. Other ArcXML capable clients, including ArcExplorer 3+, ArcMap, and ArcPad, can not access these map services. The following article outlines how to accomplish this by deploying the ArcIMS Servlet Connector in a Web application.

Known caveats when creating an alias for 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.

Procedure

While there are a variety of techniques for creating a Web application, this document outlines only one approach. The basic procedure is as follows:

  1. Deploy the ArcIMS Servlet Connector in a Web application.
  2. Configure the new Web application for use with a Web server.
  3. Configure the Web server to use the new Web application.
  4. Configure the client applications to use the new Web application.
Note:
While the technique described in this document 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, learn the new location and name of the aliased Servlet Connector, and customize the client application to use the new alias. Thorough testing is recommended.

The following instructions explain how to create a Web application in Tomcat that contains a custom version of the ArcIMS Servlet Connector. These instructions assume Tomcat has been installed and successfully deployed with a Web server.
 
  1. Copy the Servlet Connector into a new Web application.
    1. Stop the Apache Tomcat service.
    2. Make a copy of the file arcimsservletconnector.war file from <ArcIMS installation directory>\ArcIMS\Connectors\Servlet and rename the copied file to for example ARCIMS.war.
      Note:
      The name that is chosen for the file will be used in the URL prefix for the aliased ArcIMS Servlet Connector. This example employs 'ARCIMS'.
      
    3. Copy the ArcIMS.war into the Tomcat webapps directory at <Tomcat installation directory>\webapps.
    4. Restart the Tomcat service. This auto-deploys the Web application and a folder called ARCIMS should appear in the \webapps directory.
  2. Configure the Web application.
    1. In a text editor open the web.xml file for the newly created Web application. It is located at <Tomcat installation dir>/webapps/ARCIMS/WEB-INF/web.xml.
      Note:
      The web.xml file is called the deployment descriptor for the application.
      
    2. Within the web.xml file, replace the entire 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>
        <!-- This sets the alias "ims" for the ArcIMS Servlet connector --> 
      <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>
        <!-- This sets the URL Pattern /ims for the aliased ArcIMS Servlet connector "ims" --> 
      <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 a client attempts to connect to ArcIMS with the default servlet name (com.esri.esrimap.Esrimap), an "HTTP 404: File-not-found" response is returned. If preferred, an existing servlet such as, HelloWorldExample or SnoopServlet, can be substituted in the servlet-class tag. Alternatively, a sorryServlet class or a JSP page can be created to display an error message. Some servlets are typically installed at C:\Tomcat4129\webapps\examples\WEB-INF\classes. The servlet must be copied to the classes directory within the arcims Web application.
      
    3. Save and close the web.xml file.
  3. Configure the Web server to pass requests to Tomcat with the following Web server:
    • Apache 2.0.4x:
      1. Open the workers2.properties file, found in the /conf directory within the Apache Web server installation directory, in a text editor.
      2. Towards the end of the file find the following lines:
        [uri:/servlet/*]
        info=ArcIMS servlet connector
        
        Add the context for the aliased servlet /ARCIMS as the following:
        [uri:/ARCIMS/*]
        info=aliased ArcIMS servlet connector
        
      3. Save the file and exit the text editor.
    • IIS 5/6 with Tomcat using mod_jk:
      1. Open the uriworkermap.properties file, found in the <Tomcat>\conf folder, in a text editor.
      2. Add the following lines to the bottom of the file, substituting the Web application directory name as appropriate.
        For Tomcat 4.1.xx and Tomcat 6.x:
        # New location for ArcIMS connector (webapps\arcims)
        /ARCIMS/*=ajp13
        /ARCIMS=ajp13
        
        For Tomcat 5.0.xx and Tomcat 6.0xx:
        # New location for ArcIMS connector (webapps\arcims)
        /ARCIMS/*=wlb
        /ARCIMS=wlb
        
      3. Save and close the file.
    • IIS 5/6 with Tomcat using mod_jk2:
      1. Open the worker2.properties file, found in the <Tomcat>\conf folder, in a text editor.
      2. Add the following lines to the bottom of the file, substituting the Web application directory name as appropriate:
        # New mapping for aliased ArcIMS servlet connector,
        [uri:/ARCIMS/*]
        worker=ajp13:localhost:8009
        
      3. Save and close the file.
  4. Configure the aliased Servlet Connector to communicate with ArcIMS.
    1. Open Windows Explorer and navigate to the following directory: <Tomcat Install Dir>\webapps\ARCIMS\WEB-INF\classes.
    2. Open the Esrimap_prop file with a text editor.
    3. Change the value of the appServerMachine from APPSMACHINE to the name or IP address of the server hosting the ArcIMS Application Server.
    4. Save and close the file.
  5. Restart the Web server (Apache or IIS) and Tomcat.
  6. Test the new servlet configuration by opening a browser and typing the following into the Address (location) field:
    http://<servername>/ARCIMS/ims?Cmd=ConnectorPing
    where <servername> is the server name (or IP address), 'ARCIMS' is the Web application URL prefix (the folder name), and 'ims' is the servlet-name (specified in the web.xml file).
    Warning:
    The prefix and name are case-sensitive.
    A simple response with the ArcIMS version and build number should be returned. If not, check the Web application URL and settings (case sensitive), and the Servlet Connector properties in the web.xml file.
  7. For 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 files.
  8. Test each client application to verify it works with the new servlet path.
  9. Once the new clients are working with the new alias, the original Servlet Connector may be disabled to work with the web server.
    • ALTERNATIVE A: DISABLE REDIRECTOR - Recommended
      Edit the files mentioned in step 3 and remove the context paths for /servlet.

      This way the default connector can only be accessed through Tomcat directly on port 8080. Both ArcIMS Designer and ArcIMS Administrator can still be used for administration on the internal network with the URL http://servername:8080, but access through the default port 80 is denied.
       
    • ALTERNATIVE B
      Set authenticate=true in the esrimap_prop file located at <Tomcat installation directory>/webapps/servlet/WEB-INF/classes.
      This way ArcIMS Administrator can still be used for administration, but the map services are not accessible through other clients like ArcMap or Designer.
       
    • ALTERNATIVE C: DELETE CONNECTOR
      Navigate to the webapps folder of the Tomcat installation directory using Windows Explorer. For example, C:\Tomcat4129\webapps.
      Delete the /servlet directory and servlet.war file.

      This way only the ArcIMS Service Administrator (esriadmin) can be used to administer ArcIMS. Designer and Administrator cannot be used.

Related Information