| Prev | Part V. Deployment And Virtualization Chapter 20. Variable Contracts for Descriptors |
 |
Next |
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.
| 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.
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. |
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>
... 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");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>
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 (=).
import org.objectweb.proactive.core.xml.VariableContract;
import org.objectweb.proactive.core.xml.VariableContractImpl;
import org.objectweb.proactive.core.xml.VariableContractType; VariableContractType.DefaultVariable
VariableContractType.DescriptorDefaultVariable
VariableContractType.ProgramVariable
VariableContractType.ProgramDefaultVariable
VariableContractType.JavaPropertyVariable
VariableContractType.JavaPropertyDescriptorDefault
VariableContractType.JavaPropertyProgramDefault
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.
© 1997-2008 INRIA Sophia Antipolis All Rights Reserved