Configuring Conductor's Template-based Planner (Last updated: $Date: 2001/10/17 16:46:04 $)

1. Introduction

The template planner allows dynamic planning based on a set of templates that provide candidate solutions to network problems. The inputs to the template planner are a set of user preferences, node and network characteristics along the planning path, and a set of available templates. Each template describes a pattern of adaptor deployment and the resulting effect on the network, nodes, and data.

A template specifies a generic set of nodes on which adaptors will be placed, the adaptors that will be deployed on each node, the resources that will be required on each node, the effect on the data, and the effect on network characteristics.

A template can be applied to a network by matching the template node to real Conductor-enabled nodes in the network. If there are more Conductor-enabled nodes in the network than there are nodes in the template, there may be many ways to apply a given template.

The best template, and the best application of that template to a given network, is determined by examining the characteristics of the network, available node resources, and the user's preferences. The user is able to specify what effective network characteristics (on an end-to-end basis) are desired and what modifications to the data characteristics are most (or least) desired.

2. High-level Configuration

The following properties can appear in Conductor.properties to configure the overall behavior of the TemplatePlanner.
TemplatePlanner.TemplateDir filename ./config/templates The directory where templates are located.
TemplatePlanner.VerifyAdaptors boolean true Should we verify the presence of adaptors on a node before allowing that adaptor to be deployed on that node?

3. Attributes

Node and link characteristics are specified in terms of attributes. Each attribute has a name and a value. These attributes are specified in templates and in the planning information provided by nodes (which includes node resources, network characteristics, and user preferences). Conductor treats attribute names transparently, so the actual names don't matter. However, Conductor matches attribute names in templates with those in the planning information, so they must be consistent.

4. Templates

Each template is stored in an individual file. The files are stored in a directory given by the Conductor property TemplatePlanner.TemplateDir. The default template directory is ./config/templates. The name of each template file should end in .t.

Each template file consists of property/value pairs of the form property=value, one per line. Some properties require lists of values. In this case, several properties are used in the form property.<n>=value, where <n> is replaced with sequential numbers starting at 0 (<i> is also used below).

A special property, IncludeDefaults, can be used to specify the name of a file which contains a set of default properties. The default properties are overidden by any values in this file. A defaults file can also have an IncludeDefaults property, and so on.

The following properties are used to describe the overall properties of a template:

Protocol.<i>=range A list of protocols for which this template is useful. A protocol is specified using the destination port number for a connection (ie, the well known port number). Each range can be a single number or an inclusive range in the form min-max. At least one protocol must be specified
DataMod.<i>=string A list of ways in which the application of this template modifies the data delivered to the application. For instance, if an adaptor turns color images into black-and-white, the value "ColorRemoval" might be appropraite. These strings can be arbitrary and are matched to the user preferences below.
NumNodes=int The number of nodes in this template. This property is required!!
Value=int The intrinsic value of using this template. This integer is added to the evaluation score of each instantiation of this template.

The following properties are specified for each node <n> (starting at 0):

Node.<n>.UpAdaptor.<i>=Class-Name The list of adaptors that will deployed in the upstream direction (from the client to the server) on node <n>. They are listed in the order in which data will pass through. Each adaptor is specified using it's fully-qualified class name.
Node.<n>.DownAdaptor.<i>=Class-Name The list of adaptors that will deployed in the downstream direction (from the server to the client) on node <n>. They are listed in the order in which data will pass through. Each adaptor is specified using it's fully-qualified class name.
Node.<n>.Requirement.<i>=Attribute-Comparison The list of resource requirements for this node. Typically, these will be the minimum requirements for the adaptors that will be deployed (perhaps cpu cycels and storage space). The attribute name should match one of the node resources specified by that node.

The following properties are specified for each link <l> (starting at 0), which is the link upstream (toward the server) from the node with the same number:

Link.<l>.Effect.<i>=Attribute-Modifier The list of effects on this link by the application of this template. Note that when template nodes do not correspond to adjacent physical nodes, several links may be affected. This modification is applied to the matching link quality (specified below), and provides the effective characteristic after the adaptation is applied. For instance, data compression might double the effective bandwidth of a link.
The above properties make up the entire contents of a template file and may be specified in any order. Except for Protocol.<i> and NumNodes, properties (and lists of properties) can be omited when no value(s) are required.

A sample template can be found in Conductor/config/templates/ImageCompression.t.example.

