Working with Resources and Functionalities

The following section describes how a GIS data source can be utilized in the Web ADF. Data sources can provide access to geospatial information, analysis, and processing capabilities. They are exposed as services or file based sources. In the Web ADF, data sources are consumed in the Web ADF as resources. Each data source can have different capabilities, which define the type of resource they provide. The Web ADF supports three resource types: Map, Geocode, and Geoprocessing. In addition, one resource can be used in different ways, thus resources support different functionalities. Functionalities are used by Web ADF controls and programmatically to work with a data source. The capabilities of a data source define the types of functionalities available. The Web ADF supports the following functionalities: Map, Query, Tile, MapToc, ScaleBar, Geocode, and Geoprocessing. The foundation of the Web ADF's ability to consolidate and utilize multiple data sources is founded in the ability to work with a common, defined set of resources and functionalities.

We will start with a discussion on how resources are generated and managed in the Web ADF. Resources are initialized and managed by resource manager controls: MapResourceManager, GeocodeResourceManager and GeoprocessingResourceManager. Each resource manager maintains a resource collection. Resources can be added at design-time in Visual Studio or programmatically at runtime.

Creating resources at design-time

A set of resource manager controls offer design-time dialogs you can use to reference different types of data sources in your application. These include the MapResourceManager, GeocodeResourceManager, and GeoprocessingResourceManager. You can add a resource as a ResourceItem to a resource manager's resource collection and define its properties using a collection editor dialog. The Definition property in these controls contains connection information for each data source type. For example, map resources have a DisplaySettings property to set a variety of map image output options, such as map visibility, toc visibility and transparency. Other resource managers contain appropriate property settings for the resource type. The resource instance for the resource item is generated as needed at runtime.

Creating resources programmatically at runtime

To work with resources programmatically, create a resource item, set its properties, and add it to a resource manager. A resource item is used by a resource manager to create a resource. Each resource manager has its own resource item type that extends GISResourceItem. For example, a MapResourceManager uses a MapResourceItem to create a map resource. Properties of the MapResourceItem will provide the MapResourceManager with the information it needs to create the resource. Note, although a resource instance can be created without using a resource manager, it is not recommend at this time.

The following code sample illustrates how a new MapResourceItem is used create a map resource. All resource items have a definition. The definition (GISResourceItemDefinition) provides information about data source type and location as well as the specific resource or service to access. Map resource items also maintain display settings (DisplaySettings) to set properties on the map generated by the resource. These settings are often used to determine how the resource will be rendered with other resources in a Map control. The resource item is added to the resource manager's ResourceItems collection and the CreateResource method initializes the resource for use.

[C#]

MapResourceItem mapResourceItem = new MapResourceItem();

GISResourceItemDefinition definition = new GISResourceItemDefinition();                
definition.DataSourceDefinition = "http://localhost/arcgis/services/";
definition.DataSourceType = "ArcGIS Server Internet";
definition.ResourceDefinition = "Layers@USA_data";
mapResourceItem.Definition = definition;

ESRI.ArcGIS.ADF.Web.DisplaySettings displaysettings = 
    new ESRI.ArcGIS.ADF.Web.DisplaySettings();
displaysettings.Transparency = 50.0F;
displaysettings.Visible = true;
mapResourceItem.DisplaySettings = displaysettings;

MapResourceManager1.ResourceItems.Insert(0, mapResourceItem);
mapResourceItem.InitializeResource();

The following sample provides a detailed example of adding and removing resources programmatically at runtime:
Sample: Common_AddDynamicData

Initializing resources

If a resource manager is being used by another Web control (e.g. MapResourceManager consumed by a Map), resources within a resource manager are always initialized when the Web application initializes.  A full page postback will also trigger the initialization of map resources. However, since Web ADF controls are AJAX enabled, most interaction with a Web application will involve numerous callbacks.  During a callback, map resources may not be initialized, because the cost of resource initialization on every callback to the Web application can be expensive. This streamlines resource utilization to make it more intelligent, but requires the developer to check whether a resource is initialized or not.

There are two techniques for retrieving a resource in the Web ADF:

1) Via a functionality
2) Via a resource manager

If accessing a resource via a functionality, the resource should be initialized for you. For example, if you call GetFunctionality on a Map control, the resource associated with the functionality will be initialized for you.

If accessing a resource via a resource manager, the resource is not necessarily initialized. In this case you should check the initialization status of the resource manager or resource and initialize before using.  To initialize a resource manager (and thus all resources it manages), use the following code as an example:

[C#]

if (! MapResourceManager1.Initialized)
{
   MapResourceManager1.Initialize();
}
IGISResource gisResource = MapResourceManager1.GetResource("Map Resource");

To initialize an individual resource and create a functionality (e.g. QueryFunctionality), use the following code as an example:

[C#]

MapResourceItem mapResourceItem = MapResourceManager1.ResourceItems.Find("Map Resource");
IGISResource gisResource = mapResourceItem.Resource;

if (!gisResource.Initialized)
    mapResourceItem.InitializeResource();

// Create a Common Data Source API QueryFunctionality object to use for querying the resource    
IQueryFunctionality commonQueryFunctionality = (IQueryFunctionality)gisResource.CreateFunctionality(
  typeof(IQueryFunctionality), null);

The capability of a data source determines how a resource in the Web ADF can be used. The capabilities of a data source are reflected in Web ADF functionalities. Web ADF controls are designed to use resources to create functionalities to work with the capabilities of a data source. Thus, Web ADF controls and Web ADF developers can use functionalities to work with a resource to generate results.

The following diagrams illustrate how a Map control creates a separate MapFunctionality for each MapResource during Web application initialization. When the Map control needs to interact with a data source, such as drawing a new extent, it uses the MapFunctionality.

Some functionalities are implicitly created for a Web ADF control while others must be explicitly created. For example, a Map control creates a MapFunctionality from a MapResource when the Map control is loaded (during page load). The MapResource can also be used to create a QueryFunctionality to query features in a MapResource layer. If a resource manager was initialized programmatically, functionalities created from its resources must also be explicitly initialized. See the resource discussions below for the functionalities that can be created from a resource.

There is a one-to-many relationship between resources and functionalities\Web ADF controls. One resource can be consumed and utilized by many controls and thus create multiple functionalities. This resource-centric model provides a consolidated framework for managing access to data source capabilities. You only need to add and configure a resource once, then you can consume it as often as necessary.

If a data source provides a type of resource, it will implement the appropriate interfaces. The namespaces for data source specific resource implementations are included in the data source discussion . The namespace for the generic interfaces that make up the Web ADF Common Data Source API is ESRI.ArcGIS.ADF.Web.DataSources . The resource and functionality discussion below will focus initially on two interfaces in this namespace:

IGISResource

Common interface for all resource interfaces and implementation classes. This interface defines the generic methods and properties to create functionalities, check if a functionality is supported by a resource, get a reference to the data source, and get the collection of functionalities associated with a resource.
IGISFunctionality

Common interface for all functionality interfaces and implementation classes. This interface defines the generic methods and properties to initialize a functionality and get a reference to its resource or control.

Each data source supports one or more resources. Each resource supports one or more functionalities. In most cases, you will work with methods on a functionality to do work. Note that a functionality can only be created by one resource type. For example, a MapFunctionality can only be created by a MapResource. As a result, the section below will discuss the three resource types included with the Web ADF: MapResource, GeocodeResource, GeoprocessingResource; as well as a detailed discussion on the functionality types they support.