Developing Web Applications with the Web ADF  

Web ADF Common Data Source API



Previous versions of the Web ADF (pre-9.2), termed the ArcGIS Server ADF, were designed to support a single data source, namely ArcGIS Server via ArcObjects. The new Web ADF extends and enhances data source support in two ways. One, it is designed to support data from multiple sources, including ArcGIS Server and ArcIMS. And two, the multi-source architecture allows you to integrate and interact with data from different sources at the same time, in the same application.

How does the Web ADF support working with multiple data sources?  

The Web ADF uses the Common Data Source API (or Common API) to work with multiple data sources.  The Common API is an integral part of the Web ADF because it provides a generic framework by which a data source can be consolidated and utilized within the Web ADF.   Different data sources can "plug-in" to the Web ADF by implementing classes and interfaces of the generic framework defined via a set of interfaces and classes in the ESRI.ArcGIS.ADF.Web.DataSources assembly\namespace.   Three interfaces provide the implementation foundation of the Common API:

• IGISDataSource
• IGISResource
• IGISFunctionality 

In general, data sources are exposed as resources and functionalities for use in the Web ADF.   A data source can have one or more resources and a resource can have one or more functionalities. 


Data source type determines the type of resources available.  Data source capabililities determine the type of functionalities available via a resource.  The Common API supports a set of standard resource and functionality types for use within the Web ADF by providing a set of interfaces to be implemented by a data source.   The resource interfaces (all implement IGISResource) are listed in the table below:

Resource Description
IMapResource  Implemented for data sources that support generating map data as features or a map image. 
IGeocodeResource Implemented for data sources that support address matching and geolocation.
IGeoprocessingResource Implemented for data sources that support geoprocessing.

A functionality can only be associated with one resource type.  Functionality interfaces (all implement IGISFunctionality) supported for each resource type are listed below:

Map Resource Functionalities Description
IMapFunctionality  Implemented for data sources that support generating a map.
IQueryFunctionality Implemented for data sources that support spatial and attribute queries.
IMapTocFunctionality Implemented for data sources that support generating information for a table of contents.
ITileFunctionality Implemented for data sources that support providing map data via pregenerated map image tiles.
IScalebarFunctionality Implemented for data sources that support providing map scale information.

Geocode Resource Functionalities Description
IGeocodeFunctionality  Implemented for data sources that support address matching.

Geoprocessing Resource Functionalities Description
IGeoprocessingFunctionality  Implemented for data sources that support geoprocessing operations.


To integrate a data source for use within the Web ADF, the Common API generic framework of interfaces for data sources, resources and functionalities must be implemented.   Data source capabilities dictate what can be implemented.  The Web ADF provides Common API implementation libraries for a set of data sources supported out-of-the-box.  These include ArcGIS Server, ArcIMS, ArcWeb, OGC\WMS, and Web ADF Graphics.    The diagram below graphically illustrates the Common API generic architecture, a set of implementations for ArcGIS Server and ArcGIS, and how Web ADF controls and resource managers access data sources via the Common API (discussed later).      



Some data sources, like ArcGIS Server and ArcIMS, have distinct  "data source specific APIs" that are used during the implementation process.   These data source specific APIs can be used on their own, separate from the Common API and include fine-grained access to data source capabilities.   Common API implementations wrap data source capabilities exposed by a data source specific API to integrate it into the Web ADF.  The following table lists the data source type, Common API implementation library, and data source specific API library (if available).


Data Source  Common API Implementation Library Data Source Specific Library
ArcGIS Server ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer.dll ESRI.ArcGIS.ADF.ArcGISServer.dll
ArcIMS ESRI.ArcGIS.ADF.Web.DataSources.IMS.dll ESRI.ArcGIS.ADF.IMS.dll
ArcWeb ESRI.ArcGIS.ADF.Web.DataSources.ArcWebService.dll ESRI.ArcGIS.ADF.ArcWebService.dll
OGC\WMS ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService.dll Not available - Common API implementation library contains all necessary logic
Web ADF Graphics ESRI.ArcGIS.ADF.Web.DataSources.Graphics.dll ESRI.ArcGIS.ADF.Web.dll


