Variable Contracts for Descriptors

20.1. Variable Contracts for Descriptors

20.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.

20.1.2.  Variable Types

<title>Variable Types</title>
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

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.

20.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.

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.

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 to change the value in the program. If the value is changed in the program, then this new value will have precedence over the one defined in the descriptor.

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 to change the value. If the value is changed in the descriptor, then this new value will have precedence over the one defined in the program.

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.

20.1.4. Variables Example

20.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>
         ...

20.1.4.2. Program Variables

         XML_LOCATION="/home/user/descriptor.xml";
         VariableContract variableContract= new VariableContractImpl();
         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 = PADeployment.getProactiveDescriptor(XML_LOCATION, variableContract);

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

20.1.5. External Variable Definitions Files

20.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>                 

20.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 (=).

20.1.6. Program Variable API

20.1.6.1. Relevant import packages

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

20.1.6.2. Available Variable Types

  • VariableContractType.DefaultVariable

  • VariableContractType.DescriptorDefaultVariable

  • VariableContractType.ProgramVariable

  • VariableContractType.ProgramDefaultVariable

  • VariableContractType.JavaPropertyVariable

  • VariableContractType.JavaPropertyDescriptorDefault

  • VariableContractType.JavaPropertyProgramDefault

20.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.