ProActive can provide fault-tolerance capabilities through two different protocols: a Communication-Induced Checkpointing protocol (CIC) or a pessimistic message logging protocol (PML). Making a ProActive application, fault-tolerant is fully transparent: active objects are turned into fault-tolerant using Java properties that can be set in the deployment descriptor (see Chapter 21. ProActive Grid Component Model Deployment). The programmer can select at deployment time the most adapted protocol regarding the application and the execution environment.

Persistence of active objects is obtained through standard Java serialization: a checkpoint thus consists in an object containing a serialized copy of an active object and few informations related to the protocol. As a consequence, a fault-tolerant active object has to be serializable.

Usually, applications and security are developed for a specific use. We propose here a security framework that allows dynamic deployment of applications and security configuration according to this deployment.

ProActive security mechanism provides a set of security features from basic ones like communications authentication, integrity, and confidentiality to more high-level features including secure object migrations, hierarchical security policies, and dynamically negotiated policies. All these features are expressed at the ProActive middleware level and used transparently by applications.

It is possible to attach security policies to Runtimes, Virtual Nodes, Nodes and Active Objects. Policies are expressed inside an XML descriptor.

A GUI has been created to facilitate certificate generation. It is a RCP plugin shipped with the IC2D tool. Once IC2D started, go to Window -> Open Perspective -> Other... and select Security.

The following window should then appear:

Figure 2.7. The IC2D Security Perspective

From this tab, you can generate a root certificate filling the certificate information column and clicking on Generate self signed certificate.

Figure 2.8. Creating a root certificate

Then, you can generate a child certificate filling the certificate information column and clicking on Generate child certificate after having selected the parent certificate on the second column.

Figure 2.9. Creating a child certificate

Once you have generated all the certificates you need, you can drag'n drop the ones you want to activate from the second column to the last one. Activating certificates allows you to use them afterwards for rule creation. It also allows you to save them into a file.

Figure 2.10. Activating a keystore

Now, let us have a look at the Keystore Editor tab. This tab allows you to get some information on the generated keytores, to save them into files or to load some others to be used after for rule edition. Certificates are saved under a PKCS12 format (extension .p12). This format is natively supported by the ProActive Security mechanism.

Figure 2.11. Keystore Editor

Finally, you can use the Rule Editor tab to edit your rules. These rules can be saved into a policy file using the Save rules button. To get familiar with the generated policy file, please refer to Section 2.6, “The XML Security Descriptor in details”. To create a new rule, you just have to click on the New button and then fill the right panel. The From and To part can be filled by drag'n drop from the ActiveKeystore column.

Figure 2.12. Rule Editor

The last tab, Sessions browser, cannot be used directly. It is used to see certificate details at runtime. To do this, you have to monitor your application with IC2D and then, you can click right on an active object and select Export SM to Security view. You will then have access to a window looking as follows:

Figure 2.13. Session Browser

Within the deployment descriptor, the <security> tag is used to specify the policy for the deployed application. It will be the policy for all the created Nodes and Active Objects. The following example shows an example of a deployment descriptor with such a <security> tag:

<?xml version="1.0" encoding="UTF-8"?>
<ProActiveDescriptor xmlns="urn:proactive:deployment:3.3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:proactive:deployment:3.3 http://www-sop.inria.fr/oasis/ProActive/schemas/deployment/3.3/deployment.xsd">

    <!-- Variable Definitions -->
    <variables>
        <descriptorVariable name="PROACTIVE_HOME" value="/user/ffonteno/home/proactive-git/programming" />
        <descriptorVariable name="JAVA_HOME" value="/user/ffonteno/home/src/java/jdk1.6.0_11/jre/bin/java" />
    </variables>

    <!-- Security Policy Definitions -->
    <security>
          <file uri='ApplicationPolicy.xml'/>
    </security>

    <!-- Virtual Node Definitions -->
    <componentDefinition>
        <virtualNodesDefinition>
            <virtualNode name="VN_A"/>
            <virtualNode name="VN_B"/>
        </virtualNodesDefinition>
    </componentDefinition>

    <deployment>

        <!-- Mappings between Virtual Nodes and JVMs -->
        <mapping>
            <map virtualNode="VN_A">
                <jvmSet>
                    <vmName value="jvm_A" />
                </jvmSet>
            </map>
            <map virtualNode="VN_B">
                <jvmSet>
                    <vmName value="jvm_B" />
                </jvmSet>
            </map>
        </mapping>

        <!-- Mappings between JVMs and process references. -->
        <!-- Process references are used hereafter (within the infrastructure element)
             to describe the process used to create the JVMs. -->
        <jvms>
            <jvm name="jvm_A">
                <creation>
                    <processReference refid="localJVM_A" />
                </creation>
            </jvm>
            <jvm name="jvm_B">
                <creation>
                    <processReference refid="localJVM_B" />
                </creation>
            </jvm>
        </jvms>
    </deployment>
    <infrastructure>
        <processes>

            <!-- Process Definitions -->
            <processDefinition id="localJVM_A">
                <jvmProcess
                    class="org.objectweb.proactive.core.process.JVMNodeProcess">
                    <classpath>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/ProActive.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/bouncycastle.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/fractal.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/trilead-ssh2.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/javassist.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/log4j.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/xercesImpl.jar"/>
                    </classpath>
                    <javaPath>
                        <absolutePath
                            value="/user/ffonteno/home/src/java/jdk1.6.0_11/jre/bin/java" />
                    </javaPath>
                </jvmProcess>
            </processDefinition>

            <!-- Process Definitions -->
            <processDefinition id="localJVM_B">
                <jvmProcess
                    class="org.objectweb.proactive.core.process.JVMNodeProcess">
                    <classpath>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/ProActive.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/bouncycastle.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/fractal.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/trilead-ssh2.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/javassist.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/log4j.jar"/>
                        <absolutePath value="${PROACTIVE_HOME}/dist/lib/xercesImpl.jar"/>
                    </classpath>
                    <javaPath>
                        <absolutePath
                            value="/user/ffonteno/home/src/java/jdk1.6.0_11/jre/bin/java" />
                    </javaPath>
                </jvmProcess>
            </processDefinition>

        </processes>
    </infrastructure>
</ProActiveDescriptor>

Inside the policy file, you can express policy between entities (domain, runtime, node, active object).

The entity tag can be used to:

<Policy xmlns="urn:proactive:security:1.1" xmlns:schemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:proactive:security:1.1 http://www-sop.inria.fr/oasis/ProActive/schemas/security/1.1/security.xsd">

<ApplicationName>My Application</ApplicationName>

<PKCS12KeyStore>ApplicationCertificate.p12</PKCS12KeyStore>

<CertificationAuthority>
    <Certificate>ca.cert</Certificate>
</CertificationAuthority>

<?xml version="1.0" encoding="UTF-8"?>
<Policy xmlns="urn:proactive:security:1.1" xmlns:schemaVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:proactive:security:1.1 http://www-sop.inria.fr/oasis/ProActive/schemas/security/1.1/security.xsd">
    <ApplicationName>My Application</ApplicationName>
    <PKCS12KeyStore>ApplicationCertificate.p12</PKCS12KeyStore>

    <CertificationAuthority>
        <Certificate>ca.cert</Certificate>
    </CertificationAuthority>
    <Rules>
        <Rule>
            <From>
                <Entity type="VN" name="CN=VN_A"/>
            </From>
            <To>
                <Entity type="VN" name="CN=VN_B"/>
            </To>
            <Communication>
                <Request value="authorized">
                    <Attributes authentication="required" confidentiality="required" integrity="required"/>
                </Request>
                <Reply value="authorized">
                    <Attributes authentication="required" confidentiality="required" integrity="required"/>
                </Reply>
            </Communication>
            <Migration>authorized</Migration>
            <OACreation>authorized</OACreation>
        </Rule>
        <Rule>
            <From>
                <Entity type="Node" name="CN=VN_B"/>
            </From>
            <To>
                <Entity type="Node" name="CN=VN_A"/>
            </To>
            <Communication>
                <Request value="authorized">
                    <Attributes authentication="required" confidentiality="required" integrity="required"/>
                </Request>
                <Reply value="authorized">
                    <Attributes authentication="required" confidentiality="required" integrity="required"/>
                </Reply>
            </Communication>
            <Migration>authorized</Migration>
            <OACreation>authorized</OACreation>
        </Rule>
    </Rules>
    <AccessRights/>