While the Web ADF provides the Common API framework to expose generic GIS functionality, some data sources provide custom functionality only accessible via a data source specific API. For example, fine-grained ArcObjects can be accessed via an ArcGIS Server map server object to edit a layer within a personal geodatabase. Likewise, an ArcIMS image service can expose the ability to extract data layers into a zip archive.  For more information on how to access a data source specific API from the Common API implementation classes, see the section titled Accessing a data source specific API.

One of the major benefits of the Common API is the ability to work with many data source in the same (generic) way.   While data source specific APIs provide the foundation for implementation of common capabilities, interfaces in the Common API enable you to work with implementations regardless of the data source type.  One illustration of this capability is that properties and methods on a resource or functionality interface use or return Web ADF (in ESRI.ArcGIS.ADF.Web.dll ) or .NET data types, regardless of whether the underlying data source is an ArcIMS, ArcGIS Server, or ArcWeb service.     In essence, this means you don't necessarily have to know which data source you're working with, only its capabilities.    


How does a data source implement the Common API?

In general, you start with the API used to interact with a data source.  For example, ArcGIS Server offers both Local and Internet connections to services that may utilize the ArcObjects or SOAP API.  Then you start implementing the basic Common API interfaces to expose data source capabilities.  The following discussion will walkthrough the implemenation of an ArcGIS Server data source via a Local connection.

The IGISDataSource interface defines the connection to a specific data source, as well as the identity used to connect and state of the connection.  Data source implementations of IGISDataSource provide access to data source specific connection objects and parameters.   In the diagram below, business objects in the ArcGIS Server APIs implement the IGISDataSource interface in the Common API.  While both implementations maintain common properties, such as Identity and State, they define different connection properties, depending on the data source type.  An ArcGIS Server Local connection requires the use of connection libraries (ESRI.ArcGIS.ADF.dll and ESRI.ArcGIS.ADF.Connection.dll).  ArcGIS Server Internet data sources only require a url (Web service endpoint) so connection libraries are not required.  As a result, a specific IGISDataSource implementation for ArcGIS Server data sources that use Local connections has been created (GISDataSourceLocal).    



Each GISDataSource can have a collection of resources.  In general, a data source defines the type of resource that can be created.  The IGISResource interface defines a generic framework for resources and is implemented by a number of more specific sub interfaces.  Two common resource interfaces are IMapResource and IGeocodeResource.  IMapResource defines the framework for a data source that provides information associated with spatial data in a map, such as the ability to generate a map image, or query layers within a map.  IGeocodeResource defines the framework for a data source that provides the ability to perform address matching.  In the diagram below, the ArcGIS Server implementation of both interfaces creates a MapResource and GeocodeResource class, respectively.  Since it is an ArcGIS Server Local data source, the MapResource also provides access to the map server object and server context.  Likewise, the GeocodeResource provides access to the geocode server object and server context.


 
Each resource can have a collection of functionalities.  In general, a functionality defines the capabilities of a data source as a resource, and how it can be used.  If a resource supports a functionality the resource can create a functionality.  The functionality can then be used to perform an action or series of actions.  In most cases, working with the Common API will involve interacting with functionalities.  The IGISFunctionality interface defines a generic framework for functionalities and is implemented by a number of more specific sub interfaces.   Two common functionality interfaces are IMapFunctionality and IQueryFunctionality.  Both are created by a MapResource.  IMapFunctionality enables interaction with the mapping capability of a resource, such as creating a map image, getting\setting the extent, or changing the visible layers.  IQueryFunctionality enables interaction with the spatial and attribute query capabilities of a resource, such as using a where clause and/or spatial filter to return feature geometry and attributes.   In the diagram below, the ArcGIS Server implementation of both interfaces creates a MapFunctionality and QueryFunctionality class, respectively.  While a MapDescription is unique to the ArcGIS Server implementation of IMapFunctionality, note that most of the methods and properties of a functionality are available at a generic level on the interface.   


