English

How To: Use the Java Connector in a servlet to filter ArcXML requests

Summary

The ArcIMS Servlet Connector, included with the ArcIMS product, can be used to administer the ArcIMS Application server and to serve requests from multiple clients, such as HTML Viewer, ArcMap. The Servlet Connector also includes an authentication mechanism to restrict access to MapServices for those users specified in a file or JDBC-based Access Control List (ACL). The ACL can prohibit specific requests from being sent to an ArcIMS service. Unfortunately there is no way to restrict specific portions of the request, therefore all or none of a certain request can be permitted. For example, if the GET_FEATURES request is forbidden in an ACL for a specific ArcIMS service and user, all GET_FEATURES requests sent to that service will be blocked. In short, the Servlet Connector does not provide a mechanism for restricting attributes or child elements of a request.

Procedure

To restrict portion(s) of an ArcIMS request, a custom servlet implementing the Java Connector classes can be used. The Java Connector is included with the ArcIMS 4.x product and consists of four jar files: arcims_jconnect.jar, jcert.jar, jnet.jar, and jsse.jar. The Java Connector, like the Servlet Connector, also includes a mechanism for restricting access to mapservices. Moreover, the Java Connector classes can be easily implemented and customized in the Java development environment which can be used to restrict ArcIMS requests at any level. The sample servlet included with this article uses the Java Connector to communicate with an ArcIMS Application server and the Java Servlet API to communicate with Web clients using an HTML form. It includes string parsing techniques to evaluate incoming ArcXML requests for the presence of the 'geometry' attribute in a GET_FEATURES request. A property file, similar to the Esrimap_prop file used by the ArcIMS Servlet Connector, is used to enable or disable the ability of a client to retrieve feature geometry values.

The sample servlet is named the JConnServlet Connector and will only work with clients that use HTML forms, for example, ArcIMS HTML Viewer. The JConnServlet Connector will not work with clients that do not use HTML forms, for example, Java Viewers, ArcExplorer Java, ArcMap and ArcIMS Administrator.

See the Related Information section to download the sample. The sample contains the following files (with descriptions):

jconnservlet_prop
/com/esri/custom/JConnServlet.class
/com/esri/custom/Ping.class
/com/esri/custom/AxlRequestModifier.class
/com/esri/custom/GetExtractModifier.class
/com/esri/custom/GetFeaturesModifier.class
/com/esri/custom/GetGeocodeModifier.class
/com/esri/custom/GetImageModifier.class
/build/JConnServlet.java
/build/Ping.java
/build/AxlRequestModifier.java
/build/GetExtractModifier.java
/build/GetFeaturesModifier.java
/build/GetGeocodeModifier.java
/build/GetImageModifier.java

The Java classes associated with this connector are located in the com/esri/custom directory (package). The JConnServlet class files can be deployed as is (see steps below) and already contain the code necessary for disabling the ability of a client to retrieve feature geometry. The property file, jconnservlet_prop, is located in the root directory and is used to reference the ArcIMS Application server, port and enabling of feature geometry for the JConnServlet Connector. To disable retrieval of feature geometry, change the 'geometry' attribute to 'false'. The jconnservlet_prop file contains comments for further information on attributes listed.

The source code (*.java files) is located in the build directory. The JConnServlet Connector can be further developed to suit your needs. Each source file contains comments to assist you in understanding the logic introduced in the code. In order to recompile these classes, download and extract the Java Servlet API; see the link in Related Information. In general, each source file contains the following information:

JConnServlet.java - extends HttpServlet, responsible for processing the request and sending the response
Ping.java - includes methods used to check the communication with the connector and communication with the ArcIMS Application server
AxlRequestModifier.java - abstract class, contains framework for request modifier classes
GetExtractModifier.java - used to evaluate GET_EXTRACT requests, currently no filtering code included
GetFeaturesModifier.java - used to evaluate GET_FEATURES request, currently contains methods to filter requests containing the "geometry" attribute
GetGeocodeModifier.java - used to evaluate GET_GEOCODE requests, currently no filtering code included
GetImageModifier.java - used to evaluate GET_IMAGE requests, currently no filtering code included

Note:
This sample is not supported by ESRI


To setup this sample, you need the following:

1) ArcIMS functioning successfully with a Web server-servlet engine configuration.
2) A single ArcIMS image mapservice and corresponding HTML Viewer.
3) Java Connector jar files.
4) The JConnServlet Connector files.

