How To: Add and Refresh ArcIMS Services using the Java Connector


Instructions provided offer an example and discussion on how to use the Java Connector to log into an ArcIMS site, create a map service, refresh existing ArcIMS services, and save site properties.


Two packages contain classes used by the Java Connector to administer an ArcIMS site: com.esri.aims.mtier.io and com.esri.aims.mtier.model.admin

  • The ConnectionProxy class is included with the com.esri.aims.mtier.io package. This class is used to create a connection (via TCP or HTTP) to the ArcIMS Application server. The static constants TCP_ADMIN and HTTP_ADMIN can used by the ConnectionProxy's setConnectionType() method to define a connection for administrative purposes. TCP_ADMIN defines a direct connection to the ArcIMS Application server, while HTTP_ADMIN defines a connection via the ArcIMS Servlet connector (the same method used by ArcIMS Administrator). In both cases, a proprietary, encrypted data stream is used to communicate with the ArcIMS Application server. In this situation, the setUsername() and setPassword() methods are used to define the ArcIMS administrative user and password, respectively. The ConnectionProxy's ping() method can be used to validate the state of the ArcIMS site, namely whether or not the site has been logged into before.

    There are three possible results:

    0 = The ArcIMS site is accessible and the username and password have already been set (an ArcIMSSite.sez file exists).
    -1 = The ArcIMS site is not accessible
    -2 = The ArcIMS site is accessible, but this is the first administrative request, so the username and password will be set when the ArcIMS site is initialized (an ArcIMSSite.sez file does not exist).

    When used with a ConnectionProxy set up for ArcIMS administration, the ping() method will by default require the username and password. If you only want to evaluate the state of the ArcIMS site, not the username and password, use ping(false).

  • The com.esri.aims.mtier.model.admin package includes all the Java Connector's public API for administering an ArcIMS site. The Site class is used to define access to an ArcIMS site. After creating a new Site instance, the setSiteUser() method can be used to establish the authentication parameters for interacting with the site. If ping() returns -2, setSiteUser() will set the username and password for an ArcIMS site and ConnectionProxy instance. If ping() returns 0, the username and password for the ConnectionProxy instance must be set (using setUsername() and setPassword()) before calling setSiteUser()). Essentially this changes the username and password for the site from the initial ConnectionProxy settings to the username and password submitted in the setSiteUser() method. In most cases both will be exactly the same, unless you want to change the username and password. Once established, the site configuration (login, services, spatial and virtual server config) can be saved via a call to the save() method on the Site instance.

    ConnectionProxy mcp = new ConnectionProxy();
    Site site = new Site();
    boolean stf = false;

    int reaction = mcp.ping(false);

    if (reaction == ( -2)) {

    site.setSiteUser(ADMIN_USER, ADMIN_PASSWORD, mcp);
    stf = site.save(mcp);

    } else if (reaction == ( -1)){

    site.setSiteUser(ADMIN_USER, ADMIN_PASSWORD, mcp);
    stf = site.save(mcp);

    } else if (reaction == 0) {

  • Once an authenticated, administrative connection to an ArcIMS site is established, subsequent steps to manage the site can proceed. Two common procedures will be covered: adding a new service and refreshing all services.

    The Service class is used to manage creation and interaction with map services. To create a new service, a new Service instance should be instantiated. When administering ArcIMS with the Java Connector, consider that there are three separate processes capable of running on three separate machines. The Java Connector application (managed by a Java Virtual Machine, java.exe), the ArcIMS Application server, and the ArcIMS Spatial server. Adding a new service requires that a few service specific properties are known to one or more of these processes. Here are the methods to consider:


    To add a service, the Java Connector must have access to a String, input stream, or byte array containing the map configuration. Usually this means file system access to an axl or mxd. If only adding the service via the Java Connector, the ArcIMS Application server does not need to have access to the map config contents (i.e. axl file). However, if you plan on administering your ArcIMS site outside of your Java Connector application, the Application server will need to know when to get the config file contents. The next method sets the location of the config file.


    This method provides the Application server with the map configuration file location. The location is not validated by the Java Connector, it is only used by the ArcIMS Application server.


    The Spatial server needs to know where to create map or legend images for clients of ArcIMS image services. The location is not validated by the Java Connector, it is only used by the ArcIMS Spatial server.


    Any ArcXML response containing the location of an image for an ArcIMS image service includes a url to the image. The url is not validated by any ArcIMS specific process or API, but it must be valid from the client perspective to view the output images generated by the ArcIMS Spatial server.


    The type of service created dictates which virtual server name and type are defined. If the virtual service type and name are not already known, use the VirtualServerCollection collection class to discover which and what type of servers are available.


    The service name must be unique for the ArcIMS Application server. It is case sensitive.


    The Service class maintains static image constants consistent with image output types available via the ArcIMS Spatial server (these include JPG, GIF, PNG). The static constant can be used to define the output image type for a Service. The setPixelCount() method defines the maximum image size (expressed in number of pixels) possible when generating an output image from an image service. For example, a 1000 x 1000 image contains 1,000,000 pixels. The setOutputCleanup() method is used to set the number of minutes before the ArcIMS Tasker will remove images generated by the Spatial server for a specific ArcIMS service.

    Once the Service object properties are set, the addService() method is called to add the service to the ArcIMS server. By default, the service is not started. A call to the startService() method is used to start the service and make it available for requests. Note that the administrative ConnectionProxy is used by both methods to establish a connection with the ArcIMS Application server and initiate the process.

    String SERVICE_PATH = "c:/ArcIMS/AXL/sanfran.axl";
    String SERVICE_NAME = "sanfrancisco";
    String OUTPUT_PATH = "c:/ArcIMS/output";
    String OUTPUT_URL = "http://localhost/output";

    java.io.FileInputStream myservice_fis = new java.io.FileInputStream(SERVICE_PATH);
    Service myservice = new Service();
    myservice.setConfigContents(myservice_fis, false);
    myservice.setVirtualServer("ImageServer1", "ImageServer", "");


  • The Service and ServiceCollection classes are used to refresh existing ArcIMS services. The process of refreshing a service involves simply removing then readding the same service. The ServiceCollection class contains an array of Service objects populated by calling the getServices() method. Each Service object maintains the properties specific to the service, except one, the service contents. As a result, the Java process in which the Java Connector is being used must have access to the service contents, which in the simplest case means that it must have access to the map configuration file (axl or mxd). The getConfigContents() method will only return service content for Service objects that have been added during the same Java Connector session, otherwise it will return null. Note that the path to map config file can be defined via UNC. If the map config file used by the Application server is not accessible, the Java Connector must find a substitute (e.g. a local copy) or it will not be able to refresh the existing service.

    ServiceCollection service_collection = ServiceCollection.getServices(mcp);
    Service[] services = new Service[service_collection.size()];

    for (int i=0;i<service_collection.size();i++){
    Service aservice = service_collection.getService(i);
    services[i] = aservice;


    for (int i = 0; i < services.length; i++) {
    Service bservice = services[i];
    java.io.FileInputStream new_fis = new java.io.FileInputStream(bservice.getConfigFile());
    bservice.setConfigContents(new_fis, false);

    In the example above, a Service array is used to maintain Service objects between removing and readding ArcIMS services. The removeService() method is used to remove the service from an ArcIMS site. A delay has been added to allow the ArcIMS server an adequate amount of time to remove the services. When readding the same service, only the Service content needs to be restored. In this case, the Java process and the ArcIMS Application server both have file system access to the map configuration file. As a result, the getConfigFile() method returns the absolute location of the map config file which is used by an input file stream to set the config file length (setConfigFileLength()) and content (setConfigContent()). Defining the file length is required for ArcMap services and optional for other services. Note that the Java Connector determines how the config file is processed based on file extension: "axl" defines image or feature service, "mxd" defines ArcMap service. Once the Service object content is set, it can be readded to the ArcIMS site using the addService() method.

    Complete sample code is included below:

    <a href='http://support.esri.com/en/knowledgebase/techarticles/detail/29537' target='_blank'>[O] Complete Sample Code</a>