</Policy>

java -Dproactive.runtime.security=descriptors/security/jvmlocal.xml TestSecureDeployment secureDeployment.xml

Message Tagging allows you to add tags on the ProActive messages such as requests and replies. Each tag has an identifier and a unique value, and they can take a data of object type. Theses tags have a method called at each propagation. This method is the only needed method in your implementation of the abstract class Tag.

To retrieve the tag list of a request or a reply being served in your application, you can use the following API:

From this MessageTags object, you have access to the following API to interract with tags:

Once you have retrieved the tag instance, you have acces to the following methods:

All the tags have access to a LocalMemory object, which is a local memory space on the Active Object on which the request is currently being served. They can save or retrieve data in this space (key/value). This is useful when the tag needs information on a previous passage of this Active Object. This local memory space is created for a specified lease time. The max lease time is specified by the proactive.tagmemory.lease.max PAProperty which represents the max lease value time in second.

You can use this local memory space with the following API in your Tag implementation:

Once you have your LocalMemory instance, you have access to:

Each time a value is accessed, the current lease value of the LocalMemory space is incremented by half of the initial value. A thread runs periodicaly (proactive.tagmemory.lease.period) to check the lease value of each LocalMemory, and decrements their current lease.

This section presents a tag example which is able to give information on the request depth. Thus, we can know for example how many requests have been served before serving the current one.

Here is the implementation of this tag:

public class IncrementingTag extends Tag {

    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    private Integer depth;

    public IncrementingTag(String id) {
        super(id);
        this.depth = 0;
    }

    @Override
    public Tag apply() {
        this.depth++;
        return this;
    }

    public Integer getDepth() {
        return this.depth;
    }

}

Each time this tag is propated, that is, each time the apply method is called, the depth field is incremented.

In order to test this tag, we have written a loop between three active objects:

All this classes define a propagate method which hava the same principle:

Here is the propagate method of the class A:

public void propagate(Integer maxDepth) {

    MessageTags tags = PAMessageTagging.getCurrentTags();

    // Gets or creates the tag 'Tag_00'
    IncrementingTag t = (IncrementingTag) tags.getTag("TAG_00");
    if (t == null)
        t = (IncrementingTag) tags.addTag(new IncrementingTag("TAG_00"));

    // Displays the tag depth
    System.out.println("\n-----------------------");
    System.out.println("A: Tag depth = " + t.getDepth());

    // Gets the tag data and adds the current class to the path
    String str = (String) t.getData();
    if (str == null)
        str = "A";
    else
        str += " -> A";
    t.setData(str);
    System.out.println("A: Path = " + t.getData());

    // Gets or creates the memory 'MEM_00'
    // and stores in it the round number.
    LocalMemoryTag mem = t.getLocalMemory();
    if (mem == null) {
        t.createLocalMemory(10).put("MEM_00", new Integer(0));
        mem = t.getLocalMemory();

    } else {
        Integer round = (Integer) mem.get("MEM_00");
        mem.put("MEM_00", ++round);
    }
    System.out.println("A: Round number = " + (Integer) mem.get("MEM_00"));
    System.out.println("-----------------------");

    // Propagates to the active object 'B'
    if (t.getDepth() < maxDepth)
        activeB.propagate(maxDepth);
}

This example is available in the org.objectweb.proactive.examples.documentation.messagetagging package.

The Distributed Services Flow Tag (DSF Tag) allows the following of all messages (requests and replies) so as to know to which services flow these messages belong to. This tag is necessary if you want to do a graphical analysis in IC2D of the execution of your application.

This tag can be enable or disable with the proactive.tag.dsf ProActive property. Set this property to true if you want to enable the DSF Tag propagation in the execution of the application. It is set to false by default.

This feature allows to expose an active object as a web service and thus, to call it from any client written in any foreign language.

Indeed, applications written in C#, for instance, cannot communicate with ProActive applications. We have chosen web services technology to enable interoperability because they are based on XML and HTTP. Thus, any active object can be accessible from any enabled web services language.

A web service is a software entity, providing one or several functionalities, that can be exposed, discovered and accessed over the network. Moreover, web services technology allows heterogeneous applications to communicate and exchange data in a remotely way. In our case, the useful elements of web services are:

Figure 4.1. Steps taken when an active object is called via SOAP

If you want to expose your active objects on the local embedded Jetty server or on Jetty servers deployed during your deployment, you just have to deploy proactive using the build deploy command into the compile directory. If you want to expose them on an other http server, you have to build the proactive.war archive. For this, you have to go into your compile directory of your ProActive home and type build proActiveWar[Axis2|CXF]. The proactive.war file will be built into the dist/ directory.

If you have chosen to use the default Jetty server, then you have nothing else to do. Jetty server will automatically take files it needs.

If you have chosen to use your own HTTP server, then you just have to copy the proactive.war file into the webapp/ directory of your HTTP server. Some HTTP servers need to be restarted to take into account this new web application but some others like Tomcat can handle hot deployment and, thus, do not need to be restarted.

	Warning
	If you use your own HTTP server, you have to be aware that the Jetty server will be launched. Most of ProActive examples are launched with the option '-Dproactive.http.port=8080' which specifies Jetty port. So, if you want to use your own server on port 8080, you have to modify the jetty port in launching scripts or to change the port of your own server.

The steps for exporting and using an active object as a web service are the following:

When you call the exposition of your active object, the Axis2 servlet or the CXF one is deployed on the local Jetty server. It is therefore possible to expose your object locally without doing anything else.

Now, let us assume that your active object is deployed on a remote node. In that case, you have a running jetty server on the remote host containing this node but no servlet has been deployed on it. So, if you want to expose your active object on the remote host, you will have to make a small modification of the previous piece of code.

The web service extension provides classes that implements the InitActive interface which are in charge of deploying the CXF or the Axis2 servlet on the host where your object has been initialized. Thus, you just have to instantiate your active object using this implementation of InitActive.

// Get the CXF InitActive in charge of deploying the CXF Servlet
InitActive cxfInitActive = WebServicesInitActiveFactory.getInitActive("cxf");
HelloWorld helloWorld = (HelloWorld) PAActiveObject.newActive(HelloWorld.class.getName(), null,
        new Object[] {}, myNode, cxfInitActive, null);

Now, let us assume that your active object is deployed on a node or locally and that you want to expose it on a host where another node is deployed. On this host, there is only a running Jetty server without any web services servlet. In order to deploy the CXF or Axis2 servlet on it, you can use the following code:

WebServicesInitActiveFactory.getInitActive("cxf").initServlet(myNode);

Then, you can expose your active object as a web service as in Section 4.4, “Steps to expose or unexpose an active object as a web services”.

