Working with the Common Data Source API

In this topic

About the Web ADF

Prior to ArcGIS 9.2, the Web Application Developer Framework (ADF)—at that time called the ArcGIS Server ADF—supported a single data source, namely ArcGIS Server via ArcObjects. The current Web ADF extends and enhances data source support in the following ways:
  • It supports data from multiple sources, including ArcGIS Server and ArcIMS.
  • The multisource architecture allows you to integrate and interact with data from different sources at the same time, in the same application.

Multiple data sources and the Web ADF

The Web ADF uses the Common Data Source application programming interface (API) (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 in the Web ADF. Data sources can plug-in to the Web ADF by implementing classes and interfaces of the generic framework defined by a set of interfaces and classes in the ESRI.ArcGIS.ADF.Web.DataSources assembly. The following 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 as shown in the following diagram:
Technically, IGISDataSource describes how the data can be accessed, IGISResource describes the contents of the data, and IGISFunctionality describes what can be done with the data.
Data source type determines the type of resources available. Data source capabilities determine the type of functionalities available via a resource. The Common API supports a set of standard resource and functionality types for use in the Web ADF by providing a set of interfaces that can be implemented by a data source. The resource interfaces (all of which implement IGISResource) are listed in the following table:
Resource
Description
Implemented for data sources that support generating map data as features or a map image.
Implemented for data sources that support address matching and geolocation.
Implemented for data sources that support geoprocessing.
A functionality can only be associated with one resource type. Functionality interfaces (all of which implement IGISFunctionality) that are supported for each resource type are listed in the following tables:
Map resource functionality
Description
Implemented for data sources that support generating a map.
Implemented for data sources that support spatial and attribute queries.
Implemented for data sources that support generating information for a table of contents.
Implemented for data sources that support providing map data via pregenerated map image tiles.
Implemented for data sources that support providing map scale information.
Geocode resource functionality
Description
Implemented for data sources that support address matching.
Geoprocessing resource functionality
Description
Implemented for data sources that support geoprocessing operations.
To integrate a data source for use in 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 that are supported out of the box. These include ArcGIS Server, ArcIMS, OGC\WMS, and Web ADF Graphics.
The following diagram shows 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:
Some data sources, such as 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
ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer
ESRI.ArcGIS.ADF.ArcGISServer
ESRI.ArcGIS.ADF.Web.DataSources.IMS
ESRI.ArcGIS.ADF.IMS
ESRI.ArcGIS.ADF.Web.DataSources.OGCWMSService
Not available. Common API implementation library contains all necessary logic.
ESRI.ArcGIS.ADF.Web.DataSources.Graphics
ESRI.ArcGIS.ADF.Web
While the Web ADF provides the Common API framework to expose generic geographic information system (GIS) functionality, some data sources provide custom functionality that is 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 in 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 Accessing a data source-specific API.
One of the major benefits of the Common API is the ability to work with many data sources 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 example 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 or ArcGIS Server. This means you don't need to know the data source you're working with, only its capabilities.

Data source implementation of the Common API

To have a data source implement the Common API, start with the API used to interact with the data source. For example, ArcGIS Server offers both local and Internet connections to services that can utilize the ArcObjects or SOAP API. Then implement the basic Common API interfaces to expose data source capabilities. This section discusses the implementation of an ArcGIS Server data source via a local connection.

Connections

The IGISDataSource interface defines the connection to a specific data source, the identity used to connect to the data source, and the state of the connection. Data source implementations of IGISDataSource provide access to data source-specific connection objects and parameters. In the following diagram, 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.Local.dll and ESRI.ArcGIS.ADF.Connection.Local.dll. ArcGIS Server Internet data sources only require a uniform resource locator (URL) (the 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 is created (GISDataSourceLocal).

Resources

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 subinterfaces. 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 to query layers in a map. IGeocodeResource defines the framework for a data source that provides the ability to perform address matching.
In the following diagram, the ArcGIS Server implementation of both interfaces creates a MapResource and a GeocodeResource class, respectively:
Since it is an ArcGIS Server local data source, MapResource also provides access to the MapServer and ServerContext objects. Likewise, GeocodeResource provides access to the GeocodeServer and ServerContext objects.

Functionalities

Each resource can have a collection of functionalities. In general, a functionality defines the capabilities of a data source as a resource, as well as 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 involves interacting with functionalities. The IGISFunctionality interface defines a generic framework for functionalities and is implemented by a number of more specific subinterfaces. Two common functionality interfaces are IMapFunctionality and IQueryFunctionality. Both are created by MapResource. IMapFunctionality enables interaction with the mapping capability of a resource, such as creating a map image, getting and 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 or spatial filter to return feature geometry and attributes.
In the following diagram, the ArcGIS Server implementation of both interfaces creates a MapFunctionality and a QueryFunctionality class, respectively:
While a MapDescription is unique to the ArcGIS Server implementation of IMapFunctionality, most of the methods and properties of a functionality are available at a generic level on the interface.

Using the Common API

Once an implementation is provided, the Common API can be used by Web ADF controls or programmatically to interact with a data source. Managing interaction with data sources via the Common API is the responsibility of a set of controls called 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 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 control manages map resources as map resource items.
For more information on programmatically utilizing the Common API, see Resources and functionalities. In general, Web ADF controls depend on resource manager controls to expose resources and provide access to data source capabilities via functionalities.

Using the Common API framework to work with Web ADF controls and data sources

Think of the Web ADF controls as the user interface components and the Common and data source specific API classes as the components that perform most of the GIS work. The Web ADF controls are similar to other ASP.NET Server controls in that they have properties—such as height, width, and visibility—that relate to arranging the control on a Web form and controlling its appearance. In addition, the controls generate events based on client interaction that 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 in 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, so 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 can use its mapping functionality. The Map control uses each MapResource to generate a MapFunctionality, which the Map control then uses to handle all map-based interaction with the data source. The Map control gets the extent defined by the client action to draw a new map image via the MapFunctionality DrawExtent method. 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 following diagram shows 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.

Accessing more than one resource by a control

Each resource is associated with a set of functionalities. In the previous example, when the extent is set on the Map control, the control 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 responsible for consolidating MapFunctionality output, or map images, within the same display area. This means that each resource is treated as a single layer, called a resource layer, in a Web ADF Map control (see the Image blending mode section in the Working with the Map control topic for more details). Resource item display settings (for example, 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 following diagram shows 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:

Using the same set of resources by more than one control

As previously mentioned, 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. The Web ADF manages this relationship by allowing one resource manager to be utilized by many controls. The control initializes the resource and creates the functionality to do its work. For example, if you add two Map controls to a Web application and reference the same MapResourceManager, both controls use the same set of resources but access different functionalities. By default, the resource is shared by all controls that utilize the resource.
The following diagram shows 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 the shared MapResource.