Connecting to ArcIMS and Working with ArcXML

The .NET ArcIMS API provides a comprehensive framework for interacting with an ArcIMS server.  Server connections can be established via HTTP with optional authentication credentials.  TCP connections are available with LAN  (local area network) access to an ArcIMS Application Server.   Once a connection has been established, developers can use the .NET ArcIMS API classes to build and process requests and responses, or they can send ArcXML requests and receive ArcXML responses directly.  Sending custom ArcXML requests directly to ArcIMS may be required when complete control over ArcXML content is needed.  

Establishing a Connection to ArcIMS

In the IMS namespace of the Web ADF connection library (ESRI.ArcGIS.ADF.Connection.dll), two classes can be used to establish a connection to ArcIMS: TCPConnection and HTTPConnection.  The TCPConnection class is used to create a connection to an ArcIMS Application server via TCP.  The HTTPConnection class is used to create a connection to ArcIMS via a Web server and the ArcIMS Servlet Connector.  Depending on the protocol used to connect to ArcIMS, a number of properties need to be set to initialize the connection.  If connecting via HTTP, the Web server URL is defined as a parameter of the HTTPConnection constructor and the ServiceName defines the ArcIMS service ArcXML requests will be sent to.  If authentication is enabled on the Servlet Connector, the credentials can be provided via the User and Password properties on the connection object.

HTTPConnection connection = new HTTPConnection("http://webservername");
connection.Port = 80; 
connection.User = "private";
connection.Password = "pass.word";
connection.ServiceName = "MyServiceName";

The Port property is optional.  The default is port 80.  Set it to the appropriate Web server port if it is different than the default.  Note that the URL provided to the HTTPConnection constructor can define the full path to the servlet connection.  By default, it appends the path "servlet/com.esri.esrimap.Esrimap" onto the URL provided.  If the Servlet Connector does not use the default path, define it in the URL.

If connecting via TCP, the Host property defines the machine name or IP address of the machine on which the ArcIMS application server is running.  The Port property specifies the connector port on which the ArcIMS Application server is listening for incoming requests.  The ServiceName property defines which ArcIMS service ArcXML requests will be sent to. User and Password do not apply to TCP connections. 

TCPConnection connection = new TCPConnection();
connection.Host = "myserver";
connection.Port = 5300;
connection.ServiceName = "MyServiceName";

Get a list of services

Both the TCPConnection and HTTPConnection classes derive from the IMSServerConnection abstract base class which provides one method to retrieve a list of services running on an ArcIMS server: ClientServicesArray.  ClientServicesArray returns a System.Collection.ArrayList which you can iterate through to get a list of services.

System.Collections.ArrayList arraylist = connection.ClientServicesArray(); 
IEnumerator arrayenum = arraylist.GetEnumerator(); 
while (arrayenum.MoveNext())
{ 
  string servicename = (string) arrayenum.Current; 
}

Send an ArcXML Request and Get the ArcXML Response

The IMSServerConnection abstract base class provides the Send method for sending raw ArcXML requests to ArcIMS services.  The Send method permits sending an ArcXML request to the default service type (an Image Service), or a custom service type.  Custom service types include: Query, Geocode, and Extract.  Listed below are the ArcXML request types and their respective custom service types: 
 

The Send method returns a string containing the ArcXML response to the ArcXML request.   A few examples are listed below:

Send a GET_IMAGE request:

connection.ServiceName="world";
string getimage_request = "<?xml version = \"1.0\" encoding=\"UTF-8\"?>
<ARCXML version= \"1.1\"><REQUEST><GET_IMAGE><PROPERTIES><ENVELOPE minx= \"-13.62\" 
miny=\"33.91\" maxx= \"53.62\" maxy=\"73.33\" /><IMAGESIZE width=\"600\" height=\"400\" /> 
</PROPERTIES></GET_IMAGE></REQUEST></ARCXML>";
string response=connection.Send(getimage_request);

Send a GET_FEATURES request:

connection.ServiceName="world";
string getfeatures_request = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<ARCXML version=\"1.1\"><REQUEST><GET_FEATURES outputmode=\"xml\" >
<BR><LAYER id=\"1\"></LAYER><SPATIALQUERY subfields= \"NAME\" >
<BR><SPATIALFILTER relation= \"area_intersection\" >
<MULTIPOINT><POINT x=\"-102.31884\" y=\"62.31884\" />
</MULTIPOINT></SPATIALFILTER></SPATIALQUERY></GET_FEATURES>
</REQUEST></ARCXML>";
string response=connection.Send(getfeatures_request,"Query"); 

Process an ArcXML Response

Since ArcXML is based on the XML standard, common XML processing tools and methods can be used to interrogate the ArcXML content.  The following steps can be used to process an ArcXML response:

1. Create an XML document.
2. Load the ArcXML response into the document.
3. Search on the ArcXML element or node.
4. Search for an attribute value.

In the following example, a SERVICES response is processed - GETCLIENTSERVICES was the ArcXML request. A typical SERVICES response would look similar to the following. In the example below, two services are available: an Image Service named "world" and an ArcMap Image Service named "north_america".

<?xml version="1.0"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICES>
      <SERVICE name="world" servicegroup="ImageServer1" access="PUBLIC" type="ImageServer" version="" status="ENABLED" >
        <IMAGE type="PNG8" />
        <ENVIRONMENT>
          <LOCALE country="US" language="en" variant="" />
          <UIFONT name="Arial" />
        </ENVIRONMENT>
        <CLEANUP interval="20" />
      </SERVICE>
      <SERVICE name="north_america" servicegroup="ImageServerArcMap1" access="PUBLIC" type="ImageServer" version="ArcMap" status="ENABLED" >
        <IMAGE type="PNG" />
        <CLEANUP interval="20" />
      </SERVICE>
    </SERVICES>
  </RESPONSE>
</ARCXML>

This response is loaded into an XML document.  Note that a reference to the System.XML namespace must be made in order to parse an XML document.   The document is then searched for all SERVICE nodes. For each SERVICE node, a search is made for the name attribute value.

XmlDocument doc=new XmlDocument();
doc.LoadXml(response);
XmlElement root = doc.DocumentElement;
XmlNodeList nodelist=root.GetElementsByTagName("SERVICE");
foreach (XmlNode node in nodelist)
{
  string name=node.Attributes["name"].InnerXml;
}