Resources and functionalities in the Web ADF

Summary This topic describes how a geographic information system (GIS) data source can be utilized in the Web Application Developer Framework (ADF).

In this topic

About resources and functionalities 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. 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 the following resource types:
  • Map
  • Geocode
  • Geoprocessing
In addition, a single resource can be used in multiple ways and support multiple functionalities.
Functionalities are used by Web ADF controls as well as 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
  • Geoprocessing
The Web ADF's ability to consolidate and utilize multiple data sources is founded on the ability to work with a common, defined set of resources and functionalities.
For more information about data sources, see Working with data sources.

Creating and managing resources

Resources are initialized and managed by the following resource manager controls:
Each resource manager maintains a resource collection. Resources can be added at design time in Visual Studio as well as programmatically at run time.

Creating resources at design time

The previously-mentioned resource manager controls offer design-time dialogs you can use to reference various types of data sources in your application. You can add a resource as a ResourceItem to a resource manager's resource collection and define its properties using a collection editor dialog box.
The Definition property in the resource manager 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 manager controls contain appropriate property settings for their respective resource type. The resource instance for the resource item is generated as needed at run time.

Creating resources programmatically at run time

To work with resources programmatically, you need to 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, MapResourceManager uses MapResourceItem to create a map resource. Properties of MapResourceItem provide MapResourceManager with the information it needs to create the resource. Although a resource instance can be created without using a resource manager, it is not recommend.
The following code sample shows how a new MapResourceItem is used create a map resource:
[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();
Each resource item has 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 is 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.
For a detailed example of adding and removing resources programmatically at run time, see Sample: Common_AddDynamicData.

Initializing resources

If a resource manager is being used by another Web control (for example, Map consuming MapResourceManager), resources in a resource manager are initialized when the Web application is initialized. A full page postback also triggers the initialization of map resources. However, since Web ADF controls are Asynchronous JavaScript and XML (AJAX) enabled, most interaction with a Web application involves numerous callbacks. During a callback, map resources might 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 you to check whether or not a resource is initialized.
You can retrieve a resource from the Web ADF in the following ways:
  • Through a functionality
  • Through a resource manager
If you're accessing a resource through a functionality, the resource is initialized for you. For example, if you call GetFunctionality on a Map control, the resource associated with the functionality is initialized for you.
If you're accessing a resource through a resource manager, the resource is not necessarily initialized. In this case, check the initialization status of the resource manager or resource and initialize before use. To initialize a resource manager (and 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 (for example, 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 query the resource.
IQueryFunctionality commonQueryFunctionality = (IQueryFunctionality)
    gisResource.CreateFunctionality(typeof(IQueryFunctionality), null);

Creating and managing functionalities

The capabilities of a data source determine how a resource in the Web ADF can be used and are reflected in Web ADF functionalities. Web ADF controls use resources to create functionalities to work with the capabilities of a data source. Web ADF controls as well as Web ADF developers 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 interacts with a data source, such as when drawing a new extent, it uses the MapFunctionality as shown in the following diagram:
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 is initialized programmatically, functionalities created from its resources must also be explicitly initialized.
There is a one-to-many relationship between resources and functionalities and Web ADF controls. One resource can be consumed and utilized by many controls and 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.

Data source interfaces

If a data source provides a type of resource, it implements the appropriate interfaces. The namespaces for data source-specific resource implementations are included in the Working with data sources topic. The namespace for the generic interfaces that make up the Web ADF Common Data Source API (the Common API) is ESRI.ArcGIS.ADF.Web.DataSources. The two main interfaces in this namespace are described as follows:
  • IGISResource—Common interface for all resource interfaces and implementation classes. This interface defines the generic methods and properties to create functionalities, checks if a functionality is supported by a resource, gets a reference to the data source, and gets 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 gets a reference to its resource or control.
Each data source supports one or more resources, and each resource supports one or more functionalities as shown in the following diagram:
In most cases, you'll work with methods on a functionality to perform work. A functionality can only be created by a single resource type. For example, a MapFunctionality can only be created by a MapResource.


See Also:

Data source-specific APIs
Map resources
Geocode resources
Geoprocessing resources
Working with data sources