Resource Domains

Resource Domains

Resource Domain Lookups

Adapter Check Value Callbacks

A resource domain defines the domain of valid values for metadata parameters, based on rules and/or data that are specific to the adapter resource. Resource domains can have properties that affect the behavior of the resource domain, and associations with the metadata parameters.

You can use resource domain values to:

Assign default values for parameters.

Enable the adapter to look up parameter values in the adapter resource.

Enable the users of the adapter to supply their own parameter values, and enable the adapter to validate these values.

Disable parameters, based on specified sets of values in other parameters.

A common use of resource domain values is to create a dropdown list of data values for a parameter, much like the WmDescriptor.setValidValues method in connection factories. However, the resource domain values differ from the setValidValues lists in two important ways:

Resource domain values can interact with the adapter service editor.

As values in one parameter change, callbacks are made to the adapter to update the resource domain values. For example, if parameter A contains a list of database table names, and parameter B contains a list of column names, then when a table is selected in parameter A, the resource domain values used in parameter B can be updated to reflect the columns from the table selected in parameter A.

Resource domain values can be retrieved directly from the adapter resource, using a WmManagedConnection instance.

To create a resource domain:

1. Register the resource domain and its properties in your WmManagedConnection implementation.

2. Associate the adapter's metadata parameters with the resource domain.

3. Populate the resource domain with values in your WmManagedConnection implementation.

Registering Resource Domains

You must register resource domains in your WmManagedConnection implementation using the WmManagedConnection.registerResourceDomain method. This method has a single argument of the type WmAdapterAccess. For more information, see Creating a WmManagedConnection Implementation Class.

Registering a resource domain name establishes the definition of the resource domain within a given scope. That is, you can register one resource domain to be used by all adapter services that use the connection, or you can register multiple resource domains on a service-by-service basis. You must register the name of each resource domain supported by the connection (and by extension, each resource domain used by any service supported by the connection).

In the WmManagedConnection.registerResourceDomain method, you must perform the following:

Create a ResourceDomainValues object, which represents a list of values for a resource domain.

Specify whether the resource domain is fixed or dynamic.

Method	Description
WmAdapterAccess.addResourceDomain	Defines a fixed resource domain with one or more values. A fixed resource domain displays default values that you provide for the resource domain parameters. This method expects one or more ResourceDomainValues objects. For more information about resource domain values and their settings, see Populating Resource Domains with Values.
WmAdapterAccess.addResourceDomainLookup	Defines a dynamic resource domain. A dynamic resource domain enables the adapter to look up values for the parameters, based on changes to dependency parameters. This method supplies a reference to an object that the adapter service editor uses to make callbacks when the adapter service node is configured. Resource domain lookups can only be performed against WmManagedConnection objects, so the "this" reference is generally used as the object reference argument. For example: access.addResourceDomainLookup( "aSampleResourceDomainName", this); For more information, see Resource Domain Lookups.

Specify whether the users of the adapter can provide their own parameter values, and enable the adapter to validate these values. To do this, you use the following methods:

Method	Description
ResourceDomainValues.setComplete(false)	Allows the users of the adapter to supply values. Sets a flag named complete. When using both fixed resource domains and dynamic resource domains, you can allow the users of the adapter to enter their own values, allowing them to add to the current list of values for the resource domain.
ResourceDomainValues.setCanValidate(true)	Enables the adapter to validate the user supplied values using adapter check values callbacks. The WmManagedConnection.adapterCheckValue method validates the user supplied values. Sets the canValidate flag
WmAdapterAccess.addCheckValue	Calls the WmManagedConnection.adapterCheckValue method.

Note:
WmAdapterAccess.addCheckValue must appear after WmAdapterAccess.addResourceDomain or WmAdapterAccess.addResourceDomainLookup.

The following example registers two resource domains:

101. public void registerResourceDomain(WmAdapterAccess access)
102. throws AdapterException
103. {
104. ResourceDomainValues tableRdvs = new ResourceDomainValues(
105. MockDbUpdate.TABLES_RD, mockTableNames);
106. tableRdvs.setComplete(true);
107. access.addResourceDomain(tableRdvs);
108.
109. access.addResourceDomainLookup(MockDbUpdate.COLUMN_NAMES_RD,this);
110. access.addResourceDomainLookup(MockDbUpdate.COLUMN_TYPES_RD,this);
111.
112. ResourceDomainValues rdvs = new ResourceDomainValues(
113. MockDbUpdate.OVERRIDE_TYPES_RD, new String[] {""});
114. rdvs.setComplete(false);
115. rdvs.setCanValidate(true);
116. access.addResourceDomain(rdvs);
117. access.addCheckValue(MockDbUpdate.OVERRIDE_TYPES_RD,this);
...
121. }

In this example, note that:

