Data source-specific APIs

In this topic

About data source-specific APIs
Data source type
Specific APIs
State

ArcGIS Server
ArcIMS
OGC WMS services

About data source-specific APIs

The Web Application Developer Framework (ADF) provides a set of objects for programming. You can use these objects to build desktop and Web applications that access a single resource—such as an ArcIMS service or a data frame in an ArcGIS server object—or multiple resources at the same time. The Web controls and convenience classes expose a set of coarse-grained properties, methods, and events that allow you to interact with common functionality in different resource types. Each type provides a specific implementation to access fine-grained functionality provided in data source-specific application programming interfaces (APIs), such as working with ArcObjects via an ArcGIS Server object, or ArcXML via an ArcIMS service. Once you have access to a data source-specific business object, you can access a greater range of data source-specific capabilities.

The basic architecture of the Web ADF is shown in the following diagram:

Diagram of the Web ADF basic architecture.

One or more Web ADF controls can be used in an ASP.NET Web page. Each control works with a single resource manager, either directly or through another control. The resource manager manages access to one or more resources depending on the type of manager. For example, MapResourceManager manages resources that can generate mapped data, each known as a MapResource.

When a control accesses a resource, it generates a collection of functionalities, depending on the control type. For example, a Map control generates a MapFunctionality for each MapResource in a MapResourceManager. MapFunctionality dictates how the Map control interacts with MapResource to generate a map.

Data source type

The data source type dictates the resource and functionality implementation. The business objects for a data source can be accessed via a functionality or a resource. The Web controls work with resources to create functionalities. Functionalities are classes the Web control can use to perform an action.

The data source type dictates the capabilities of a resource (such as creating a map image). The resource manager type dictates the capabilities of a resource to utilize (for example, MapResourceManager accesses resources that can create a map). The Web ADF has a Common Data Source API (the Common API) that defines an abstract contract to organize interaction between the multisource Web controls and data source-specific business objects. More specifically, these contracts are interfaces, such as the following:

IGISResource (resources)
IGISFunctionality (functionalities)
IGISDataSource (data sources)

Each data source type implements these interfaces, and the implementations are utilized by the Web controls to perform tasks.

Specific APIs

Each data source has a specific API that defines how you can work with it. ArcGIS Server has two APIs: SOAP and ArcObjects. The ArcIMS API that is included with the Web ADF manages ArcXML in a library of .NET objects. In each case, the data source API can be used alone, without the Web ADF controls or the Common API. However, to plug into the Web ADF, each data source must implement the Common API interfaces. These implementations are then utilized by the Web controls to perform actions.

State

The Web ADF works with data sources in a stateless manner. State is not maintained by the data source; rather, the data source implementation classes and business objects manage state. Each IGISDataSource, IGISResource, and IGISFunctionality interface can expose data source-specific business objects that can be modified. The modifications are maintained in-session by the Web ADF.

For example, MapResourceManager stores MapResourceInfos that reference resources of the MapResource type. A Map works with a resource of the IMapResource type, which implements IGISResource. Each resource in MapResourceManager is associated with a data source-specific MapResource, which implements IMapResource. The Map control creates one data source-specific MapFunctionality—which implements IMapFunctionality—to interact with the data source. By default, state is managed in properties and data source business objects available via MapFunctionality.

ArcGIS Server

When working with an ArcGIS Server data source, the implementation of IMapResource in the ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer namespace is referenced. ArcGIS Server Internet data sources are implemented in the MapResourceInternet class. ArcGIS Server local data sources are implemented in the MapResourceLocal class. Both classes expose the ArcGIS Server-specific MapDescription class via a property.

The implementation of IMapFunctionality is in the ESRI.ArcGIS.ADF.Web.DataSources.ArcGISServer namespace. Both ArcGIS Server data source types are implemented in the same MapFunctionality class. By default, MapFunctionality stores state in-session on the client to work with the data source via a stateless API. The ArcGIS Server SOAP API is inherently stateless. The MapDescription property provides access to the MapDescription Value object, which is part of the ArcGIS Server SOAP API. Changes to MapDescription are persisted for the session.

