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 ArcGIS Server 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 availablility 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, whic 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.