Once the active object deployed, you can access it via any web service client (such as C#, SoapUI, Axis2 API, CXF API...) or with your favorite browser (only if the returned type of your service methods are primitive types).

First of all, the client will get the WSDL file matching this active object. This WSDL file is the 'identity card' of the service. It contains the web service public interfaces and its location. Generally, WSDL files are used to generate a proxy to the service. For example, for a given service, say 'compute', you can get the WSDL document at http://localhost:8080/proactive/services/compute?wsdl.

Now that this client knows what and where to call the service, it will send a SOAP message to the web server. The web server looks into the message and performs the right call. Then, it returns the response into another SOAP message to the client.

Contrary to the previous version of the active object exposition using Apache SOAP, this new version which uses Axis2 or CXF can handle complex types. That is, with this version, you can implement a service which exposes a method returning or taking in argument an instance of any class. However, the class of this instance has to respect some criteria due to the serialization and CXF/Axis2 restrictions:

Axis2 and CXF are not fully compatible. In particular, clients behave differently. Axis2 client uses to send SOAP requests using "argn" as name for the n-th argument of the requested method. However, CXF creates the WSDL service using parameter names as written into the Java code. Thus, there is a difference of names and the service cannot find argument names in the SOAP message matching with the argument names of the requested method. Null value is therefore used as parameters. To easily solve this issue, you can change the argument names of your service to match with "argn". If you cannot change the service, you have to use another client as those used in the ProActive extension.

If you want to use the CXF client provided by ProActive for calling an Axis2 service, you will also face difficulties since this client waits for a returned SOAP message that the Axis2 service will not return for a void method. One thing but not the best you can do, is to modify ProActive CXF client in order to eat the exception for oneWayCall. This is not the best solution since other exceptions will be eaten too.

In a general manner, we advise you to use the same framework for the exposition as a web service and for the client consuming this service.

Compile-time annotations provide a way to check at compile-time the constraints imposed on Java code by the ProActive library. Usually, these constraints are documented in the ProActive manual, and it is left to the responsibility of the programmer to obey these rules. If the rules are broken, the effects are usually seen at runtime, translated into specific runtime exceptions, which are difficult to interpret by the unexperienced ProActive programmers. The compile-time annotation system makes it possible to verify these rules at compile-time, in order to avoid long debugging sessions made out of stack traces eyeballing. Ideally, the runtime errors that the programmer will receive will be more related to the logic of the application, and less to the misusage of the ProActive library.

void methodName()

void method(Node, String)

void method(String)

OSGi is a corporation that works on the definition and promotion of open specifications. These specifications mainly aim at packaging and delivering services among all kinds of networks.

OSGi Framework

The OSGi specification defines a framework that allows a diversity of services to be executed in a service gateway. Thus, many applications can share a single JVM.

Figure 6.1. The OSGi framework entities

Bundles

In order to be delivered and deployed on OSGi, each piece of code is packaged into bundles. Bundles are functional entities offering services and packages. They can be delivered dynamically to the framework. Concretely, a bundle is a Java jar file containing:

Bundles can be plugged dynamically and their so-called lifecycle can be managed through the framework (start, stop, update...).

Manifest file

This important file contains crucial parameters for the bundle. It specifies which Activator (entry point) the bundle has to use, the bundle classpath, the imported and exported packages and so on...

Services

Bundles communicates with each other thanks to services and packages sharing. A service is an object registered into the framework in order to be used by other applications. The definition of a service is specified in a Java interface. OSGi specifies a set of standard services like Http Service, Log Service...

We currently use the Apache Felix implementation. For more information on OSGi, please visit the OSGi website.

In order to use ProActive on top of OSGi, we have developed the ProActive Bundle that contains all classes required to launch a ProActive runtime.

The ProActive bundle offers a service, the ProActiveService that has almost the same interface that the ProActive static class. When installed, the ProActive bundle starts a new runtime, and clients that use the ProActive Service will be able to create active object on this runtime.

Figure 6.2. The Proactive Bundle uses the standard Http Service

The active object will be accessible remotely from any java application, or any other OSGi gateway. The communication can be either rmi or http. In case of using http, the ProActive bundle requires the installation of the Http Service that will handle http communications through a Servlet. We show in the example section how to use the ProActive service.

The example below is a simple hello world that uses ProActive Service. It creates an Hello active Object and registers it as a service. We reuse the basic hello example provided within the ProActive's examples. We have to write a bundle Activator that will create the active object and register it as a OSGi service.

The HelloActivator has to implements the BundleActivator interface.

public class HelloActivator implements BundleActivator {
}

The start() method is the one executed when the bundle starts. When the hello bundle starts, we need to get the reference to the ProActive service and use it. Once we have the reference, we can create our active objects thanks to the ProActiveService.newActive() method. In this example, we use this method to create two active objects: One HelloSystemOut object and one HelloLogInfo object. This two classes implement the HelloService class which defines two methods: sayHello() and saySomething(String something). Finally, we register these two objects as a HelloService with two different out properties that will enable us to differentiate them.

public class HelloActivator implements BundleActivator {

    private BundleContext context;
    private ProActiveService proActiveService;

    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#start(org.osgi.framework.BundleContext)
     */
    public void start(BundleContext context) throws Exception {
        this.context = context;

        /* gets the ProActive Service */
        ServiceReference sr = this.context.getServiceReference(ProActiveService.class.getName());

        if (sr == null) {
            System.out.println("Couldn't start this bundle: The service '" +
                ProActiveService.class.getName() + "' is not started");
            return;
        }

        this.proActiveService = (ProActiveService) this.context.getService(sr);
        HelloService h = (HelloService) this.proActiveService.newActive(HelloSystemOut.class.getName(),
                new Object[] {});

        /* Register the service */
        Properties props = new Properties();
        props.put("name", "HelloSystemOut");
        props.put("out", "system");

        this.context.registerService(HelloService.class.getName(), h, props);

        h = (HelloService) this.proActiveService.newActive(HelloLogInfo.class.getName(), new Object[] {});

        /* Register the service */
        props = new Properties();
        props.put("name", "HelloLogInfo");
        props.put("out", "logger");

        this.context.registerService(HelloService.class.getName(), h, props);
    }

    /*
     * (non-Javadoc)
     * @see org.osgi.framework.BundleActivator#stop(org.osgi.framework.BundleContext)
     */
    public void stop(BundleContext context) throws Exception {
    }

}

Now that we have created the hello active service, we have to package the application into a bundle. First of all, we have to write a Manifest File where we specify:

Here is how the Manifest looks like:

Bundle-Name: ProActive Hello World Bundle
Bundle-SymbolicName: ProActive Hello World Bundle
Bundle-Description: Bundle containing Hello World ProActive example
Bundle-Vendor: OASIS - INRIA Sophia Antipolis
Bundle-version: 1.0.0
Export-Package: org.objectweb.proactive.examples.osgi.hello
DynamicImport-Package: *
Bundle-Activator: org.objectweb.proactive.examples.osgi.hello.HelloActivator
Require-Bundle: org.objectweb.proactive.extensions.osgi

Installing the ProActive Bundle and the Hello Bundle.

In order to run the example, you need to install an OSGi framework. Proactive uses felix as an OSGi framework but you can choose another one.

JMX (Java Management eXtensions) is a Java technology providing tools and APIs for managing and monitoring Java applications and their resources. Resources are represented by objects called Managed Beans (MBeans).

Figure 7.1.  This figure shows the JMX 3-level architecture and the integration of the ProActive JMX Connector.

JMX defines a 3-layer management architecture:

The JMX technology defines a connector based on RMI. The RMI connector allows the manager to connect to an MBean in a MBeanServer from a remote location and performs operations on it.

We defined a ProActive Connector according to the JMX Remote API JSR 160 that enables asynchronous remote access to a JMX Agent thanks to ProActive. This connector is based on a call via an active object. When invoking the standard API specification methods, the access to the managed application is synchronous, because the JMX remote API provides non-reifiable methods. For example, the invoke() method, allowing to invoke a Mbean's method, throws exceptions:

public Object invoke(ObjectName name, String operationName, Object[] params, String[] signature)
   throws InstanceNotFoundException, MBeanException, ReflectionException, IOException;

We have extended the API in order to provide asynchronous access thanks to additionnal reifiable methods. The additional invoke() method looks like as follows:

public GenericTypeWrapper invokeAsynchronous(ObjectName name, String operationName, Object[] params, String[] signature)

Thus, all requests sent to the MBean are put in the active object requests queue and a future object is returned to the client.

The ProActive connector allows you to connect an MBean in an MBean server to a remote location, and perform operations on it, exactly as if the operations were being performed locally.

To perform such a call, you have first to create the server connector on the application you wish to manage. This is simply done by adding one line of code in the application:

ServerConnector serverConnector = new ServerConnector("MyServerName");
serverConnector.start();

Once the connector server part launched, any ProActive JMX connector client can connect to it and manage the application thanks to the ClientConnector class.

ClientConnector cc = new ClientConnector("//localhost/", "MyServerName");

To perform remote operations on a given MBean, you have to get the reference of the current MBeanServerConnection, which is actually a ProActiveConnection:

// Connects the client connector
cc.connect();

// Retrieves the ProActive connection
ProActiveConnection pc = cc.getConnection();

// Creates an ObjectName refering to an MBean
ObjectName beanName = new ObjectName("SimpleAgent:name=hellothere");

// Asynchronously invoke the "concat" method of this mbean with two Strings as parameters
GenericTypeWrapper<?> returnedObject = pc.invokeAsynchronous(beanName, "concat", new Object[] {
        "FirstString ", "| SecondString" }, new String[] { String.class.getName(),
        String.class.getName() });

	Note
	To know all available methods on a MBeanServerConnection, have a look at the MBeanServerConnection javadoc.

The JMX specification defines a notification mechanism, based on java events and allowing to alert client management applications. To use JMX notifications, one has to use a listener object that is registered within the MBean server. On the server side, the MBean has to implement the NotificationBroadcaster interface. As we work in a distributed environment, listeners are located remotely and thus, have to be joined remotely. Hence, the listener must be a serializable active object and added as a NotificationListener:

/* Creates an active listener MyListener */
MyListener listener = (MyListener) PAActiveObject.newActive(MyListener.class.getName(), null);

/* Adds the listener to the Mbean server where we are connected to */
pc.addNotificationListener(beanName, listener, null, null);

	Note
	More informations on JMX on: Getting Started with Java Management Extensions (JMX): Developing Management and Monitoring Solutions

The example available in the $PROACTIVE_HOME/examples/jmx/ directory, is a simple textual tool to connect to a remote MBeanServer and list available domains and mbeans registered in this server.

To launch the connector server side, execute the connector.[sh|bat] script. To connect this server, execute the simpleJmx.[sh|bat] script and specify the MBean serber name where is hosted the Mbean server:

--- JMC Test client connector---------------------------------------------
Enter the name of the JMX MBean Server :  [default is '//localhost/serverName']
(Type "exit" to quit)

Just typing Enter should work since the server location of the mbean server launched with the connector.[sh|bat] script is the default one.

The console shows the domains list:

Registered Domains :
	[ 0 ] JMImplementation
	[ 1 ] com.sun.management
	[ 2 ] org.objectweb.proactive
	[ 3 ] org.objectweb.proactive.core.runtimes
	[ 4 ] org.objectweb.proactive.core.node
	[ 5 ] java.lang
	[ 6 ] java.util.logging

Type the domain number to see all registered MBeans in this domain :

By choosing a specific domain, the console will show the Mbeans registered in this domain:

Choosing the java.lang domain, you should see the following registered MBeans:

[ 0 ] java.lang:type=OperatingSystem
[ 1 ] java.lang:type=Compilation
[ 2 ] java.lang:type=MemoryPool,name=PS Old Gen
[ 3 ] java.lang:type=Memory
[ 4 ] java.lang:type=MemoryPool,name=PS Perm Gen
[ 5 ] java.lang:type=Runtime
[ 6 ] java.lang:type=GarbageCollector,name=PS MarkSweep
[ 7 ] java.lang:type=Threading
[ 8 ] java.lang:type=GarbageCollector,name=PS Scavenge
[ 9 ] java.lang:type=ClassLoading
[ 10 ] java.lang:type=MemoryPool,name=PS Survivor Space
[ 11 ] java.lang:type=MemoryManager,name=CodeCacheManager
[ 12 ] java.lang:type=MemoryPool,name=Code Cache
[ 13 ] java.lang:type=MemoryPool,name=PS Eden Space
[ D ]  Domains list

Type the mbean number to see its properties :

If you wish to get informations about Memory, choose 3, and the console will show the whole information about this MBean.

In order to be able to monitor and controle ProActive application, each ProActive object has an MBean:

Thus, through these beans, it is possible to receive the JMX notification emitted by the MBean, or to invoke a method on the MBean.

Utility classes are provided in order to make the subscription of JMX notifications easy. If you subscribe to a MBean of a remote MBean server, this one sends you the notifications of the wanted MBean. However, in case of an active object, if the object migrates it is necessary to unsubscribe the listener from the MBean Server and to open a new connection to the new MBean Server and subscribe to this one. If you do not do those steps you will not continue to receive the notifications. In order to resolve this problem, we provide the JMXNotificationManager class.

JMXNotificationManager.getInstance().subscribe(ObjectName objectName, NotificationListener listener, String runtimeUrl);

JMXNotificationManager.getInstance().subscribe(
        ProActiveRuntimeImpl.getProActiveRuntime().getMBean().getObjectName(), listener);

JMXNotificationManager.getInstance().unsubscribe(ObjectName objectName, NotificationListener listener);

JMXNotificationManager.getInstance().subscribe(
        ProActiveRuntimeImpl.getProActiveRuntime().getMBean().getObjectName(), listener);

TimIt offers a complete solution to benchmark an application. It is an API which provides some advanced timing and event observing services. Benchmarking your ProActive application will permit you to enhance performance of it. Thanks to generated statistics charts, you will be able to determine critical points of your application.

TimIt is best suited for SPMD applications. Using TimIt for other purposes is not recommended but possible. All TimIt SPMD classes are located in org.objectweb.proactive.extensions.timitspmd package in the ProActive sources folder.

Different kind of statistics can be collected. You can setup different timers with hierarchical capabilities and see them in charts. For instance, event observers can be used to study communication pattern between your application's workers.

TimIt generates charts and results XML file, with exact timing and event observers values. Here are some examples of charts and XML files generated by TimIt:

<timit>
  <FinalStatistics name="Example2 4" runs="10" timeoutErrors="0"
                   date="2006-11-05 10:46:56.742">

    <timers>
      <timer name="total"
             min="2095.0" avg="2191.250" max="2357.0" dev="1.603" sum="2187.750">
        <timer name="work"
               min="1453.0" avg="1466.000" max="1473.0" dev="0.951" sum="0.000" />
        <timer name="init"
               min="147.0" avg="175.250" max="205.0" dev="2.932" sum="0.000" />
        <timer name="end"
               min="467.0" avg="546.500" max="679.0" dev="1.439" sum="0.000" />
      </timer>
    </timers>

    <events>
      <event name="nbComms" min="92.000" avg="92.000" max="92.000" dev="0.000" />
      <event name="commPattern" value="Too complex value, first run shown">.
10  0 13  0
 0 13  0 10
13  0 10  0
 0 10  0 13
      </event>
      <event name="densityPattern" value="Too complex value, first run shown">.
  20    0 2080    0
   0 2080    0   20
2080    0   20    0
   0   20    0 2080
      </event>
    </events>


    <informations>
      <deployer jvm="Java HotSpot(TM) Client VM 1.5.0_06-64 - Version 1.5.0_06"
                os="ppc Mac OS X 10.4.8" processors="1" />
    </informations>


  </FinalStatistics>

</timit>

TimIt provides different kinds of services. By combining them, you will be able to measure many parameters of your application. TimIt package contains few examples for using these services in your application.

T_TOTAL.start();

  T_INIT.start();
    // Initialization part...
    T_COMM.start();
      // Communications...
    T_COMM.stop();
  T_INIT.stop();

  T_WORK.start();
    // Working part...
    T_COMM.start();
      // Communications...
    T_COMM.stop();
  T_WORK.stop();

T_TOTAL.stop();

TimIt package can be found in the org.objectweb.proactive.extensions.timitspmd package. We try to make as easy as possible the way to add a new feature to this application. To do so, TimIt is organized in 5 major points which can be extended:

// Add these lines in the get method of Benchmark class
if (name.equals("myOption")) {
  return "1";
}

String result = bench.get("myOption");
// ... and do whatever you want with it...

For dealing with filtered network topology, ProActive provide an implementation of the OpenSSH ProxyCommand mechanism. It permit to do a bouncing SSH connection using a gateway. A SSH server has to be host by the gateway, and an implementation of the netcat command should be available.

The proxyCommand is implemented as an extension of the RMI+SSH protocol, so the protocol RMI+SSH must be selected by using the ProActive Property :

                proactive.communication.protocol=rmissh

The proxyCommand consists in opening a connection to a specified gateway, and then from this connection, bouncing all request to the desired host. Thus it is possible to rely NATed (Network Address Translation) LANs, Clusters, ...

Figure 10.1. An example of proxy command use

The proxyCommand can be configured either by specifying a ProActive property or by using the one found in the file .ssh/config. The property to use is

proactive.communication.ssh.proxy.gateway
            

.

Here is an example :

            *.domain.com:gateway.domain.com:22;192.168.1.0/24:gateway.domain.com:22;
        

The ProActive framework contains many protocols to fit all the constraints that the network topology will makes.

Therefore, it provides the support of the multi-protocol, this permits to make the most of the underlying network, by using the most suitable protocol on each parts of the network and to maintain reliability between each nodes.

The support of multi-protocol aims to be totally transparent, no user actions are needed, neither for exposition, nor for selection. The only constraint is that the default protocol selected must be able to allow communication between all nodes.

By default, the benchmarking are disabled and only the selection is done. For enabling the benchmark, the property proactive.communication.benchmark.class must be set to something else than org.objectweb.proactive.core.remoteobject.benchmark.SelectionOnly.

The API for dealing with multi protocol support is placed in PARemoteObject class.

This chapter is meant to help you as a reference for writing ProActive-directed documentation. If you have added a new feature and want to help its uptake by documenting it, you should read this chapter.

The examples sections (Section 12.3, “Example use of tags”) describes the use of the main tags you will use (eventually, all the ProActive-allowed docbook tags should be described). The limitations (Section 12.4, “DocBook limitations imposed”) section describes what is allowed in our docbook style, and why we restrict ourselves to a subset of docbook.

First off, all the documentation is written in docbook. You can find all the documentation source files in the ProActive/doc/src/ directory.

Here are the instructions to follow to start well and fast writing documentation for the ProActive middleware:

These are the basic rules to follow to use docbook tags. This document is made up of the files in the docBookTutorial directory, and you may find it with the other manual files in the ProActive/doc/src directory.

12.3.1. Summary of the useful tags

The main tags/structures you should be using are:

• <figure> - when you want to insert an image

• <example> - when you want an example with a title (should contain a <screen> or a <programlisting>). You can also use <literal> inside paragraphs.

• <screen> - when you want to insert a command line, an output or a flat text...

• <programlisting language="[java|xml|c]"> - when you want to insert a java, an XML or a C snippet of code which will be highlighted.

• <para> - to start a paragraph.

• <section> - to start a section.

• <emphasis> - when you want to have some particular text pointed out.

• <itemizedlist> followed by several <listitem> - when you want bullets

• <orderedlist> followed by several <listitem> - when you want numbered bullets

• <xref> - when you want to reference another section, chapter, example, etc. using its id.

• <ulink> - when you want to reference a web URL.

• <table> - when you want to insert a table.

	Note
	If you are using XXE, you should always use the XXE icons. They have all you need (except for EXAMPLE/SCREEN)! You can also cut'n paste!

12.3.2. Figures

This is the figure example. Please use the <title> tag.

Figure 12.1. A drawing using the <figure> tag

Here is what has been written into the XML file:

<figure xml:id="ADrawingusingtheFIGUREtag_42">
    <info>
        <title>A drawing using the &lt;figure&gt; tag</title>
    </info>
    <mediaobject>
        <imageobject>
            <imagedata scalefit="1" width="100%" contentdepth="100%" align="center" fileref="images/png/e1.png" format="PNG"/>
        </imageobject>
    </mediaobject>
</figure>

<itemizedlist>
    <listitem>
        <para>Provide an implementation for the required server-side functionalities</para>
    </listitem>
    <listitem>
        <para>Provide an empty, no-arg constructor</para>
    </listitem>
    <listitem>
        <para>Write a method in order to instantiate one server object.</para>
    </listitem>
</itemizedlist>

12.3.4. Code

Code sources should be written using the <programlisting language="java"> tag (possibly language are java, xml or c). You do not have to write valid code, as the highlighting (done by the docbook highlighting) is based on regular expression replacement, and not on language grammars. If you want to show some program output, you can use <screen> instead of <programlisting>. In any case, watch out, because spaces count (and produce your own indentation)! You can also use the <example> tag around your <programlisting> or <screen> tags, to give a title and be referenced in the table of examples.

There are three different ways to insert code:

• by referencing a file

• by referencing a code snippet

• by directly writing your code into the <programlisting> tag

	Warning
	We strongly advise to use one of the two first ways. Writing directly codes into the documentation files implies to always update the documentation when source codes change. Referencing a file or a piece of code which is always up-to-date is the best means to keep coherence between the source code and the documentation.

We will now give some examples illustrating each case of writing code into the documentation. After each example, the documentation XML code is exposed.

/*
 * ################################################################
 *
 * ProActive Parallel Suite(TM): The Java(TM) library for
 *    Parallel, Distributed, Multi-Core Computing for
 *    Enterprise Grids & Clouds
 *
 * Copyright (C) 1997-2011 INRIA/University of
 *                 Nice-Sophia Antipolis/ActiveEon
 * Contact: proactive@ow2.org or contact@activeeon.com
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Affero General Public License
 * as published by the Free Software Foundation; version 3 of
 * the License.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
 * USA
 *
 * If needed, contact us to obtain a release under GPL Version 2 or 3
 * or a different license than the AGPL.
 *
 *  Initial developer(s):               The ProActive Team
 *                        http://proactive.inria.fr/team_members.htm
 *  Contributor(s):
 *
 * ################################################################
 * $$PROACTIVE_INITIAL_DEV$$
 */
package org.objectweb.proactive.examples.hello;

import org.apache.log4j.Logger;
import org.objectweb.proactive.api.PAActiveObject;
import org.objectweb.proactive.api.PALifeCycle;
import org.objectweb.proactive.core.util.ProActiveInet;
import org.objectweb.proactive.core.util.log.Loggers;
import org.objectweb.proactive.core.util.log.ProActiveLogger;
import org.objectweb.proactive.core.util.wrapper.StringMutableWrapper;
import org.objectweb.proactive.extensions.annotation.ActiveObject;


/** A stripped-down Active Object example.
 * The object has only one public method, sayHello()
 * The object does nothing but reflect the host its on. */
@ActiveObject
public class TinyHello implements java.io.Serializable {
    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    private final static Logger logger = ProActiveLogger.getLogger(Loggers.EXAMPLES);
    private final String message = "Hello World!";

    /** ProActive compulsory no-args constructor */
    public TinyHello() {
    }

    /** The Active Object creates and returns information on its location
     * @return a StringWrapper which is a Serialized version, for asynchrony */
    public StringMutableWrapper sayHello() {
        return new StringMutableWrapper(this.message + "\n from " + getHostName() + "\n at " +
            new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date()));
    }

    /** finds the name of the local machine */
    static String getHostName() {
        return ProActiveInet.getInstance().getInetAddress().getHostName();
    }

    /** The call that starts the Acive Objects, and displays results.
     * @param args must contain the name of an xml descriptor */
    public static void main(String[] args) throws Exception {
        // Creates an active instance of class Tiny on the local node
        TinyHello tiny = (TinyHello) PAActiveObject.newActive(TinyHello.class.getName(), // the class to deploy
                null // the arguments to pass to the constructor, here none
                ); // which jvm should be used to hold the Active Object

        // get and display a value 
        StringMutableWrapper received = tiny.sayHello(); // possibly remote call
        logger.info("On " + getHostName() + ", a message was received: " + received); // potential wait-by-necessity
        // quitting

        PALifeCycle.exitSuccess();
    }
}

