Access a data source specific API

In a basic sense, the Web ADF simply provides you with a set of objects to program with. 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 within 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 which 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 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 illustrated in the following object model diagram.

In general, one or more Web ADF controls can be used within 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, the 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 will interact with the MapResource to generate a map.

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. In essence, 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 the ability to create a map image). The resource manager type dictates the capabilities of a resource it needs to utilize (for example, a MapResourceManager needs to access resources that can create a map). As a result, the Web ADF has a Common API which defines a abstract contract to marshal interaction between the multi-source Web controls and data source specific business objects. More specifically, these contracts are interfaces, such as IGISResource (Resources), IGISFunctionality (Functionalities), and IGISDataSource (DataSources). Each data source type implements these interfaces, and those implementations are utilized by the Web controls to perform tasks.

Each data source has a specific API which defines how you can work with it. ArcGIS Server has two APIs, SOAP and ArcObjects. The ArcIMS API included with the Web ADF manages ArcXML in a library of .NET objects. ArcWeb Services maintain a SOAP API via a Web service endpoint. In each case, the data source API can be used alone, without the Web ADF controls and 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.

In general, the Web ADF works with data sources in a stateless manner. State is not maintained by the data source, instead the data source implementation classes and business objects manage state for you. Each IGISDataSource, IGISResource, and IGISFunctionality may expose data source specific business objects which can be modified. The modifications are maintained in-session by the Web ADF.

For example, a MapResourceManager stores MapResourceInfos that reference resources of type MapResource. A Map knows how to work with a resource of type IMapResource, which implements IGISResource. Each resource in a MapResourceManager is associated with a data source specific MapResource which implements IMapResource. The Map control will create 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 the MapFunctionality.

ArcGIS Server

If working with 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, thus it needs 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, part of the ArcGIS Server SOAP API. Changes to MapDescription are persisted for the session.

ArcGIS Server Internet

ArcGIS Server Local data sources expose access to server context in the MapResourceLocal class via the ServerContextInfo.ServerContext property.   The Web ADF will not manage stateful changes made using server context. Instead, stateful changes will be managed on the server.

ArcGIS Server Local


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 diagrams above. For example, properties on the GeoprocessingResourceLocal class expose the GPServerProxy in the SOAP API and IGPServer and IServerContext in the ArcObjects API.

To work with ArcGIS Server data sources in general, see the section titled Working with the ArcGIS Server SOAP API.

To work with ArcGIS Server Local data sources and access fine-grained ArcObjects, see the section titled Working with the ArcObjects API.

All data source types supported by the Web ADF are designed to 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 (e.g. 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 thus ArcObjects, they can also make stateful changes to a map server object.   The Web ADF controls and Common API are only designed to 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 informing the Web ADF of the changes. Keep in mind that pooled server objects are designed for stateless use.  When working with a pooled server object, a client is unaware of which server object instance is processing a request. And, when the request is finished, the server object is released to handle the next request possibly from a different client.   Non-pooled server objects are designed for stateful changes, but each client works with one server object for the duration of a session.   This can be quite 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. There are three ways to make permanent changes to a map server object:
- Change the map document
  
  Using ArcMap or the ArcGIS Desktop SDK, change the map document (.mxd) and restart the server object
- Change a MapDescription and apply the 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 an IMapDescription and call the IMapServerObjects method ApplyMapDescription.
- 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, like 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.
ArcIMS

If 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, in 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.

To work with ArcIMS data sources, see the section titled Working with the ArcIMS API.

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

If working with an ArcWeb data source, the implementation of the IMapResource in the ESRI.ArcGIS.ADF.Web.DataSources.ArcWebService namespace is referenced.
OGC\WMS Services

OGC\WMS services do not expose any business objects via the Common API implementation classes. It does not maintain a data source specific API. Instead, the data source implementation classes wrap working with OGC\WMS services via raw HTTP GET requests and responses.