5. User Preferences

During the planning process, the client node should provide the user's preferences to the planner. The user preferences should be specified in the following properties:

UserPrefs.DataMods.Preferred.<i>=string A list of data modifications preferred by the user. These modifications should match those specified in the template. The list should be specified in order of the user's preference.
UserPrefs.DataMods.Bad.<i>=string A list of data modifications unacceptable to the user. These modifications should match those specified in the template.
UserPrefs.LinkRequirements.<i>=Aggregated-Attribute-Comparison A list of user requirements for the effective characteristics (after the effects of adaptation) of the end-to-end network.

A sample configuration file for specifying user preferences using the StaticMonitor can be found in Conductor/config/UserPrefs.example.TemplatePlanner. Note that the StaticMonitor also allows user preferences to be specified on a per-protocol basis.

6. Node Properties

During the planning process each node should describe its local resources to the planner using the following properties:

NodeProps.Resource.<i>=Attribute A list of node resources available at this node. Typically one would specify attributed such as cpu cycles and storage space available.
NodeProps.Adaptor.<i>=Class-Name A list of adaptors available on this node. Each entry should be a fully-qualified class name. This list is not required if TemplatePlanner.VerifyAdaptors is set to false in the Conductor properties file.

A sample configuration file for specifying node properties using the StaticMonitor can be found in Conductor/config/NodeInfo.example.TemplatePlanner.

7. Link properties

During the planning process, each node should provide a description of the adjacent upstream and downstream links to the planner using the following properties:

NextLinkProps.Priority=int The priority of this "next link" information relative to the next node's "previous link" information.
NextLinkProps.Quality.<i>=Attribute A list of attributed describing the quality of the upstream (toward the server) link.
PrevLinkProps.Priority=int The priority of this "previous link" information relative to the previous node's "next link" information.
PrevLinkProps.Quality.<i>=Attribute A list of attributed describing the quality of the downstream (toward the client) link.

The names of the attributes specified in the above properties should typically match with the names of the attributes specified in the templates and the user requirements.

Note that for any given link there are two nodes that could potentially specify link properties. This conflict is resolved via the Priority property of NextLinkProps and PrevLinkProps. If the priorities are equal, the NextLink properties are preferred (ie, the node nearest the client specifies the link characteristics).

An example for specifying link properties using the template planner is provided in the following files: Conductor/config/LinkInfo.example.TemplatePlanner, Conductor/config/LinkInfo.lan.example.TemplatePlanner, and Conductor/config/LinkInfo.modem.example.TemplatePlanner Note that the prefixes PrevLinkProps and NextLinkProps are automatically added by the StaticMonitor for each link.

8. The Planning Algorithm

The planning algorithm formulates a plan based on the templates, the node inputs, and the user inputs. The algorithm takes each template, determines if it is basically suitable, and then tries to apply it to the network by matching the template nodes to the real network nodes in all possible configurations. Each configuration is tested to see if the network meets the template's requirements and if the resulting "effective" network characteristics meet the user's requirements. Each acceptable application of a template is scored, and the highest scoring application of a template is used to generate a plan.

The following is pseudo-code of the algorithm:

	for each template {
	   if (the network has too few nodes)
	      try next template
	   if (this protocol isn't in the template's protcol list)
	      try next template
	   if (one of the template data modes appears in the user's 
	       unacceptable data mod list)
	      try next template

	   for each matchup of template nodes to network nodes {
	      for each node {
	         if (the node resources don't meet the requirements from 
	             the template)
	            try another matchup
              }

	      for each link {
	         compute the effective link characteristics after adaptation
	      }

	      if (the aggregate effective network characteristics don't 
	          meet the user requriemetns)
	         try another matchup

	      compute the score for this application of the template
	   }
	}

	generate plan for highest scoring application of a template
Scoring is currently a little primitive, but it works like this:
  1. Start at some large number
  2. Subtract 100 points for each adaptor deployed
  3. For each data modification subtract 20 points times the rank (in order of the user's preference for that modification)
  4. Subtract 20 points for each Conductor node required (including the endpoints even if adaptation is not occurring there)
  5. Add the intrinsic value of this template (specified by the Value parameter)


Conductor is a product of Mark Yarvis (yarvis@fmg.cs.ucla.edu) and the FMG Research Group at UCLA's Department of Computer Science.
Copyright © 2001 The Regents of the University of California. All Rights Reserved.