Example 12.1. JAVA program listing with file inclusion

<example xml:id="JAVAprogramlistingwithfileinclusion_42">
    <info>
        <title>JAVA program listing with file inclusion</title>
    </info>
    <programlisting language="java"><textobject><textdata fileref="../../../src/Examples/org/objectweb/proactive/examples/hello/TinyHello.java"/></textobject></programlisting>
</example>

Example 12.2. Documentation source code of Example 12.1, “JAVA program listing with file inclusion”

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<!-- A user component. It has an interface to the dispatcher. -->

<definition name="org.objectweb.proactive.examples.components.c3d.adl.UserImpl">

<!-- The interfaces the component defines -->
  <interface signature="org.objectweb.proactive.examples.c3d.Dispatcher" role="client" name="user2dispatcher"/>

<!-- The implementation of the component -->
  <content class="org.objectweb.proactive.examples.components.c3d.UserImpl"/>
  <controller desc="primitive"/>

<!-- deploy this component only on 'User' VirtualNodes (which must be found in the deploy. descr.) -->
  <virtual-node name="User"/>

</definition>

Example 12.3. XML program listing with file inclusion

<example xml:id="XMLprogramlistingwithfileinclusion_42">
    <info>
        <title>XML program listing with file inclusion</title>
    </info>
    <programlisting language="xml"><textobject><textdata fileref="../../../src/Examples/org/objectweb/proactive/examples/components/c3d/adl/UserImpl.fractal"/></textobject></programlisting>