In this example, ArcIMS 4.0 has been configured with IIS 5.0 and Tomcat 4.0.3 on Windows 2000.

  1. Confirm ArcIMS requirements

    Make sure that ArcIMS is functioning correctly. Confirm that an ArcIMS image mapservice is running and an HTML Viewer referencing that mapservice will load successfully in a browser.

  2. Add the Java Connector jars to the servlet engine classpath

    All four Java Connector jars must be in the servlet engine's classpath. For Tomcat users, add all jars to the $TOMCAT_HOME\classes directory. Other servlet engines may require you to add the path to each jar specifically.

  3. Unzip the JConnServlet zip file in a new directory

    Create a new directory and unzip the contents of the JConnServlet zip file.

  4. Add the JConnServlet Connector classes to the servlet engine

    Locate the default servlet directory for your servlet engine. Note that in most cases, the ArcIMS Servlet Connector is located in the default servlet directory. Copy and paste the com folder and the jconnservlet_prop file to the default servlet directory. If you receive a message to "Confirm Folder Replace", click "Yes to All".

  5. Change the ArcIMS Application server and port in the jconnservlet_prop file

    Open the jconnservlet_prop file in a text editor. Change the appServerMachine and appServerClientPort to the ArcIMS Application server and connector port, respectively. Save the file.

  6. Restart the servlet engine and web server

  7. Check communication with the JConnServlet Connector

    Open a browser and type the following (where "server_name" is your web server's host name):

    Code:
    http://server_name/servlet/com.esri.custom.JConnServlet?cmd=ConnectorPing


    You should see the following response:

    Code:
    JConnServlet 1.0

  8. Check communication between the JConnServlet Connector and the ArcIMS Application server

    Open a browser and type the following (where "server_name" is your web server's host name):

    Code:
    http://server_name/servlet/com.esri.custom.JConnServlet?cmd=AppServerPing


    You should see the following response:

    Code:
    SUCCESS: ArcIMS Application Server Contacted Successfully



  9. Setup an HTML Viewer to use the JConnServlet Connector

    From the HTML Viewer referenced in step 1, open the ArcIMSParam.js (in the website's root directory) file in a text editor. Near the beginning of the file, change the following line from (:

    Code:
    var esriBlurb = "/servlet/com.esri.esrimap.Esrimap?ServiceName="


    -to-

    Code:
    var esriBlurb = "/servlet/com.esri.custom.JConnServlet?ServiceName="


    Also, change the following lines to reference the JConnServlet Connector accordingly (note that the service name referenced by these lines may be different in your HTML Viewer):

    Code:
    var imsURL = 'http://server_name/servlet/com.esri.esrimap.Esrimap?ServiceName=World';
    var imsOVURL = 'http://server_name/servlet/com.esri.esrimap.Esrimap?ServiceName=World';


    -to-

    Code:
    var imsURL = 'http://server_name/servlet/com.esri.custom.JConnServlet?ServiceName=World';
    var imsOVURL = 'http://server_name/servlet/com.esri.custom.JConnServlet?ServiceName=World';


    Save the file.

  10. Load the HTML Viewer in a browser

    Open a browser and load the HTML Viewer referenced in the previous step. The HTML Viewer should load successfully. The HTML Viewer is now using the JConnServlet Connector instead of the ArcIMS Servlet Connector to communicate with the ArcIMS Application server.

  11. Evaluate ArcIMS security options

    The JConnServlet Connector can be deployed in any servlet enabled location on your servlet engine. It will allow you to detect and alter incoming requests at any level (element or attribute) as well as restrict the type of clients accessing your ArcIMS Application server. While the ArcIMS Servlet Connector is needed to administer your ArcIMS site using ArcIMS Administrator, it is not required, and may not be the most functional and\or secure solution for HTML clients. While aliasing the ArcIMS Servlet Connector (see Related Information below) will block most incoming requests from non-HTML clients, it will not necessarily restrict communication with development environments that allow the creation and posting of HTML forms. For example, the Java package java.net contains the URL and URLConnection classes which can be used to send raw ArcXML requests to an ArcIMS Application server through a servlet. In conclusion, the techniques introduced in the JConnServlet Connector can be used to assuredly manage the incoming and outgoing information associated with your ArcIMS site.

Related Information