The Connection library is a .NET assembly (ESRI.ArcGIS.ADF.Connection.dll) included with the Web ADF and other ESRI developer products.   It provides Microsoft .NET developers with a single library for connecting to ArcGIS Server locally via the Server Object Manager and ArcIMS via HTTP and TCP.   The Connection library also contains a connection manager to configure fail-over and round-robin capabilities in a custom application.  

Connecting to a server

Implementation and usage discussions, as well as sample code, for connecting to ArcGIS Server and ArcIMS are located in their respective developer API sections.  

Working with Connection Manager

The connection library includes a connection manager to enhance the capabilities of an application by providing techniques to create a fail-safe and performant solution.  You can group a collection of connections to handle application requests for a resource.  In the case, the application only needs needs access to the resource, the connection manager determines which server is used to retrieve the data.  Two options are provided:

1. Fail-over
   
   Fail-over solutions are designed to ensure that service requests are always channeled to a working connection\server.  All requests are sent to a primary server, unless it is unavailable or a request fails, then a secondary server is used. 
   
2. Round-robin
   
   Round-robin solutions are designed to make efficient use of the available servers to handle high request volumes.  Both primary and secondary servers are used to service requests.  Servers are used in sequence, with the first request sent to the primary server, the second request to the secondary server, and so on. 
   

Connection manager capabilities can be utilized in two ways: using the Web ADF resource manager dialogs to configure connections for a Web application or programmatically create and assign connections to a ConnectionManager instance.
 

Web ADF resource manager dialogs

The Web ADF uses the Connection library to create and manage connections for both ArcGIS Server Local and ArcIMS data sources.   The resource manager controls (MapResourceManager, GeocodeResourceManager, and GeoprocessingResourceManager) will provide a Data Source Definition dialog to define the primary server connection for a resource.  For ArcGIS Server Local and ArcGIS dialogs, the option to configure connection manager capabilities is available in an Advanced Settings dialog.    

ArcIMS data sources


                                  




ArcGIS Server Local data sources


                                 



When finished configuring connections, a ConnectionManager.xml file is created in the Web application root folder.  There is only one ConnectionManager.xml per Web application.  The file is used to store the properties defined in the Advanced Settings dialogs.  If the file is available at design-time, the Web ADF reads the content of the xml file to populate the Advanced Settings dialogs.  The primary connection property is the unique key for connections defined in an application.  At runtime, the data source uses the xml file to establish which servers are available for resource requests.   An example ConnectionManager.xml is included below:
 

<?xml version="1.0"?>
<ESRI.ArcGIS.ADF.Connection>
  <ConnectionManager>
    <Connection primary="server1@5300" serverType="ArcIMS" mode="RoundRobin" maxAttempts="20" failedCheckInterval="5">
      <Alternate>server2@5300</Alternate>
      <Alternate>server3@5300</Alternate>
    </Connection>
    <Connection primary="server1" serverType="ArcGIS" mode="Failover" maxAttempts="20" failedCheckInterval="5">
      <Alternate>server2</Alternate>
      <Alternate>server3</Alternate>
    </Connection>
  </ConnectionManager>
</ESRI.ArcGIS.ADF.Connection>
						

In this example, an ArcIMS TCP and ArcGIS Server Local connection have been configured to be managed for Web ADF components in the respective Web application.  For all ArcIMS TCP connections that use server1@5300 as their primary server, server2@5300 and server3@5300 will also be accessed using the round-robin mode.    Any resource manager that defines server1@5300 as the primary connection will use this configuration.

The ArcGIS Server Local connection defined in this example, the primary connection server1 will be accessed, until a failure occurs.  If a failure occurs, the next alternate server, server2, will be used.  The failedCheckInterval parameter defines the amount of time in minutes the connection manager will wait to check the primary connection to see if it is available.  The maxAttempts parameter defines the number of attempts to check if the primary connection becomes available.

Programmatic Use