How do you use the Common API?
Once an implementation is provided, the Common API can be used by Web ADF controls or programatically to interact with a data source.  Managing interaction with data sources via the Common API is the responsibility of a set of controls termed resource managers.   Resource managers manage a set of resource items and dictate which data sources are available as resources, how the resources are prepared for use, and subsequently how the resources interact with one another.   A resource item (IGISResourceItem) is a container for the resource and maintains other properties, such as display settings for a map resource item.   There is a resource manager control for each resource type.  For example, a MapResourceManager controls manages map resources as map resource items.   We'll discuss how Web ADF controls work with the Common API below.  For more details on programatically utilizing the Common API, see the Resources and Functionalities topic.  In essence, Web ADF controls depend on resource manager controls to expose resources and provide access to data source capabilities via functionalities.

How do the Web ADF controls use the Common API framework to work with data sources?  

You can think of the Web ADF controls as the user interface components, and the Common and data source specific API classes as the part that does most of the GIS work.  The Web ADF controls are similar to other ASP.NET Server controls - they have properties such as height, width, visibility, or anything that relates to arranging the control on a Web form and controlling its appearance.  In addition, the controls generate events based on client interaction which a server-side component can respond to, such as when a control is clicked. For example, in the case of a Map control, the client action might be dragging a box, and the associated server action uses the box to define an extent for the map to zoom to, or selects all features that intersect the box. The action executed on the server is handled by the appropriate functionality. Since each data source, available as a resource within the Web ADF, supports one or more functionalities, the control creates the functionality it needs to do its job.  In this example, the Map control's server action uses a box defined by the client to zoom to an extent.  The Map control displays map data, thus each resource it accesses must be able to generate a map.   If a data source can generate a map and is available via the MapResourceManager as a MapResource, the Map control is able to use its mapping functionality.   The Map control will use each MapResource to generate a MapFunctionality, which it will then use to handle all map-based interaction with the data source.   In this example, the Map control gets the extent defined by the client action to draw a new map image via the MapFunctionality DrawExtent method.  Note, the Map control calls this method for you, you do not need to explicitly call methods on the MapFunctionality for the Map to function.   The diagram below illustrates the creation of a MapFunctionality for a MapResource.  The DrawExtent method on the MapFunctionality is used by the Map control to work with the data source as a MapResource and generate a map image.
~

What happens when there is more than one resource accessed by a control?  

Each resource is associated with a set of functionalities. In our previous example, when the extent is set on the Map control, the control in turn sets the extent for each resource via its associated MapFunctionality. Each resource works with the data source to generate its own output, in this case, a map image. The Map control is also responsible for consolidating MapFunctionality output, or map images, within the same display area.  This means that each resource is treated as a single layer, termed a "resource layer", within a Web ADF Map control (see the Image Blending discussion in the Map control for more details). Again, resource item display settings (e.g. map image transparency) are used by the MapFunctionality to define a rendering scheme for each "resource layer" (map image) so that the content of each "resource layer" is visible in the Map.  The diagram below illustrates the creation of a MapFunctionality for each MapResource consumed by a Map control, and how the Map control works with each MapFunctionality exclusively to generate a map image.

 


What happens when more than one control uses the same set of resources?
As mentioned before, the Web ADF controls and classes support the use of data from multiple sources in the same application. At the same time, multiple Web controls often work with the same set of data sources. How does the Web ADF manage this relationship? One resource manager can be utilized by many controls.  The control is responsible for initializing the resource and create the functionality it needs to do work.   So if you add two Map controls to a Web application and reference the same MapResourceManager, both controls will use the same set of resources, but access different functionalities. By default, the resource will be shared for all controls that utilized them.  The diagram below illustrates how two Map controls work with the same MapResource available via a MapResourceManager.   Each Map creates and uses a MapFunctionality to work with a data source via a shared MapResource.