</example>

Example 12.4. Documentation source code of Example 12.3, “XML program listing with file inclusion”

Here is a screen example. For instance, this could be some code inside a unix shell:

linux > start.sh & 

Example 12.5. A screen example

<example xml:id="screen_42">
        <info>
            <title>A screen example</title>
        </info>
        <screen>linux &gt; start.sh &amp; </screen>
    </example>
</example>

Example 12.6. Documentation source code of Example 12.5, “A screen example”

As previously evoked, it is also possible to display a snippet of an existing code. To do this, you should insert the following comments into your source code:

• //@snippet-start MySnippet or <!-- @snippet-start MySnippet --> - to start your snippet

• <!-- @snippet-start-with-header MySnippet --> - to start your snippet adding the XML prologue before (only for XML files)

• //@snippet-start-with-copyright MySnippet - to start your snippet adding the copyright before (only for Java files)

• //@snippet-end MySnippet or <!-- @snippet-end MySnippet --> - to end your snippet

• //@snippet-break MySnippet or <!-- @snippet-break MySnippet --> - to break your snippet

• //@snippet-resume MySnippet or <!-- @snippet-resume MySnippet --> - to resume your snippet

Warning

You cannot not insert an annotation before the prologue in case of an XML file and you should not insert an annotation before a copyright in case of a Java file. Adding such an annotation before the prologue of an XML file makes it invalid and if you add one before the copyright of a Java file, it will be removed the next time we will update copyrights. If you want to have the prologue or the copyright displayed in your snippet, use @snippet-start-with-header and @snippet-start-with-copyright.

