| Prev | Part VIII. Extending ProActive Chapter 49. Adding a Deployment Protocol |  | Next |
ProActive support several deployment protocols. This protocols can be configured through an XML Descriptor file in the process section. From time to time, new protocols are added. This documentation describes how to add a new deployment protocol (process) to ProActive.
Adding a new process can be divided into two related tasks:
Java Process Class
In this section, a java class that handles the specific protocol must be implemented. This java class must have certain properties discussed later on.
XML Descriptor
Since each new protocol requieres different configuration parameteres, the DescriptorSchema.xsd and related parsing code must be modified to handle the new process and it's specific parameteres.
Both of this tasks are closely related because the Java Process Class is used when parsing the Descriptor XML.
The Java Process Classes are defined in the org.objectweb.proactive.core.process package.
Most implementations extend the class AbstractExternalProcessDecorator.
In this figure, OARSubProcess and SSHProcess both extend from AbstractExternalProcessDecorator. Notice, that in the case of SSH, more than one class maybe required to succesfully implement the protocol. This is why, every protocol is implemented within it's on directory in the process package:
ProActive/src/org/objectweb/proactive/core/process/newprocessdir/
Sometimes, implementeing a specific process requiers external libraries, possibly from the original protocol client. The correct place to put this external .jar libraries is in:
ProActive/lib/newprocessdir/*.jar
Before executing a deployment using this new process, don't forget to add this libraries to the $CLASSPATH envirorment variable.
Usualy the new java process class will have a name such as: ProtocolNameProcess.java. The ProtocolNameProcess class will extend from AbstractExternalProcessDecorator. Therefore, at least the following inherited methods must be implemented:
public ProtocolNameProcess();
public ProtocolNameProcess(ExternalProcess targetProcess);
public String getProcessId();
public int getNodeNumber();
public UniversalProcess getFinalProcess();
protected String internalBuildCommand();
protected void internalStartProcess(String commandToExecute) throws java.io.IOException;
On certain clusters, a starting script might be required. Sometimes, this script will be static and receive parameteres at deployment time (globus, pbs, ...), and in other cases it will have to be generated at deployment time (oar, oargrid). In either case, the proper place to put these scipts is:
ProActive/scripts/unix/cluster/
The schema file is located at: ProActive/descriptors/DescriptorSchema.xsd. This file contains the valid tags allowed in an XML descriptor file.
processDefinition Childs
The first thing to do, is add the new process tag in:
<xs:complexType name="ProcessDefinitionType">
<xs:choice>
<xs:element name="jvmProcess" type="JvmProcessType"/>
<xs:element name="rshProcess" type="RshProcessType"/>
<xs:element name="maprshProcess" type="MapRshProcessType"/>
<xs:element name="sshProcess" type="SshProcessType"/>
<xs:element name="processList" type="ProcessListType"/>
<xs:element name="processListbyHost" type="ProcessListbyHostType"/>
<xs:element name="rloginProcess" type="RloginProcessType"/>
<xs:element name="bsubProcess" type="BsubProcessType"/>
<xs:element name="pbsProcess" type="PbsProcessType"/>
<xs:element name="oarProcess" type="oarProcessType"/>
<xs:element name="oarGridProcess" type="oarGridProcessType"/>
<xs:element name="globusProcess" type="GlobusProcessType"/>
<xs:element name="prunProcess" type="prunProcessType"/>
<xs:element name="gridEngineProcess" type="sgeProcessType"/>
</xs:choice>
<xs:attribute name="id" type="xs:string" use="required"/>
</xs:complexType>
Specific Process Tag
Afterwards, all the tag attributes and subtags need to be defined. In this example, we show the OARGRID tag:
<!--oarGridProcess-->
<xs:complexType name="oarGridProcessType">
<xs:sequence>
<xs:element ref="processReference"/>
<xs:element ref="commandPath" minOccurs="0"/>
<xs:element name="oarGridOption" type="OarGridOptionType"/>
</xs:sequence>
<xs:attribute name="class" type="xs:string" use="required"
fixed="org.objectweb.proactive.core.process.oar.OARGRIDSubProcess"/>
<xs:attribute name="queue" type="xs:string" use="optional"/>
<xs:attribute name="bookedNodesAccess" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="rsh"/>
<xs:enumeration value="ssh"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="closeStream" type="CloseStreamType" use="optional"/>
</xs:complexType>
<!--oarGridOption-->
<xs:complexType name="OarGridOptionType">
<xs:sequence>
<xs:element name="resources" type="xs:string"/>
<xs:element name="walltime" type="xs:string" minOccurs="0"/>
<xs:element name="scriptPath" type="FilePathType" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
This file is located in org.objectweb.proactive.core.descriptor.xml package. It contains the tag names used within XML descriptor files. When adding a new process, new tags should be registered in this file.
Located in: org.objectweb.proactive.core.descriptor.xml, this file is the XML handler for the process descriptor section.
New XML handler innerclass
This class will parse all the process specific tags and attributes. It is an innerclass in the ProcessDefinitinonHandler.java file. Sometimes, this class will have a subclass in charge of parsing a subsection of the process tag.
protected class OARGRIDProcessHandler extends ProcessHandler {
public OARGRIDProcessHandler(ProActiveDescriptor proActiveDescriptor) {
super(proActiveDescriptor);
this.addHandler(OARGRID_OPTIONS_TAG, new OARGRIDOptionHandler());
}
public void startContextElement(String name, Attributes attributes)
throws org.xml.sax.SAXException {
super.startContextElement(name, attributes);
String queueName = (attributes.getValue("queue"));
if (checkNonEmpty(queueName)) {
((OARGRIDSubProcess) targetProcess).setQueueName(queueName);
}
String accessProtocol = (attributes.getValue("bookedNodesAccess"));
if (checkNonEmpty(accessProtocol)) {
((OARGRIDSubProcess) targetProcess).setAccessProtocol(accessProtocol);
}
}
protected class OARGRIDOptionHandler extends PassiveCompositeUnmarshaller {
public OARGRIDOptionHandler() {
UnmarshallerHandler pathHandler = new PathHandler();
this.addHandler(OAR_RESOURCE_TAG, new SingleValueUnmarshaller());
this.addHandler(OARGRID_WALLTIME_TAG, new SingleValueUnmarshaller());
BasicUnmarshallerDecorator bch = new BasicUnmarshallerDecorator();
bch.addHandler(ABS_PATH_TAG, pathHandler);
bch.addHandler(REL_PATH_TAG, pathHandler);
this.addHandler(SCRIPT_PATH_TAG, bch);
}
public void startContextElement(String name, Attributes attributes)
throws org.xml.sax.SAXException {
}
protected void notifyEndActiveHandler(String name, UnmarshallerHandler activeHandler)
throws org.xml.sax.SAXException {
OARGRIDSubProcess oarGridSubProcess = (OARGRIDSubProcess) targetProcess;
if (name.equals(OAR_RESOURCE_TAG)) {
oarGridSubProcess.setResources((String) activeHandler.getResultObject());
}
else if(name.equals(OARGRID_WALLTIME_TAG)){
oarGridSubProcess.setWallTime((String) activeHandler.getResultObject());
}
else if (name.equals(SCRIPT_PATH_TAG)) {
oarGridSubProcess.setScriptLocation((String) activeHandler.getResultObject());
}
else {
super.notifyEndActiveHandler(name, activeHandler);
}
}
}
}
Registering the new XML handler innerclass
The new XML handler innerclass must be registered to handle the parsing of the newprocess tag. This is donde in the constructor:
public ProcessDefinitionHandler(ProActiveDescriptor
proActiveDescriptor){...}
© 2001-2007 INRIA Sophia Antipolis All Rights Reserved