Developing Web Applications with the Web ADF  

Using the Connection Library




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 high-performance solution.  You can group a collection of connections to handle application requests for a resource.  In the case, the application only 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.  For all ArcGIS Server Local connections, the primary connection to server1 will be used until a failure occurs.  If a failure occurs, the next alternate server, server2, will be used.  The failedCheckInterval parameter defines the number of requests after the failure the connection manager will wait to check the primary connection to see if it is available.  The maxAttempts parameter defines the maximum 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 After a connection fails, this value defines how many requests can be made to the application before checking the status of the failed connection.  Valid for round-robin and failover modes only.  Default value is 5. 

For example, assume you set the FailedCheckInterval to 3.  If two servers are associated with one Connection and the primary server is unavailable, the secondary server will be used exclusively until the third request to the Connection.  During the third request , the Connection will attempt to reconnect and failed connections, in this case to the primary server.   If unsuccessful, the Connection will wait another three requests to try again until reaching the maximum number of attempts (MaxAttempts).   If set to 0, the Connection will attempt to reconnect to any server that has failed during each request. 

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 property 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;