For this moment, only java, xml, c and fractal files are supported for snippet extraction and you must respect some rules:

• The name of your snippet, here "MySnippet", should be unique.

• A started snippet has to be ended.

• A broken snippet has to be resumed before it ends.

• Break blocks of a same snippet cannot be imbricated.

• For a given snippet name, the first annotation is snippet-start.

• For a given snippet name, the last annotation is snippet-end.

• The source file has to be located into the ProActive/src/ or the ProActive/examples/ directory. The other directories are not browsed by the snippet extractor.

When compiling the documentation, we can see errors that occurred during the snippet extraction.

/*
 * ################################################################
 *
 * ProActive Parallel Suite(TM): The Java(TM) library for
 *    Parallel, Distributed, Multi-Core Computing for
 *    Enterprise Grids & Clouds
 *
 * Copyright (C) 1997-2011 INRIA/University of
 *                 Nice-Sophia Antipolis/ActiveEon
 * Contact: proactive@ow2.org or contact@activeeon.com
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Affero General Public License
 * as published by the Free Software Foundation; version 3 of
 * the License.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
 * USA
 *
 * If needed, contact us to obtain a release under GPL Version 2 or 3
 * or a different license than the AGPL.
 *
 *  Initial developer(s):               The ProActive Team
 *                        http://proactive.inria.fr/team_members.htm
 *  Contributor(s):
 *
 * ################################################################
 * $$PROACTIVE_INITIAL_DEV$$
 */
package org.objectweb.proactive.examples.documentation.classes;

import java.io.Serializable;

import org.objectweb.proactive.core.util.wrapper.StringWrapper;


/**
 * @author ffonteno
 *
 */
//@snippet-start class_A
public class A implements Serializable {
    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    protected String str = "Hello";

    /**
     * Empty no-arg constructor
     */
    public A() {
    }

    /**
     * Constructor which initializes str
     *
     * @param str
     */
    public A(String str) {
        this.str = str;
    }

    /**
     * setStrWrapper
     *
     * @param strWrapper StringWrapper to set
     *      StringWrapper is used since this method gives an example
     *      of parameter scatterring. Parameter need to be serializable.
     * @return this
     */
    public A setStrWrapper(StringWrapper strWrapper) {
        this.str = strWrapper.getStringValue();
        return this;
    }

    /**
     * getB
     *
     * @return a B object corresponding to the current Object
     */
    public B getB() {
        if (this instanceof B) {
            return (B) this;
        } else {
            return new B(str);
        }
    }

    /**
     * display str on the standard output
     */
    public void display() {
        System.out.println("A display =====> " + str);
    }

    //@snippet-break class_A
    //@snippet-start class_A_exception
    /**
     * Example of a method which can throw an exception
     *
     * @param hasToThrow boolean saying whether the method should
     *                   throw an exception
     * @throws Exception
     */
    public void throwsException(boolean hasToThrow) throws Exception {
        Thread.sleep(5000);
        if (hasToThrow)
            throw new Exception("Class A has thrown an exception");
    }
    //@snippet-resume class_A
    //@snippet-end class_A_exception
}
//@snippet-end class_A

Example 12.7. File from which the snippet will be extracted

public class A implements Serializable {
    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    protected String str = "Hello";

    /**
     * Empty no-arg constructor
     */
    public A() {
    }

    /**
     * Constructor which initializes str
     *
     * @param str
     */
    public A(String str) {
        this.str = str;
    }

    /**
     * setStrWrapper
     *
     * @param strWrapper StringWrapper to set
     *      StringWrapper is used since this method gives an example
     *      of parameter scatterring. Parameter need to be serializable.
     * @return this
     */
    public A setStrWrapper(StringWrapper strWrapper) {
        this.str = strWrapper.getStringValue();
        return this;
    }

    /**
     * getB
     *
     * @return a B object corresponding to the current Object
     */
    public B getB() {
        if (this instanceof B) {
            return (B) this;
        } else {
            return new B(str);
        }
    }

    /**
     * display str on the standard output
     */
    public void display() {
        System.out.println("A display =====> " + str);
    }

}

Example 12.8. Snippet extraction

<example xml:id="snippet_42">
    <info>
        <title>Result of the snippet extraction</title>
    </info>
    <programlisting language="java"><textobject><textdata fileref="automatic_snippets/class_A.snip"/></textobject></programlisting>
</example>

Example 12.9. Documentation source code of Example 12.8, “Snippet extraction”

Finally, here is some java code directly included in the docbook (you can use CDATA to escape & and <):

package util;

import java.io.IOException;

/** Just a dummy class. */

public class Dummy {

  /** Just the method description
   * @param fileToConvert the name of the file to convert
   * @return a String created  */
  String convert(String fileToConvert) throws IOException {
    if (a > b && c < d ) {
      // can use "this" for 'NodeCreationEvent'
      VirtualNode vn = pad.getVirtualNode("vn");
      vn.start();
      }
    return "Hello World";
  }

}

Example 12.10. Java program listing with direct inclusion

        <example xml:id="programlistingWithDirectInclusion">
            <info>
                <title>Java program listing with direct inclusion</title>
            </info>

            <programlisting language="java">package util;

import java.io.IOException;

/** Just a dummy class. */

public class Dummy {

  /** Just the method description
   * @param fileToConvert the name of the file to convert
   * @return a String created  */
  String convert(String fileToConvert) throws IOException {
    if (a &gt; b &amp;&amp; c &lt; d ) {
      // can use "this" for 'NodeCreationEvent'
      VirtualNode vn = pad.getVirtualNode("vn");
      vn.start();
      }
    return "Hello World";
  }

}</programlisting>
        </example>

Example 12.11. Documentation source code of Example 12.10, “Java program listing with direct inclusion”

12.3.5. Links

Use <xref> tags to point to a element of your documentation. For instance, you can refer to the "Figures" section like that Section 12.3.2, “Figures”. The documentation source code of this link is the following one:

<xref linkend="Figures"/>

The linkend attribute points to the id which is referenced, for example, in a <section> tag. With the endterm attribute, you can customize the content which will be used to point to the reference. For instance, the following example refers to the same section as previously but using the figure itself:

This has been done using the following code:

<xref linkend="Figures" endterm="ADrawingusingtheFIGUREtag_42"/>

Use <link> tags to point to a web references (ProActive for instance). Here is the documentation source code for this link:

<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://proactive.inria.fr/"> a web references (ProActive for instance)</link>

This is the way of writing links as describes in the DocBook documentation. However, the xlink namespace is already defined in the DocBook xsl files. So, it is possible to omit it. You may have already the <ulink> tags for other documents based on DocBook. This is no longer possible with the version 5 of DocBook: this tag has been removed.

Use <citation> followed by an <xref> for citations. For example, see [BBC02] to learn on groups. All the biblio entries should be put in biblio.xml. This citation has been written using the following piece of code:

<citation><xref linkend="BBC02" endterm="BBC02.abbrev"/></citation>