Managing connections with the ConnectionManager involves working with a set of classes in the ESRI.ArcGIS.ADF.Connection library.  In general, connections are added and maintained in a ConnectionManager.  A connection is subsequently retrieved from the same ConnectionManager depending on the connection mode (round-robin, failover, default).  Each connection has the option of maintaining a list of alternate connection items which simply define an alternate server from which to create a connection.  Alternates are only used when the connection mode is round-robin or failover.   Consider the following classes and properties when configuring a connection manager:

ConnectionManager

A ConnectionManager's connections and properties can be configured via an xml file (e.g. see ConnectionManager.xml in the previous section) or added programmatically.  The constructor provides an option for specifying the path to an xml file as well as a default identity to be used for managed connections (if they have not specified an identity).  Once a ConnectionManager is configured, connections are retrieved via the ServerConnection() method.  The ServerConnection() method requires two parameters, the connection name and type.  It contains logic for managing connections via the defined connection mode.   The ServerConnection() method should return an active ArcGIS Server (ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection) or ArcIMS (ESRI.ArcGIS.ADF.Connection.IMS.IMSServerConnection) connection.   The following table lists important ConnectionManager methods:          

Method Name	Returns	Description
Add(Connection)	void	Add a new Connection instance.  Add ConnectionItems to the Connection instance before adding it to the ConnectionManager.
Find(name, type)	Connection	Find a Connection instance using name and server type.
ReadXML(XmlDocument)	void	Load an xml document with ConnectionManager configuration information.
Remove(Connection)	void	Remove a Connection instance from the ConnectionManager.
ServerConnection(name, type)	IServerConnection	Use a Connection instance to create an active connection to ArcGIS Server or ArcIMS.  Specify the name of the primary Connection and the server type.  If the name does not reference an existing Connection, a new Connection will be created.  The new Connection will use the default connection mode and the ConnectionManager identity (if set).

Connection

The Connection class is used to define the primary connection to a server.  Each Connection is associated with a unique name used to define the primary server with which it will connect.  See the Name property in the table below for more information.  A Connection instance may also store the identity used when connecting, the connection mode, and parameters for retrying failed connections.  The following table lists Connection properties: 

Property Name	Type	Description
ActiveConnectionItemIndex	int	For round-robin connection modes, this provides the current active index of the Connection item (0-number of items).  The primary connection returns -1.   Other connection modes also return -1.
ConnectionMode	ConnectionMode	Three types: RoundRobin, Failover, Default RoundRobin - Each server (name), defined for the primary Connection and any alternate ConnectionItems, will be used to create a connection in sequence. Failover - Only one server (name) will be used at a time. If a connection fails, the next connection (either primary Connection or ConnectionItem) will be used to define a server from which to create a connection.  The first attempt will always use the primary Connection.    Default - Only the primary Connection will be used to create a connection.
FailedCheckInterval	int	The number of failed attempts to create a connection (from primary and alternate options) before checking the status of failed connections.  Valid for round-robin and failover modes only.  Default value is 5.  For example, if four servers are associated with one Connection, and you want to wait until three servers fail before attempting to reconnect to any of the failed servers, set the value of FailedCheckInterval to 3.   If set to 0, the Connection will attempt to reconnect to any server that has failed when it becomes available in the connection cycle (round-robin or failover).  The default maximum number of attempts by a Connection to connect to any server in its list of server names is 20.   This will require at least 20 different server names associated with a single Connection instance to become a factor.  This value can only be changed via a Connection constructor - no public propery is available.  In most cases, this value will not need to be changed.
Identity	Identity	The identity used by the Connection and subsequent ConnectionItems.  Valid for ArcGIS Server and ArcIMS HTTP connections.
Items	ConnectionItemCollection	Use to add or remove ConnectionItem instances to a Connection.
Name	string	The name of the connection is determined by the server type.  For ArcGIS Server Local connections it is the machine name on which an ArcGIS Server SOM is available.  For ArcIMS TCP connections it is the machine name and port on which an ArcIMS Application Server is available.  For ArcIMS HTTP connections it is the url to the ArcIMS Servlet connector. Use the name to uniquely identify a Connection instance when using the ConnectionManager to create a connection.
ServerType	string	Two valid values:  "ArcGIS" for ArcGIS Server connections, "ArcIMS" for ArcIMS connections.

