Chapter 40. Adding a Deployment Protocol

40.1. Objectives

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.

40.2. Overview

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.

40.3. Java Process Class

The Java Process Classes are defined in the org.objectweb.proactive.core.process package.

40.3.1. Process Package Arquitecture

Most implementations extend the class AbstractExternalProcessDecorator .

Figure 40.1. core.process structure

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.

40.3.2. The New Process Class

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;

40.3.3. The StartRuntime.sh script

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/

40.4. XML Descriptor Process

40.4.1. Schema Modifications

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>

40.4.2. XML Parsing Handler

40.4.2.1. ProActiveDescriptorConstants.java:

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.

40.4.2.2. ProcessDefinitinonHandler.java:

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){...}

Prev	Up	Next
Chapter 39. Developing Conventions	Table of Contents	Chapter 41. How to add a new FileTransfer CopyProtocol