<table>

    <title xml:id="Thisisanexampletable_42">This is an example table</title>

    <tgroup cols="2">
        <thead>
            <row>
                <entry><para>Name</para></entry>
                <entry><para>Hits</para></entry>
            </row>
        </thead>
        <tbody>
            <row>
                <entry><para>Bob</para></entry>
                <entry><para>5</para></entry>
            </row>

            <row>
                <entry><para>Mike</para></entry>
                <entry><para>8</para></entry>
            </row>

            <row>
                <entry><para>Jude</para></entry>
                <entry><para>3</para></entry>
            </row>
        </tbody>
    </tgroup>
</table>

We restrict ourselves to a subset of docbook because we want a maintainable and uniform styled documentation. To achieve this goal, we require minimum learning investment from our ProActive developers, who are meant to be coding, not spending their time writing documentation. So you still want to add a fancy feature? Well, you can, as long as you describe how to use this new tag in this howto, and be extra careful with the pdf output.

There is a schema specifying which are the allowed tags. You can only use the tags that this dtd allows. If you want more freedom, refer to Section 12.5.5, “DocBook subset: the dtd”. You can use the following tags:

Here are a few notes on how you should go about customizing the output. That means, changing how the pdf and html are written.

<xsl:message>
    <xsl:text> OK, in question.toc, id is </xsl:text> <xsl:value-of select="$id" />
</xsl:message>

<xsl:for-each select="./@*">
    <xsl:message>
        Attribute <xsl:value-of select="name(.)"/> = <xsl:value-of select="."/>
    </xsl:message>
</xsl:for-each>

java -cp $CLASSPATH org.apache.xalan.xslt.Process -TT -xsl ...  -in ... -out ...

[xml_validate] 1 file(s) have been successfully validated.

To add a new external FileTransfer CopyProtocol, follow the steps hereafter:

	Warning
	Choosing the correct name for the protocol is simple, but must be done carefully. All names already in the array ALLOWED_COPY_PROTOCOLS are forbidden. This includes the name 'processDefault', which is also forbidden. Some times, 'processDefault' will correspond to an external FileTransfer protocol (e.g. ssh with scp), and some other times, it will correspond to an internal protocol.

To add a new internal FileTransfer CopyProtocol, follow the steps hereafter:

	Note
	When adding an internal FileTransfer protocol, nothing must be modified or added to the copyProtocolFactory(){} method.

Fault-tolerance mechanism in ProActive is mainly based on the org.objectweb.proactive.core.body.ft.protocols.FTManager class. This class contains several hooks that are called before and after the main actions of an active object (e.g. sending or receiving a message, serving a request, etc.)

For example, with the Pessimistic Message Logging protocol (PML), messages are logged just before the delivery of the message to the active object. Main methods for the FTManager of the PML protocol are then:

/**
 * Message must be synchronously logged before being delivered.
 * The LatestRcvdIndex table is updated
 * @see org.objectweb.proactive.core.body.ft.protocols.FTManager#onDeliverReply(org.objectweb.proactive.core.body.reply.Reply)
 */
@Override
public int onDeliverReply(Reply reply) {
    // if the ao is recovering, message are not logged
    if (!this.isRecovering) {
        try {
            // log the message
            this.storage.storeReply(this.ownerID, reply);
            // update latestIndex table
            this.updateLatestRvdIndexTable(reply);
        } catch (RemoteException e) {
            e.printStackTrace();
        }
    }
    return 0;
}

/**
 * Message must be synchronously logged before being delivered.
 * The LatestRcvdIndex table is updated
 * @see org.objectweb.proactive.core.body.ft.protocols.FTManager#onReceiveRequest(org.objectweb.proactive.core.body.request.Request)
 */
@Override
public int onDeliverRequest(Request request) {
    // if the ao is recovering, message are not logged
    if (!this.isRecovering) {
        try {
            // log the message
            this.storage.storeRequest(this.ownerID, request);
            // update latestIndex table
            this.updateLatestRvdIndexTable(request);
        } catch (RemoteException e) {
            e.printStackTrace();
        }
    }
    return 0;
}

The local variable this.storage is a remote reference to the checkpoint server. The FTManager class contains a reference to each fault-tolerance server: fault-detector, checkpoint storage and localization server. Those reference are initialized during the creation of the active object.

A FTManager has to define also a beforeRestartAfterRecovery() method, which is called when an active object is recovered. This method usually restore the state of the active object so as to be consistent with the others active objects of the application.

For example, with the PML protocol, all the messages logged before the failure has to be delivered to the active object. The method beforeRestartAfterRecovery() thus looks like:

/**
 * Message logs are contained in the checkpoint info structure.
 */
@Override
public int beforeRestartAfterRecovery(CheckpointInfo ci, int inc) {
    // recovery mode: received message no longer logged
    this.isRecovering = true;

    //first must register incoming futures deserialized by the recovery thread
    this.owner.registerIncomingFutures();

    //get messages
    List<Reply> replies = ((CheckpointInfoPMLRB) ci).getReplyLog();
    List<Request> request = ((CheckpointInfoPMLRB) ci).getRequestLog();

    // deal with potential duplicata of request
    // duplicata of replies are not treated since they are automaticaly ignored.
    Request potentialDuplicata = request.get(request.size() - 1);
    this.potentialDuplicataSender = potentialDuplicata.getSourceBodyID();
    this.potentialDuplicataSequence = potentialDuplicata.getSequenceNumber();

    // add messages in the body context
    Iterator<Request> itRequest = request.iterator();
    BlockingRequestQueue queue = owner.getRequestQueue();

    while (itRequest.hasNext()) {
        queue.add((itRequest.next()));
    }

    // replies
    Iterator<Reply> itReplies = replies.iterator();
    FuturePool fp = owner.getFuturePool();
    try {
        while (itReplies.hasNext()) {
            Reply current = itReplies.next();
            fp.receiveFutureValue(current.getSequenceNumber(), current.getSourceBodyID(), current
                    .getResult(), current);
        }
    } catch (IOException e) {
        e.printStackTrace();
    }

    //    add pending request to reuqestQueue
    Request pendingRequest = ((CheckpointInfoPMLRB) ci).getPendingRequest();

    // pending request could be null
    if (pendingRequest != null) {
        queue.addToFront(pendingRequest);
    }

    // normal mode
    this.isRecovering = false;

    // enable communication
    this.owner.acceptCommunication();

    try {
        // update servers
        this.location.updateLocation(ownerID, owner.getRemoteAdapter());
        this.recovery.updateState(ownerID, RecoveryProcess.RUNNING);
    } catch (RemoteException e) {
        logger.error("Unable to connect with location server");
        e.printStackTrace();
    }

    this.checkpointTimer = System.currentTimeMillis();

    return 0;
}

The parameter ci is a org.objectweb.proactive.core.body.ft.checkpointing.CheckpointInfo . This object contains all the informations linked to the checkpoint used for recovering the active object, and is used to restore its state. The programmer might define his own class implementing CheckpointInfo, to add needed informations, depending on the protocol.

ProActive includes a global server that provides fault detection, active object localization, resource service and checkpoint storage. For developing a new fault-tolerance protocol, the programmer might specify the behavior of the checkpoint storage by extending the org.objectweb.proactive.core.body.ft.servers.storage.CheckpointServerImpl class. For example, only for the PML protocol and not for the CIC protocol, the checkpoint server must be able to synchronously log messages. The other parts of the server can be used directly.

To specify the recovery algorithm, the programmer has to extend the org.objectweb.proactive.core.body.ft.servers.recovery.RecoveryProcessImpl class. In the case of the CIC protocol, all the active object of the application must recover after one failure, while only the faulty process must restart with the PML protocol. This specific behavior is coded in the recovery process.

ProActive is built on top of a metaobject protocol (MOP) that permits reification of method invocation and constructor call. As this MOP is not limited to the implementation of our transparent remote objects library, it also provides an open framework for implementing powerful libraries for the Java language.

As for any other element of ProActive, this MOP is entirely written in Java and does not require any modification or extension to the Java Virtual Machine, as opposed to other metaobject protocols for Java {Kleinoeder96}. It makes extensive use of the Java Reflection API, thus requiring JDK 1.1 or higher. JDK 1.2 is required in order to suppress default Java language access control checks when executing reified non-public method or constructor calls.

If the programmer wants to implement a new metabehavior using our metaobject protocol, he (or she) has to write both a concrete (as opposed to abstract) class and an interface. The concrete class provides an implementation for the metabehavior he wants to achieve while the interface contains its declarative part.

The concrete class implements the Proxy interface and provides an implementation for the given behavior through the reify method:

public Object reify (MethodCall c) throws Throwable;

