Chapter 22. Variable Contracts for Descriptors

22.1. Variable Contracts for Descriptors

22.1.1. Principle

The objective of this feature is to allow the use of variables with XML descriptors. Variables can be defined: directly in the descriptor, using independent files, or inside the deploying application's code (with an API).

The variable tags are usefull inside a descriptor because they can factorize frequent parameters. (For example, a variable like ${PROACTIVE_HOME} can be defined, set and used in an XML Descriptor.) But also, because they can be used to establish a contract between the Program and the Descriptor.

22.1.2. Variable Types

Type	Ability to set value	Ability to set empty value	Priority
DescriptorVariable	Descriptor	Program	Descriptor
ProgramVariable	Program	Descriptor	Program
DescriptorDefaultVariable	Descriptor, Program	-	Program
ProgramDefaultVariable	Program, Descriptor	-	Descriptor
JavaPropertyVariable	Descriptor, Program	-	JavaProperty
JavaPropertyDescriptorDefault	JavaProperty, Descriptor, Program	Program	JavaProperty, Descriptor, Program
JavaPropertyProgramDefault	JavaProperty, Descriptor, Program	Descriptor	JavaProperty, Program, Descriptor

Table 22.1. Variable Types

Variables can be set in more than one place. When the value is set on multiple places, then the definition specified in the priority column will take precedence. In the priority column, items towards the left have more priority.

22.1.3. Variable Types User Guide

To help identify the user cases where the variable types might be useful, we have defined the concept of programmer and deployer. The programmer is the person writing the application code. The deployer corresponds to the responsible of writing the deployment descriptor. The variables represent rights and responsabilities between the two parties (contract) as specified in the following table:

Type	Behavior	When to use this type
descriptorVariable	The value has to be set in the descriptor, and cannot be specified in the program.	If the deployer wants to use a value, without giving the possibility to the programmer to modify it. The programmer can define this variable to empty, to force the descriptor to set a value.
programVariable	The value must be set in the program, and cannot be specified in the descriptor.	If the programmer wants to use a value, without giving the possibility to the descriptor to modify it. The descriptor can define this variable to empty, to force the programmer to set a value.
descriptorDefaultVariable	A default value must be specified in the descriptor. The programmer has the ability not to change the value in the program. Nevertheless, if the value is changed in the program, then this new value will have precedence over the one defined in the descriptor.	If the programmer may override the default value, but the responsability of setting a default belongs to the deployer.
programDefaultVariable	A default value must be specified in the program. The descriptor has the ability not to change the value. Nevertheless, if the value is changed in the descriptor, then this new value will have precedence over the one defined in the program.	If the deployer may override the default value, but the responsability of setting a default belongs to the programmer.
javaPropertyVariable	Takes the value from the corresponding Java property.	When a variable will only be known at runtime through the Java properties, and no default has to be provided by the descriptor or the application.
javaPropertyDescriptorDefault	Takes the value from the corresponding java property. A default value can also be set from the descriptor or the program. If no property is found, the descriptor default value will override the program default value.	When the descriptor sets a default value, that can be overrided at deployment using a java property.
javaPropertyProgramDefault	Takes the value from the corresponding java property. A defualt value can also be set from the program or the descriptor. If no property is found, the program default value will override the program default value	When the program sets a default value, than can be overrided at deployment using a java property.

22.1.4. Variables Example

22.1.4.1. Descriptor Variables

All variables must be set in a variable section at the beginning of the descriptor file in the following way:

         <variables>
         <descriptorVariable name="PROACTIVE_HOME" value="ProActive/dist/ProActive"/>
         <descriptorDefaultVariable name="NUMBER_OF_VIRTUAL_NODES" value="20"/>
         <programVariable name="VIRTUAL_NODE_NAME"/>
         <javaPropertyVariable name="java.home"/>
         <javaPropertyDescriptorDefault name="host.name" value="localhost"/> 
         <javaPropertyProgramDefault name="priority.queue"/> 

         <!-- Include external variables from files-->
         <includeXMLFile location="file.xml"/>
         <includePropertyFile location="file.properties"/>
         </variables>
         ...
         <!-- Usage example-->
         <classpath>
         <absolutePath value="${USER_HOME}/${PROACTIVE_HOME}/ProActive.jar"/>
         ...
         </classpath>
         ...

22.1.4.2. Program Variables

         XML_LOCATION="/home/user/descriptor.xml";
         VariableContract variableContract= new VariableContract();
         variableContract.setVariableFromProgram( "VIRTUAL_NODE_NAME", "testnode", VariableContractType.ProgramVariable);
         variableContract.setVariableFromProgram( "NUMBER_OF_VIRTUAL_NODES", "10", VariableContractType.DescriptorDefaultVariable);
         variableContract.setVariableFromProgram( "priority.queue", "vip", VariableContractType.JavaPropertyProgramDefault);
         ProActiveDescriptor pad = ProActive.getProactiveDescriptor(XML_LOCATION, variableContract);

         //Usage example
         VariableContract vc=pad.getVariableContract;
         String proActiveHome=vc.getValue("PROACTIVE_HOME");

22.1.5. External Variable Definitions Files

22.1.5.1. XML Files

Is built using XML property tags.

File: file.xml

<!-- Definition of the specific context -->
<variables>
  <descriptorVariable name="USER_HOME" value="/usr/home/team"/>
  <descriptorVariable name="PROACTIVE_HOME" value="ProActive/dist/ProActive"/>
  <descriptorVariable name="NUM_NODES" value="45"/>
</variables>

22.1.5.2. Properties Files

This approach uses Sun microsystems properties file format. The format is plain text with one definition per line in the format variable = value, as shown in the following example:

File: file.properties

# Definition of the specific context
USER_HOME = /usr/home/team
PROACTIVE_HOME = ProActive/dist/ProActive
NUM_NODES: 45

Variables defined in this format will be declared as DescriptorVariable type. Note that colon (:) can be used instead of equal (=).

22.1.6. Program Variable API

22.1.6.1. Relevant import packages

import org.objectweb.proactive.core.xml.VariableContract;
import org.objectweb.proactive.core.xml.VariableContractType;

22.1.6.2. Available Variable Types

VariableContractType.DefaultVariable
VariableContractType.DescriptorDefaultVariable
VariableContractType.ProgramVariable
VariableContractType.ProgramDefaultVariable
VariableContractType.JavaPropertyVariable
VariableContractType.JavaPropertyDescriptorDefault
VariableContractType.JavaPropertyProgramDefault

22.1.6.3. API

The API for setting variables from the Program is shown below. The name corresponds to the variable name, and the value to the variable content. The type corresponds to a VariableContractType.

public void VariableContract.setVariableFromProgram( String name, String value, VariableContractType type);
public void VariableContract.setVariableFromProgram( HashMap map, VariableContractType type);

The API for adding a multiple variables is shown above. The variable name/value pair is specified as the key/content of the HashMap.

Prev	Up	Next
Chapter 21. XML Deployment Descriptors	Table of Contents	Chapter 23. ProActive File Transfer Model