Lines 104-105 create a ResourceDomainValues object (identified by the constant MockDbUpdate.TABLES_RD).

Line 106 indicates that the users of the adapter may not supply their own values to the resource domain.

Line 107 adds a resource domain to this object.

Lines 109-110 add lookups for this object, indicating that the resource domain is dynamic. For these lookups, you must pass an instance of the connection that can satisfy the lookup. This is accomplished by using the "this" reference.

Lines 112-113 create an empty ResourceDomainValues object.

Line 114-115 indicate that the users of the adapter may supply their own values, and the adapter validates these values. setCanValidate(true) calls the adapterCheckValue method (line 117) for each value that is not already in the resource domain.

Line 116 adds a resource domain to this object. This is a fixed resource domain because no lookups are performed.

Associating Metadata Parameters with Resource Domains

The metadata parameters of an adapter service must be assigned to a resource domain supported by the service's connection. The interface WmTemplateDescriptor, provides setResourceDomain with the following signature:

void setResourceDomain(String name,
String resourceDomainName,
String[] dependencies)

Parameter Name	Description
name	Name of the parameter being assigned.
resourceDomainName	Resource domain name that matches the name registered in the connection.
dependencies	List of any other metadata parameter names in the current adapter service upon which the value of the parameter in the first argument depends. Dependencies are important to dynamic resource domain lookups. When the user of an adapter changes the value of a parameter in the dependency list, a lookup retrieves a new set of resource domain values. For example, for the parameters named columns and tables, you might assign the columns parameter to a resource domain called columnsLookup, with a dependency on the tables parameter as follows: d.setResourceDomain("columns", "columnsLookup", new String[] {"tables"}); When the tables parameter changes, WmManagedConnection.adapterResourceDomainLookup determines the new value or values that can be applied to the columns parameter. Depending on the properties of a resource domain, the lookup may be used to set the value of a parameter, or to provide a list of possibilities from which the user of the adapter may select a value.

For more information, see Resource Domain Lookups.

For more information about the variant forms of setResourceDomain, including the concept of useColumns, see The useParam Argument of setResourceDomain.

Populating Resource Domains with Values

To populate a fixed or dynamic resource domain with values, implement the ResourceDomainValues class in your WmManagedConnection implementation.

This class is the primary container for controlling the behavior of the adapter service parameters. It is used during the registration process when you register a fixed resource domain, and it is returned from the adapterResourceDomainLookup method in response to a dynamic callback. For more information, see Resource Domain Lookups.

A ResourceDomainValues object contains the following:

Name of the resource domain.

Current list of values for the resource domain.

The current list of values can contain an array of strings or an array of ResourceDomainValue objects. This array constitutes the list of values that appears in the appropriate widgets in the adapter service editor. The displayed values are communicated as strings, regardless of the data type of the parameter associated with the resource domain.

Note:
Using a list of values that cannot be converted to the parameter's data type results in a runtime error. Null and empty strings are not accepted in numeric parameters.

The following methods:

Method	Description
ResourceDomainValues.setComplete(false)	Allows the users of the adapter to supply values. Sets a flag named complete. When using both fixed resource domains and dynamic resource domains, you can allow the users of the adapter to enter their own values, allowing them to add to the current list of values for the resource domain.
ResourceDomainValues.setCanValidate(true)	Enables the adapter to validate the user supplied values using adapter check values callbacks. The WmManagedConnection.adapterCheckValue method validates the user supplied values. Sets the canValidate flag
ResourceDomainValues.setDisabled	Disables the parameter in the adapter service editor.

For example, assume that a parameter named portNumber has a data type of int. When constructing the associated resource domain values, limit the list of values to numeric strings as follows:

new ResourceDomainValues("portNumberLookup", new String[]
{"6048","8088","9090"});

This example shows a ResourceDomainValues object with a set list. You have the option to define a range of values, by providing a minimum/maximum value. In this case, a single ResourceDomainValues object is used to define the minimum and maximum values of a numeric parameter. The following conditions must be met for defining a range of values:

The parameter must be of a numeric data type (such as int or long).

The parameter cannot be a sequence parameter (array).

The ResourceDomainValues object must contain exactly one value that is constructed from a ResourceDomainValue object.

ResourceDomainValues.setComplete must be false. You must set this method explicitly if you used the ResourceDomainValue[] constructor; otherwise, changes to the parameter are not saved.

The embedded ResourceDomainValue object must have a name representing a numeric value, and an endName representing a number value greater than the value of the name.

Note:
This is the only defined use for ResourceDomainValue.endName. In all other cases, only ResourceDomainValue.name is used. All other ResourceDomainValue attributes are placeholders, and are not currently implemented. Using a String[] to construct ResourceDomainValues is equivalent to using a ResourceDomainValue[] where only the ResourceDomainValue.name attributes are populated.