ConnectionItem

A Connection can also maintain a list of ConnectionItems, each referencing an alternative connection name.  When the connection mode is round-robin or failover, each ConnectionItem associated with a Connection may be used.  It is important to note that the services available on a server referenced by a ConnectionItem should match the primary Connection.   The following table list ConnectionItem properties:

Property Name	Type	Description
Name	string	The same as the Connection.Name property except the ConnectionItem defines an alternative server for a Connection.

How to use the ConnectionManager
 
The following steps will provide a quick overview of how to utilize the ConnectionManager in a custom application.  Any application type can take advantage of connection manager capabilities, including Web, desktop, and console applications.  Assuming you have already created a Visual Studio project, do the following:

1. Add references to the connection libraries: ESRI.ArcGIS.ADF.dll and ESRI.ArcGIS.ADF.Connection.dll
2. Create a ConnectionManager instance and persist it for the duration of a user's session.  If a Web application, store it in session.  If a desktop or standalone application, create as a member variable or expose via a static class.  In essence, you only want to create and populate the ConnectionManager once, then access when needed.
   
   [C#]

   ESRI.ArcGIS.ADF.Connection.ConnectionManager m_ConnectionManager = 
     new ESRI.ArcGIS.ADF.Connection.ConnectionManager(null);
   

3. Configure connection properties and add to the connection manager.  Create a new Connection class by defining a server name and type.  The Connection class defines the default (primary) server to use.  Define the connection mode to determine if alternative connection items are needed.  Round-robin and failover modes should include Connection Items as alternative servers for a Connection.  Add each ConnectionItem to a Connection class, then add the Connection class to the ConnectionManager.  A ConnectionManager can manage multiple Connection instances of different server types, therefore you can manage multiple ArcGIS Server and ArcIMS connections via the same ConnectionManager.  Alternatively, create an xml file with connection properties and load it into the ConnectionManager.    At this point the ConnectionManager is ready to be used.  
   
   [C#]

   // Define identity to use when connecting to server
   ESRI.ArcGIS.ADF.Identity agsIdentity = new ESRI.ArcGIS.ADF.Identity("user",
       "password", "domain"); 
   
   // Create and define primary Connection
   ESRI.ArcGIS.ADF.Connection.Connection primaryConnectionArcGIS = 
       new ESRI.ArcGIS.ADF.Connection.Connection("primaryserver",
       ESRI.ArcGIS.ADF.Connection.ConnectionMode.RoundRobin, agsIdentity, 3, 3);
   primaryConnectionArcGIS.ServerType = "ArcGIS";
   
   // Add alternative servers to primary Connection
   primaryConnectionArcGIS.Items.Add(new 
       ESRI.ArcGIS.ADF.Connection.ConnectionItem("mirrorserver1"));
   primaryConnectionArcGIS.Items.Add(new 
       ESRI.ArcGIS.ADF.Connection.ConnectionItem("mirrorserver2"));
   
   // Add Connection to ConnectionManager
   m_ConnectionManager.Add(primaryConnectionArcGIS);
   

4. Use the ConnectionManager to retrieve a valid connection.  The ConnectionManager will attempt to return an active connection.  Regardless of which mode is defined (e.g. round-robin, failover, default), the server name of the default (primary) Connection is used to identify which connection to return.  The ConnectionManager.ServerConnection() method will return an active ArcGIS Server Local or ArcIMS connection (both implement IServerConnection) which can be used to communicate with a service.  Note that the connection must be disposed when finished (IServerConnection.Dispose()).
   
   [C#]

   ESRI.ArcGIS.ADF.Connection.IServerConnection serverConnection = m_ConnectionManager.  
     ServerConnection("primaryserver", "ArcGIS");
   
   // A connection should be returned alive (connected)
   bool isAlive = serverConnection.IsAlive();
               
   // Cast to the appropriate connection type:
   // ArcGIS - ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection
   // ArcIMS - ESRI.ArcGIS.ADF.Connection.IMS.IMSServerConnection
   ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection agsConnection = 
     (ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection) serverConnection;