This method takes a reified call as a parameter and returns the value returned by the execution of this reified call. Automatic wrapping and unwrapping of primitive types is provided. If the execution of the call completes abruptly by throwing an exception, it is propagated to the calling method, just as if the call had not been reified.

The interface that holds the declarative part of the metabehavior has to be a subinterface of Reflect (the root interface for all metabehaviors implemented using ProActive). The purpose of this interface is to declare the name of the proxy class that implements the given behavior. Then, any instance of a class implementing this interface will be automatically created with a proxy that implements this behavior, provided that this instance is not created using the standard new keyword but rather through a special static method: MOP.newInstance. This is the only required modification to the application code. Another static method, MOP.newWrapper, adds a proxy to an already-existing object. The turnActive function of ProActive, for example, is implemented through this feature.

Here's the implementation of a very simple yet useful metabehavior: for each reified call, the name of the invoked method is printed out on the standard output stream and the call is then executed. This may be a starting point for building debugging or profiling environments.

class EchoProxy extends Object implements Proxy {
  // here are constructor and variables declaration
  // [...]
  public Object reify (MethodCall c) throws Throwable {
      System.out.println (c.getName());
      return c.execute (targetObject);
  }
}

interface Echo extends Reflect {
  public String PROXY_CLASS= 'EchoProxy';
}

All the interfaces used for declaring metabehaviors inherit directly or indirectly from Reflect. This leads to a hierarchy of metabehaviors such as shown in the figure below:

Figure 15.1. Metabehavior hierarchy

Note that ImplicitActive inherits from Active to highlight the fact that implicit synchronization somewhere always relies on some hidden explicit mechanism. Interfaces inheriting from Reflect can thus be logically grouped and assembled using multiple inheritance in order to build new metabehaviors out of existing ones.

Due to its commitment to be a 100% Java library, the MOP has a few limitations:

The Branch and Bound (BnB) consists in an algorithmic technique for exploring a solution tree from which returns the optimal solution.

The main goal of this BnB API is to provide a set of tools for helping the developers to parallelize his BnB problem implementation.

The main features are:

The following figure shows the API architecture:

Figure 16.1. The API architecture

The API active objects are:

All Workers have a group reference on all the others. The figure hereafter shows step by step how a Task can share a new better solution with all others:

Figure 16.2. Broadcasting a new solution

Finally, here is the order execution of methods:

Keep in mind that is only 'initLower/UpperBound' and 'split' methods are called on the root task. The 'execute' method is called on the root task's splitted task.

This example solves the permutation flowshop scheduling problem, with the monoobjective case. The main objective is to minimized the overall completion time for all the jobs, i.e. makespan. A flowshop problem can be represented as a set of n jobs; this jobs have to be scheduled on a set of m machines. Each jobs is defined by a set of m distinct operations. The goal consists to determine the sequence used for all machines to execute operations.

The algorithm used to find the best solution, tests all permutations and try to cut bad branches is the following one:

First, the Flowshop Task:

import org.objectweb.proactive.api.PAActiveObject;
import org.objectweb.proactive.extra.branchnbound.core.Result;
import org.objectweb.proactive.extra.branchnbound.core.Task;
import org.objectweb.proactive.extra.branchnbound.core.exception.NoResultsException;


/**
 * A Task for the FlowShop problem.
 *
 * A FlowShopTask can split the problem in subproblem and compute its best
 * makespan. FlowShopTask extends Task, this allow to take advantage of the
 * branch and bound api from ProActive, which manage task comunication and
 * repartition on the available nodes.
 *
 * @author The ProActive Team
 */
public class FlowShopTask extends Task {
    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    //in ms
    private static final long MAX_TIME_TO_SPLIT = 120000; // 2'
    private FlowShop fs;
    private FlowShopResult fsr;

    /**
     * The permutation with we work
     */
    private int[] currentPerm;

    /**
     * The best know permutation and its makespan
     */

    // private int[] bestPerm;
    // private long bestMakespan;
    /**
     * The last permutation we must explore.
     */
    private int[] lastPerm;

    /**
     * The depth tree where we tests all permutations
     */
    private int depth;

    /**
     * for benchmark
     */
    private boolean com;
    private boolean randomInit;

    /**
     *
     */
    private long lowerBound;
    private long upperBound;
    private Result r;

    public FlowShopTask() {
        // the empty no args constructor for ProActive
    }

    /**
     * Contruct a Task which search solution for all permutations to the
     * Flowshop problem. Use it to create the root Task.
     *
     * @param fs the description of the Flowshop problem
     * @param com for bench
     * @param randomInit for bench
     */
    public FlowShopTask(FlowShop fs, long lowerBound, long upperBound, boolean com, boolean randomInit) {
        this(fs, lowerBound, upperBound, null, null, 0, com, randomInit);
        currentPerm = new int[fs.jobs.length];
        for (int i = 0; i < currentPerm.length; i++) {
            currentPerm[i] = i;
        }
    }

    /**
     * @param fs
     * @param lowerBound
     * @param upperBound
     * @param currentPerm
     * @param lastPerm
     * @param depth
     * @param com
     * @param randomInit
     */
    public FlowShopTask(FlowShop fs, long lowerBound, long upperBound, int[] currentPerm, int[] lastPerm,
            int depth, boolean com, boolean randomInit) {
        this.fs = fs;
        this.fsr = new FlowShopResult();
        this.lowerBound = lowerBound;
        this.upperBound = upperBound;
        this.currentPerm = (currentPerm == null) ? null : (int[]) currentPerm.clone();
        this.lastPerm = (lastPerm == null) ? null : (int[]) lastPerm.clone();
        this.depth = depth;
        this.com = com;
        this.randomInit = randomInit;
        this.r = new Result();
    }

}

Now, implement all Task abstract methods.

Computation bound methods:

@Override
public void initLowerBound() {
    if (lowerBound == -1) {
        lowerBound = FlowShop.computeLowerBound(this.fs);
        Main.logger.info("We compute a lower bound: " + lowerBound);
    }
}

@Override
public void initUpperBound() {
    int[] randomPerm = currentPerm.clone();
    for (int i = depth + 1; i < randomPerm.length; i++) {
        int randomI = (int) (i + (Math.random() * (randomPerm.length - (i + 1))));
        int tmp = randomPerm[i];
        randomPerm[i] = randomPerm[randomI];
        randomPerm[randomI] = tmp;
    }
    Main.logger.info("initUpperBound => " +
        (randomInit ? ("random Perm : " + Permutation.string(randomPerm) + " her makespan " + FlowShop
                .computeMakespan(fs, randomPerm)) : (" non random Perm " +
            Permutation.string(currentPerm) + FlowShop.computeMakespan(fs, currentPerm))));
    fsr.makespan = randomInit ? FlowShop.computeMakespan(fs, randomPerm) : FlowShop.computeMakespan(fs,
            currentPerm);
    fsr.permutation = randomInit ? randomPerm : (int[]) currentPerm.clone();
}

The split method:

/**
 * Split the root Task in subtask. Can be called by the method execute() if
 * we want to split again.
 *
 * @see org.objectweb.proactive.extra.branchnbound.core.Task#split()
 */
@Override
public Vector split() {
    int nbTasks = fs.jobs.length - depth;

    Vector tasks = new Vector(nbTasks);

    int[] perm = currentPerm.clone();
    int[] beginPerm = new int[perm.length];

    do {
        if ((lastPerm != null) && (Permutation.compareTo(perm, lastPerm) > 0)) {
            break;
        }
        System.arraycopy(perm, 0, beginPerm, 0, perm.length);

        Permutation.jumpPerm(perm, perm.length - (depth + 1));

        tasks.add(new FlowShopTask(fs, this.lowerBound, this.upperBound, beginPerm, perm, depth + 1, com,
            randomInit));
    } while (Permutation.nextPerm(perm) != null);
    if (tasks.size() != 0) {
        ((FlowShopTask) tasks.lastElement()).lastPerm = lastPerm;
    }
    Main.logger.info("We split in " + tasks.size() + " subtask at depth " + depth + " : " +
        Permutation.string(currentPerm) + ", " + Permutation.string(lastPerm));

    /*
     * Iterator i = tasks.iterator(); while (i.hasNext()) { Task t = (Task) i.next();
     * Main.logger.info(t); Main.logger.info(""); }
     */
    return tasks;
}