The following diagram shows the ArcGIS Server Internet architecture:

Diagram of the ArcGIS Server Internet architecture.

ArcGIS Server local data sources expose access to server context in the MapResourceLocal class via the ServerContextInfo.ServerContext property. The Web ADF does not manage stateful changes made using server context. Stateful changes are managed on the server.

The following diagram shows the ArcGIS Server local architecture:

Diagram of the ArcGIS Server local architecture.

MapFunctionality is the only functionality type designed to maintain state, so it provides access to the data source-specific ArcGIS Server SOAP API. Web ADF resource types for ArcGIS Server use the same architecture illustrated by the map resource in the previous diagrams. For example, properties on the GeoprocessingResourceLocal class expose the GPServerProxy in the SOAP API and IGPServer and IServerContext in the ArcObjects API.

All data source types that are supported by the Web ADF work with services in a shallowly stateful manner. This means that the client (Web ADF) makes temporary changes to a data source for the duration of a request using properties managed by the client (for example, session state). In the process, the server remains unchanged.

The option to make permanent changes to the server (or server object) is only available when using ArcGIS Server map services. However, to change the state of the map server object you need to have access to fine-grained ArcObjects running on the server. Since ArcGIS Server local data sources have direct access to server context, and ArcObjects, you can also make stateful changes to a map server object using them. The Web ADF controls and Common API only work with data sources in a shallowly stateful manner. As a result, when changing the state of a map server object, you are responsible for making the changes in the Web ADF.

Pooled server objects are stateless. When working with a pooled server object, the server object instance that is processing a request is not obvious to the client. When the request is finished, the server object is released to handle the next request, possibly from a different client. Non-pooled server objects use stateful changes, but each client works with one server object for the duration of a session. This can be expensive when attempting to balance availability and resource usage on the server. Technically, stateful changes can be made to a map server object, regardless of pooling properties.

The following options are available to make permanent changes to a map server object:

Change the map document—Using ArcMap or the ArcObjects Software Development Kit (SDK), change the map document (.mxd) and restart the server object.
Change MapDescription and apply MapDescription to the server object—In the Web ADF, modify the MapDescription value object (part of the SOAP API) and call the ApplyMapDescriptionToServer() method on the MapResourceLocal instance. Using the ArcObjects API, change IMapDescription and call the ApplyMapDescription method on IMapServerObjects.
Change fine-grained ArcObjects and refresh the server object—In the Web ADF, work with fine-grained ArcObjects using methods on IMapServerObjects. Make a change, such as adding a layer or changing a layer renderer, then call the RefreshServerObjects() method on the MapResourceLocal instance. When using the ArcObjects API, call the RefreshServerObjects() method on the IMapServerObjects interface.

For more information about ArcGIS Server data sources in general, see Working with the ArcGIS Server SOAP API.

For more information about ArcGIS Server Local data sources and accessing fine-grained ArcObjects, see Working with the ArcObjects API.

ArcIMS

When working with an ArcIMS data source, the implementation of IMapResource in the ESRI.ArcGIS.ADF.Web.DataSources.IMS namespace is referenced. The ArcIMS MapResource class exposes the ArcIMS-specific MapService and MapView classes via properties. The implementation of IMapFunctionality is in the same namespace—the MapFunctionality class. The ArcIMS API is inherently stateless because the ArcIMS server does not maintain state. The MapView property provides access to the MapView object in the ArcIMS API. Changes to the MapView are persisted for the session.

The following diagram shows the ArcIMS API architecture:

GeocodeFunctionality provides access to MapView. Other Web ADF functionality types are dependent on the map resource, which exposes MapView. Web ADF resource types for ArcIMS use the same architecture illustrated by the map resource in the previous diagrams.

For information on working with ArcIMS data sources, see Introduction to the ArcIMS API.

OGC WMS services

Open Geospatial Consortium (OGC) Web Map Service (WMS) services do not expose business objects via the Common API implementation classes. It does not maintain a data source-specific API. The data source implementation classes wrap working with OGC WMS services via raw Hypertext Transfer Protocol (HTTP) GET requests and responses.