This tutorial explains how to create a simple component named Slave using ADL files. This component looks like that:

Figure 3.1. Slave component

The interface used for this example is the following one:

package org.objectweb.proactive.examples.userguide.components.adl.starter;

import java.util.List;


/**
 * @author The ProActive Team
 */
public interface Itf1 {
    void compute(List<String> arg);
}

This interface defines a compute() method which is implemented in the following SlaveImpl class:

package org.objectweb.proactive.examples.userguide.components.adl.starter;

import java.util.List;

import org.objectweb.proactive.api.PAActiveObject;


/**
 * @author The ProActive Team
 */
public class SlaveImpl implements Itf1 {

    public void compute(List<String> arg) {
        String str = "\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this + "\n";
        str += "arg: ";
        for (int i = 0; i < arg.size(); i++) {
            str += arg.get(i);
            if (i + 1 < arg.size()) {
                str += " - ";
            }
        }
        System.err.println(str);
    }
}

In order to define the component, we need an ADL file which describes all the interfaces, the component content class as well as potential binding between interfaces. In that case, the file is very simple:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.starter.adl.Slave">
    <interface signature="org.objectweb.proactive.examples.userguide.components.adl.starter.Itf1" role="server" name="i1"/>

    <content class="org.objectweb.proactive.examples.userguide.components.adl.starter.SlaveImpl"/>

    <controller desc="primitive"/>
</definition>

With the interface tag, we can define components interfaces. In our case, there is only one interface whose signature is defined in org.objectweb.proactive.examples.userguide.components.adl.starter.Itf1, which is a server interface and whose name is i1. As for the content tag, it enables to define the component contents. Eventually, the controller tag indicates whether the component is a primitive component or a composite one (component composed of several components).

Now that we have created our Slave component, it still remain to instantiate it and to use it. That is our proposed work for this first exercise.

Here is the main class that we want you to fill in:

package org.objectweb.proactive.examples.userguide.components.adl.starter;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.adl.Factory;
import org.objectweb.fractal.api.Component;
import org.objectweb.proactive.core.component.adl.FactoryFactory;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Get the Factory
        // TODO: Create Component
        // TODO: Start Component
        // TODO: Get the interface i1
        // TODO: Call the compute method
        // TODO: Stop Component

        System.exit(0);
    }
}

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory (not the one located into the ProActive directory) and type:

build components.adl.starter

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the adl-starter.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node494021116Slave: org.objectweb.proactive.examples.userguide.components.adl.starter.SlaveImpl@15fa713
arg: hello - bye

Here is how you should have filled in the main() method:

package org.objectweb.proactive.examples.userguide.components.adl.starter;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.adl.Factory;
import org.objectweb.fractal.api.Component;
import org.objectweb.proactive.core.component.adl.FactoryFactory;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Get the Factory
        Factory factory = FactoryFactory.getFactory();
        // TODO: Create Component
        Map<String, Object> context = new HashMap<String, Object>();
        Component slave = (Component) factory.newComponent(
                "org.objectweb.proactive.examples.userguide.components.adl.starter.adl.Slave", context);
        // TODO: Start Component
        GCM.getGCMLifeCycleController(slave).startFc();
        // TODO: Get the interface i1
        Itf1 itf1 = (Itf1) slave.getFcInterface("i1");
        // TODO: Call the compute method
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        itf1.compute(arg);
        // TODO: Stop Component
        GCM.getGCMLifeCycleController(slave).stopFc();

        System.exit(0);
    }
}

This tutorial shows how to create a composite component composed of a Master and a Slave component. This tutorials aims at making you manipulate ADL files. Java sources are filled in but they will be explain to you however. These explanations will be useful for the next tutorials.

This composite can be represented as follows:

Figure 3.2. Composite component

The Slave component is exactly the same as in the previous tutorial. It is defined by the Itf1 interface implemented by the SlaveImpl class and the corresponding ADL file is Slave.fractal.

Concerning the Master component, it is defined by the following Runner interface:

package org.objectweb.proactive.examples.userguide.components.adl.composite;

import java.util.List;


/**
 * @author The ProActive Team
 */
public interface Runner {
    public void run(List<String> arg);
}

which is implemented by the MasterImpl class:

package org.objectweb.proactive.examples.userguide.components.adl.composite;

import java.util.List;

import org.objectweb.fractal.api.NoSuchInterfaceException;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.IllegalBindingException;
import org.objectweb.fractal.api.control.IllegalLifeCycleException;


/**
 * @author The ProActive Team
 */
public class MasterImpl implements Runner, BindingController {
    public static String ITF_CLIENT = "i1";
    private Itf1 i1;

    public void run(List<String> arg) {
        i1.compute(arg);
    }

    public void bindFc(String clientItfName, Object serverItf) throws NoSuchInterfaceException,
            IllegalBindingException, IllegalLifeCycleException {
        if (ITF_CLIENT.equals(clientItfName)) {
            i1 = (Itf1) serverItf;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public String[] listFc() {
        return new String[] { ITF_CLIENT };
    }

    public Object lookupFc(String clientItfName) throws NoSuchInterfaceException {
        if (ITF_CLIENT.equals(clientItfName)) {
            return i1;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public void unbindFc(String clientItfName) throws NoSuchInterfaceException, IllegalBindingException,
            IllegalLifeCycleException {
        if (ITF_CLIENT.equals(clientItfName)) {
            i1 = null;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

}

This class contains an Itf1 member representing the client interface which is used in the BindingController method. These methods are:

The ADL file corresponding to this component is the Master.fractal file which is almost empty since it will be one of your work.

The only things that remain to do now so as to be able to use our composite component are first, to define that composite with an ADL file and then to write our main method to use it. The writing of the composite ADL file is the second work you have to do and the main method, which is quite similar to the one you have written in the previous tutorial, is exposed hereafter.

package org.objectweb.proactive.examples.userguide.components.adl.composite;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.adl.Factory;
import org.objectweb.fractal.api.Component;
import org.objectweb.proactive.core.component.adl.FactoryFactory;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {
        Factory factory = FactoryFactory.getFactory();

        Map<String, Object> context = new HashMap<String, Object>();
        Component composite = (Component) factory.newComponent(
                "org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Composite", context);

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

You can notice that the only thing that changed is the first argument of the newComponent() method which is now the name of the ADL file representing the composite component.

Here are the two ADL files that you have to fill in:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<!-- TODO: Write the Master Component definition -->
<!-- This Component has 2 interfaces: -->
<!-- Server: org.objectweb.proactive.examples.userguide.components.adl.composite.Runner -->
<!-- Client: org.objectweb.proactive.examples.userguide.components.adl.composite.Itf1 -->

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.composite.Runner" role="server" name="runner"/>

  <!-- TODO: Add the Master Component -->
  <component name="Slave" definition="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Slave"/>

  <!-- TODO: Do the bindings -->

  <!-- TODO: Indicates that this component is a composite component -->
</definition>

We propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.adl.composite

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the adl-composite.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node82553583Slave: org.objectweb.proactive.examples.userguide.components.adl.composite.SlaveImpl@50078e
arg: hello - world

Here is how you should have filled in the two ADL files:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<!-- TODO: Write the Master Component definition -->
<!-- This Component has 2 interfaces: -->
<!-- Server: org.objectweb.proactive.examples.userguide.components.adl.composite.Runner -->
<!-- Client: org.objectweb.proactive.examples.userguide.components.adl.composite.Itf1 -->
<definition name="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Master">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.composite.Runner" role="server" name="runner"/>
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.composite.Itf1" role="client" name="i1"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.composite.MasterImpl"/>

  <controller desc="primitive"/>
</definition>

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.composite.Runner" role="server" name="runner"/>

  <!-- TODO: Add the Master Component -->
  <component name="Master" definition="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Master"/>
  <component name="Slave" definition="org.objectweb.proactive.examples.userguide.components.adl.composite.adl.Slave"/>

  <!-- TODO: Do the bindings -->
  <binding client="this.runner" server="Master.runner"/>
  <binding client="Master.i1" server="Slave.i1"/>

  <!-- TODO: Indicates that this component is a composite component -->
  <controller desc="composite"/>
</definition>

In this tutorial, we will add a new server interface to the Slave component and bind it to a new client interface of the master component. Our composite component will therefore look like as follows:

Figure 3.3. Composite component with the new interface

We introduce a second interface named Itf2 which source code is the following one:

package org.objectweb.proactive.examples.userguide.components.adl.interfaces;

/**
 * @author The ProActive Team
 */
public interface Itf2 {
    void doNothing();
}

The aim of this tutorial is to make you modify all the necessary files to add this new interface.

The first thing to do when adding a new interface is to implement it. In our case, it is SlaveImpl class that implements it:

package org.objectweb.proactive.examples.userguide.components.adl.interfaces;

import java.util.List;

import org.objectweb.proactive.api.PAActiveObject;


/**
 * @author The ProActive Team
 */
public class SlaveImpl implements Itf1
//TODO: Add the new interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2
{

    public void compute(List<String> arg) {
        String str = "\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this + "\n";
        str += "arg: ";
        for (int i = 0; i < arg.size(); i++) {
            str += arg.get(i);
            if (i + 1 < arg.size()) {
                str += " - ";
            }
        }
        System.err.println(str);
    }

    public void doNothing() {
        System.err.println("\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this +
            "\nI do nothing");
    }
}

Then, you have to modify the ADL file of the Slave component to add this new interface:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Slave">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf1" role="server" name="i1"/>
  <!-- TODO: Add the server interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2 -->

  <content class="org.objectweb.proactive.examples.userguide.components.adl.interfaces.SlaveImpl"/>

  <controller desc="primitive"/>
</definition>

Now, you have to do the same thing for the Master component, that is, you have to add a new interface. However, in that case, you have to add a client interface and thus, you have to modify the BindingController methods:

package org.objectweb.proactive.examples.userguide.components.adl.interfaces;

import java.util.List;

import org.objectweb.fractal.api.NoSuchInterfaceException;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.IllegalBindingException;
import org.objectweb.fractal.api.control.IllegalLifeCycleException;


/**
 * @author The ProActive Team
 */
public class MasterImpl implements Runner, BindingController {
    public static String ITF_CLIENT_1 = "i1";
    public static String ITF_CLIENT_2 = "i2";
    private Itf1 i1;
    private Itf2 i2;

    public void run(List<String> arg) {
        i1.compute(arg);
        i2.doNothing();
    }

    public void bindFc(String clientItfName, Object serverItf) throws NoSuchInterfaceException,
            IllegalBindingException, IllegalLifeCycleException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            i1 = (Itf1) serverItf;
        }
        // TODO: Bind the new client interface
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public String[] listFc() {
        return new String[] { ITF_CLIENT_1
        //TODO: Add the new client interface name
        };
    }

    public Object lookupFc(String clientItfName) throws NoSuchInterfaceException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            return i1;
        }
        // TODO: Return the interface to which the new client interface is bound
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public void unbindFc(String clientItfName) throws NoSuchInterfaceException, IllegalBindingException,
            IllegalLifeCycleException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            i1 = null;
        }
        // TODO: Unbind the new client interface
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }
}

Then, Master's ADL file needs also to be modified:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Master">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Runner" role="server" name="runner"/>
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf1" role="client" name="i1"/>
  <!-- TODO: Add the new client interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2 -->

  <content class="org.objectweb.proactive.examples.userguide.components.adl.interfaces.MasterImpl"/>

  <controller desc="primitive"/>
</definition>

Finally, you have to add a binding in the Composite's ADL file:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Runner" role="server" name="runner"/>

  <component name="Master" definition="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Master"/>
  <component name="Slave" definition="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Slave"/>

  <binding client="this.runner" server="Master.runner"/>
  <binding client="Master.i1" server="Slave.i1"/>
  <!-- TODO: Do the binding for the new interface -->

  <controller desc="composite"/>
</definition>

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.adl.interfaces

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the adl-interfaces.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node438557290Slave: org.objectweb.proactive.examples.userguide.components.adl.interfaces.SlaveImpl@97aaa6
arg: hello - world

rmi://kisscool.inria.fr:6618/Node438557290Slave: org.objectweb.proactive.examples.userguide.components.adl.interfaces.SlaveImpl@97aaa6
I do nothing

Here is the solution:

package org.objectweb.proactive.examples.userguide.components.adl.interfaces;

import java.util.List;

import org.objectweb.proactive.api.PAActiveObject;


/**
 * @author The ProActive Team
 */
public class SlaveImpl implements Itf1
//TODO: Add the new interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2
        , Itf2
{

    public void compute(List<String> arg) {
        String str = "\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this + "\n";
        str += "arg: ";
        for (int i = 0; i < arg.size(); i++) {
            str += arg.get(i);
            if (i + 1 < arg.size()) {
                str += " - ";
            }
        }
        System.err.println(str);
    }

    public void doNothing() {
        System.err.println("\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this +
            "\nI do nothing");
    }
}

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Slave">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf1" role="server" name="i1"/>
  <!-- TODO: Add the server interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2 -->
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2" role="server" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.interfaces.SlaveImpl"/>

  <controller desc="primitive"/>
</definition>

package org.objectweb.proactive.examples.userguide.components.adl.interfaces;

import java.util.List;

import org.objectweb.fractal.api.NoSuchInterfaceException;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.IllegalBindingException;
import org.objectweb.fractal.api.control.IllegalLifeCycleException;


/**
 * @author The ProActive Team
 */
public class MasterImpl implements Runner, BindingController {
    public static String ITF_CLIENT_1 = "i1";
    public static String ITF_CLIENT_2 = "i2";
    private Itf1 i1;
    private Itf2 i2;

    public void run(List<String> arg) {
        i1.compute(arg);
        i2.doNothing();
    }

    public void bindFc(String clientItfName, Object serverItf) throws NoSuchInterfaceException,
            IllegalBindingException, IllegalLifeCycleException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            i1 = (Itf1) serverItf;
        }
        // TODO: Bind the new client interface
        else if (ITF_CLIENT_2.equals(clientItfName)) {
            i2 = (Itf2) serverItf;
        }
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public String[] listFc() {
        return new String[] { ITF_CLIENT_1
        //TODO: Add the new client interface name
                , ITF_CLIENT_2
        };
    }

    public Object lookupFc(String clientItfName) throws NoSuchInterfaceException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            return i1;
        }
        // TODO: Return the interface to which the new client interface is bound
        else if (ITF_CLIENT_2.equals(clientItfName)) {
            return i2;
        }
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public void unbindFc(String clientItfName) throws NoSuchInterfaceException, IllegalBindingException,
            IllegalLifeCycleException {
        if (ITF_CLIENT_1.equals(clientItfName)) {
            i1 = null;
        }
        // TODO: Unbind the new client interface
        else if (ITF_CLIENT_2.equals(clientItfName)) {
            i2 = null;
        }
        else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }
}

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Master">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Runner" role="server" name="runner"/>
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf1" role="client" name="i1"/>
  <!-- TODO: Add the new client interface org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2 -->
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Itf2" role="client" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.interfaces.MasterImpl"/>

  <controller desc="primitive"/>
</definition>

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.interfaces.Runner" role="server" name="runner"/>

  <component name="Master" definition="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Master"/>
  <component name="Slave" definition="org.objectweb.proactive.examples.userguide.components.adl.interfaces.adl.Slave"/>

  <binding client="this.runner" server="Master.runner"/>
  <binding client="Master.i1" server="Slave.i1"/>
  <!-- TODO: Do the binding for the new interface -->
  <binding client="Master.i2" server="Slave.i2"/>

  <controller desc="composite"/>
</definition>

This tutorial will explain you how to create a multicast interface in order to get a component looking like this:

Figure 3.4. Composite component with a multicast client interface

For this, a new interface called Itf1Multicast will be added and will be used for the client interface of the Master component.

package org.objectweb.proactive.examples.userguide.components.adl.multicast;

import java.util.List;


/**
 * @author The ProActive Team
 */
public interface Itf1Multicast {
    // Optional TODO: Change the dispatch parameters policy to Round Robin
    void compute(List<String> arg);
}

Except this new interface and the replacement of

private Itf1 i1

by

private Itf1Multicast i1

in the MasterImpl class, there is no need of changes in Java code source. Only changes in ADL files are needed.

First, you have to change the client interface into the Master's ADL file in order to refer to the Itf1Multicast signature. You also have to change its cardinality to indicate that this interface is now a multicast interface.

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Master">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Runner" role="server" name="runner"/>

  <!-- TODO: Add the client multicast interface org.objectweb.proactive.examples.userguide.components.adl.multicast.Itf1Multicast -->
  <!-- Note: do not forget to set its cardinality -->

  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Itf2" role="client" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.multicast.MasterImpl"/>

  <controller desc="primitive"/>
</definition>

Then, you have to modify the Composite's ADL file to add a new Slave component and to add also some bindings.

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Runner" role="server" name="runner"/>

  <component name="Master" definition="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Master"/>
  <component name="Slave1" definition="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Slave"/>

  <!-- TODO: Add a second Slave Component -->

  <binding client="this.runner" server="Master.runner"/>

  <!-- TODO: Do the binding between the Master Component and the Slave Components on the Multicast Interface -->

  <binding client="Master.i2" server="Slave1.i2"/>

  <controller desc="composite"/>
</definition>

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.adl.multicast

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the adl-interfaces.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node1434753324Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@3861e6
arg: hello - world

rmi://kisscool.inria.fr:6618/Node1434753324Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@1132e76
arg: hello - world

rmi://kisscool.inria.fr:6618/Node1434753324Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@3861e6
I do nothing

If you have done the optional work, you should have a display as follows:

rmi://kisscool.inria.fr:6618/Node1653076599Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@789d63
arg: hello

rmi://kisscool.inria.fr:6618/Node1653076599Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@a4ed99
arg: world

rmi://kisscool.inria.fr:6618/Node1653076599Slave: org.objectweb.proactive.examples.userguide.components.adl.multicast.SlaveImpl@789d63
I do nothing
         

Here are solutions for the ADL files:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Master">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Runner" role="server" name="runner"/>

  <!-- TODO: Add the client multicast interface org.objectweb.proactive.examples.userguide.components.adl.multicast.Itf1Multicast -->
  <!-- Note: do not forget to set its cardinality -->
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Itf1Multicast" role="client" name="i1" cardinality="multicast"/>

  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Itf2" role="client" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.multicast.MasterImpl"/>

  <controller desc="primitive"/>
</definition>

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Composite">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.multicast.Runner" role="server" name="runner"/>

  <component name="Master" definition="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Master"/>
  <component name="Slave1" definition="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Slave"/>

  <!-- TODO: Add a second Slave Component -->
  <component name="Slave2" definition="org.objectweb.proactive.examples.userguide.components.adl.multicast.adl.Slave"/>

  <binding client="this.runner" server="Master.runner"/>

  <!-- TODO: Do the binding between the Master Component and the Slave Components on the Multicast Interface -->
  <binding client="Master.i1" server="Slave1.i1"/>
  <binding client="Master.i1" server="Slave2.i1"/>

  <binding client="Master.i2" server="Slave1.i2"/>

  <controller desc="composite"/>
</definition>

If you do not want to do the optional work, you do not have to modify other files. Otherwise, if you want to change the dispatch parameter policy, you have to make some little modification in Java code sources. The first one is to change the signature of the compute method in the Itf1Multicast interface. Change the line

void compute(List<String> arg);

by

void compute(@ParamDispatchMetadata(mode = ParamDispatchMode.ROUND_ROBIN) List<String> arg);

Then, you have to change the Itf1 interface since the server interface will no longer receive a list of String but instead, just a String. Thus, in the Itf1 interface, change the line

void compute(List<String> arg);

by

void compute(String arg);

and in the SlaveImpl class, change the implementation of compute so that it returns a String:

public void compute(String arg) {
   String str = "\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this + "\n";
   str += "arg: " + arg;
   System.err.println(str);
}

Now that we know how to use component, we would like to benefit from active object properties. One of these is the deployment on several Java Virtual Machines (JVM). This tutorial will explain you how to deploy our component on 3 differents JVM. For this, we will use GCM deployment model. If you have done the active object tutorials, you should know what this model is and how to use it. If not, please refer to Chapter 21. ProActive Grid Component Model Deployment.

For the deployment, we will use the following application description:

<GCMApplication xmlns="urn:gcm:application:1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www-sop.inria.fr/oasis/ProActive/schemas http://proactive.inria.fr/schemas/gcm/1.0/ApplicationDescriptorSchema.xsd">

    <environment>
        <javaPropertyVariable name="user.home" />
        <javaPropertyVariable name="user.name" />
        <javaPropertyVariable name="java.home" />
        <javaPropertyVariable name="proactive.home" />
    </environment>

    <application>
        <proactive base="root" relpath="${proactive.home}">
            <configuration>
                <java base="root" relpath="${java.home}/bin/java" />
                <applicationClasspath>
                    <pathElement base="root" relpath="${proactive.home}/classes" />
                </applicationClasspath>
            </configuration>
            <virtualNode id="master-node" capacity="1">
                <nodeProvider refid="MASTER_REMOTE_PROVIDER" />
            </virtualNode>
            <virtualNode id="slave-node" capacity="2">
                <nodeProvider refid="SLAVE_REMOTE_PROVIDER" />
            </virtualNode>
        </proactive>
    </application>

    <resources>
        <nodeProvider id="MASTER_REMOTE_PROVIDER">
            <file path="GCMD_Local.xml" />
        </nodeProvider>
        <nodeProvider id="SLAVE_REMOTE_PROVIDER">
            <file path="GCMD_Local.xml" />
        </nodeProvider>
    </resources>
</GCMApplication>

which refers to the following deployment descriptor, used both for the deployment of the Master component and for the Slave components:

<GCMDeployment xmlns="urn:gcm:deployment:1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:gcm:deployment:1.0 http://proactive.inria.fr/schemas/gcm/1.0/ExtensionSchemas.xsd">

    <environment>
        <javaPropertyVariable name="user.home" />
        <javaPropertyVariable name="user.name" />
        <javaPropertyDescriptorDefault name="os" value="windows" />
    </environment>

    <resources>
        <host refid="hLocalhost" />
    </resources>

    <infrastructure>

        <hosts>
            <host id="hLocalhost" os="${os}" hostCapacity="3" vmCapacity="1">
                <homeDirectory base="root" relpath="${user.home}" />
            </host>

        </hosts>

    </infrastructure>
</GCMDeployment>

The main things that change comparing to the previous tutorial are the Main method where deployment has to be loaded and used, and ADL files into which virtual node of the corresponding component deployment has to be added.

First, you have to add a virtual-node tag into the Slave's ADL file to indicate where to deploy the Slave components:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.deployment.adl.Slave">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.deployment.Itf1" role="server" name="i1"/>
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.deployment.Itf2" role="server" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.deployment.SlaveImpl"/>

  <controller desc="primitive"/>

  <!-- TODO: Affect this Component to the virtual node "slave-node" -->
</definition>

Then, you have to modify the Main method so as to load and use the application descriptor.

package org.objectweb.proactive.examples.userguide.components.adl.deployment;

import java.io.File;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.adl.Factory;
import org.objectweb.fractal.api.Component;
import org.objectweb.proactive.core.component.adl.FactoryFactory;
import org.objectweb.proactive.extensions.gcmdeployment.PAGCMDeployment;
import org.objectweb.proactive.gcmdeployment.GCMApplication;
import org.objectweb.proactive.gcmdeployment.GCMVirtualNode;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Load the Application Descriptor

        // TODO: Start the deployment

        Factory factory = FactoryFactory.getFactory();

        Map<String, Object> context = new HashMap<String, Object>();

        // TODO: Put the Application Descriptor in the context

        Component composite = (Component) factory
                .newComponent(
                        "org.objectweb.proactive.examples.userguide.components.adl.deployment.adl.Composite",
                        context);

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.adl.deployment

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the adl-deployment.[sh|bat] script. You should then see a display looking like this:

--- User Guide: ADL Deployment ---------------------------------------------
30447@kisscool - [INFO oactive.remoteobject] Remote Object Factory provider <pamr, class org.objectweb.proactive.extra.messagerouting.remoteobject.MessageRoutingRemoteObjectFactory> found
30447@kisscool - [INFO    communication.rmi] Created a new registry on port 6618
30447@kisscool - [INFO        proactive.mop] Generating class : pa.stub.org.objectweb.proactive.gcmdeployment._StubGCMVirtualNode
30447@kisscool - [INFO        proactive.mop] Generating class : pa.stub.org.objectweb.lector -Djava.security.policy="/home/ffonteno/proactive-git/programming/tutorials/scripts/proactive.java.policy" org.objectweb.proactive.core.runtime.StartPARuntime -p rmi://kisscool.inria.fr:6618/PA_JVM798723297 -c 1 -i 1 -d 8194810407958514089 -b http://kisscool.inria.fr:49352/classServer/  '
30447@kisscool - [INFO                job.1] executing command=/usr/bin/ssh -l ffonteno localhost '"/home/ffonteno/src/java/jdk1.5.0_17/jre/bin/java" -cp "/home/ffonteno/proactive-git/programming/tutorials/dist/lib/ProActive.jar:/home/ffonteno/proactive-git/programming/tutorials/classes" -Dproactive.log4j.collector=rmi://kisscool.inria.fr:6618/8194810407958514089/logCollector -Djava.security.policy="/home/ffonteno/proactive-git/programming/tutorials/scripts/proactive.java.policy" org.objectweb.proactive.core.runtime.StartPARuntime -p rmi://kisscool.inria.fr:6618/PA_JVM798723297 -c 1 -i 1 -d 8194810407958514089 -b http://kisscool.inria.fr:49352/classServer/  '
30447@kisscool - [INFO      deployment.GCMD] Starting group id=gCluster #commands=1
30447@kisscool - [INFO                job.2] executing command=/usr/bin/ssh -l ffonteno localhost '"/home/ffonteno/src/java/jdk1.5.0_17/jre/bin/java" -cp "/home/ffonteno/proactive-git/programming/tutorials/dist/lib/ProActive.jar:/home/ffonteno/proactive-git/programming/tutorials/classes" -Dproactive.log4j.collector=rmi://kisscool.inria.fr:6618/8194810407958514089/logCollector -Djava.security.policy="/home/ffonteno/proactive-git/programming/tutorials/scripts/proactive.java.policy" org.objectweb.proactive.core.runtime.StartPARuntime -p rmi://kisscool.inria.fr:6618/PA_JVM798723297 -c 1 -i 2 -d 8194810407958514089 -b http://kisscool.inria.fr:49352/classServer/  '
30447@kisscool - [INFO        proactive.mop] Generating class : pa.stub.org.objectweb.proactive.core.util.log.remote._StubProActiveLogCollector
30447@kisscool - [INFO        proactive.mop] Generating class : pa.stub.org.objectweb.proactive.examples.userguide.components.adl.deployment._StubMasterImpl
30447@kisscool - [INFO        proactive.mop] Generating class : pa.stub.org.objectweb.proactive.examples.userguide.components.adl.deployment._StubSlaveImpl
30447@kisscool - [INFO                job.1]
30447@kisscool - [INFO                job.1] rmi://kisscool.inria.fr:6618/PA_JVM539286369_GCMNode-0Slave: org.objectweb.proactive.examples.userguide.components.adl.deployment.SlaveImpl@e931d9
30447@kisscool - [INFO                job.1] arg: hello - world
30447@kisscool - [INFO                job.0]
30447@kisscool - [INFO                job.0] rmi://kisscool.inria.fr:6618/PA_JVM1043221418_GCMNode-0Slave: org.objectweb.proactive.examples.userguide.components.adl.deployment.SlaveImpl@e9a7c2
30447@kisscool - [INFO                job.0] arg: hello - world
30447@kisscool - [INFO                job.0]
30447@kisscool - [INFO                job.0] rmi://kisscool.inria.fr:6618/PA_JVM1043221418_GCMNode-0Slave: org.objectweb.proactive.examples.userguide.components.adl.deployment.SlaveImpl@e9a7c2
30447@kisscool - [INFO                job.0] I do nothing

Here are the solutions:

<!DOCTYPE definition PUBLIC "-//objectweb.org//DTD Fractal ADL 2.0//EN" "classpath://org/objectweb/proactive/core/component/adl/xml/proactive.dtd">

<definition name="org.objectweb.proactive.examples.userguide.components.adl.deployment.adl.Slave">
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.deployment.Itf1" role="server" name="i1"/>
  <interface signature="org.objectweb.proactive.examples.userguide.components.adl.deployment.Itf2" role="server" name="i2"/>

  <content class="org.objectweb.proactive.examples.userguide.components.adl.deployment.SlaveImpl"/>

  <controller desc="primitive"/>

  <!-- TODO: Affect this Component to the virtual node "slave-node" -->
  <virtual-node name="slave-node"/>
</definition>

package org.objectweb.proactive.examples.userguide.components.adl.deployment;

import java.io.File;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.adl.Factory;
import org.objectweb.fractal.api.Component;
import org.objectweb.proactive.core.component.adl.FactoryFactory;
import org.objectweb.proactive.extensions.gcmdeployment.PAGCMDeployment;
import org.objectweb.proactive.gcmdeployment.GCMApplication;
import org.objectweb.proactive.gcmdeployment.GCMVirtualNode;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Load the Application Descriptor
        String descriptorPath = "file://" +
            System.getProperty("proactive.home") +
            "/src/Examples/org/objectweb/proactive/examples/userguide/components/adl/deployment/descriptors/application_descriptor.xml";
        // This tricky line enables to use this path in both Linux and Windows OS
        File deploymentFile = new File((new URL(descriptorPath)).toURI().getPath());
        GCMApplication gcma = PAGCMDeployment.loadApplicationDescriptor(deploymentFile);

        // TODO: Start the deployment
        gcma.startDeployment();
        gcma.waitReady();
        GCMVirtualNode vn = gcma.getVirtualNode("slave-node");
        vn.waitReady();

        Factory factory = FactoryFactory.getFactory();

        Map<String, Object> context = new HashMap<String, Object>();

        // TODO: Put the Application Descriptor in the context
        context.put("deployment-descriptor", gcma);

        Component composite = (Component) factory
                .newComponent(
                        "org.objectweb.proactive.examples.userguide.components.adl.deployment.adl.Composite",
                        context);

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

This tutorial explains how to create a simple component named Slave using the API. This component looks like that:

Figure 3.5. Slave component

The interface used for this example is the following one:

package org.objectweb.proactive.examples.userguide.components.api.starter;

import java.util.List;


/**
 * @author The ProActive Team
 */
public interface Itf1 {
    void compute(List<String> arg);
}

This interface defines a compute() method which is implemented in the following SlaveImpl class:

package org.objectweb.proactive.examples.userguide.components.api.starter;

import java.util.List;

import org.objectweb.proactive.api.PAActiveObject;


/**
 * @author The ProActive Team
 */
public class SlaveImpl implements Itf1 {

    public void compute(List<String> arg) {
        String str = "\n" + PAActiveObject.getBodyOnThis().getNodeURL() + "Slave: " + this + "\n";
        str += "arg: ";
        for (int i = 0; i < arg.size(); i++) {
            str += arg.get(i);
            if (i + 1 < arg.size()) {
                str += " - ";
            }
        }
        System.err.println(str);
    }

}

These two classes are strictly the same as the ones used in the Starter tutorial using ADL files. In this tutorial, instead of describing the component into an ADL file, we will describe it directly in the main() method.

Here is the main() method that you have to complete:

package org.objectweb.proactive.examples.userguide.components.api.starter;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Get the Bootstrap Component
        // TODO: Get the TypeFactory
        // TODO: Get the GenericFactory
        // TODO: Create the i1 Interface Type (org.objectweb.proactive.examples.userguide.components.api.starter.Itf1)
        // TODO: Create the Slave Component type
        // TODO: Create the Slave Component

        GCM.getGCMLifeCycleController(slave).startFc();

        Itf1 itf1 = (Itf1) slave.getFcInterface("i1");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        itf1.compute(arg);

        GCM.getGCMLifeCycleController(slave).stopFc();

        System.exit(0);
    }
}

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory (not the one located into the ProActive directory) and type:

build components.api.starter

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the api-starter.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node564429316Slave: org.objectweb.proactive.examples.userguide.components.api.starter.SlaveImpl@109da93
arg: hello - world

Here is how you should have filled in the main() method:

package org.objectweb.proactive.examples.userguide.components.api.starter;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {

        // TODO: Get the Bootstrap Component
        Component boot = Utils.getBootstrapComponent();
        // TODO: Get the TypeFactory
        GCMTypeFactory tf = GCM.getGCMTypeFactory(boot);
        // TODO: Get the GenericFactory
        GenericFactory gf = GCM.getGenericFactory(boot);
        // TODO: Create the i1 Interface Type (org.objectweb.proactive.examples.userguide.components.api.starter.Itf1)
        InterfaceType itf1Slave = tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.SERVER,
                TypeFactory.MANDATORY, TypeFactory.SINGLE);
        // TODO: Create the Slave Component type
        ComponentType tSlave = tf.createFcType(new InterfaceType[] { itf1Slave });
        // TODO: Create the Slave Component
        Component slave = gf.newFcInstance(tSlave, new ControllerDescription("slave", Constants.PRIMITIVE),
                SlaveImpl.class.getName());

        GCM.getGCMLifeCycleController(slave).startFc();

        Itf1 itf1 = (Itf1) slave.getFcInterface("i1");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        itf1.compute(arg);

        GCM.getGCMLifeCycleController(slave).stopFc();

        System.exit(0);
    }
}

This tutorial shows how to create a composite component composed of a Master and a Slave component.

This composite can be represented as follows:

Figure 3.6. Composite component

The Slave component is exactly the same as in the previous tutorial. It is defined by the Itf1 interface implemented by the SlaveImpl class.

Concerning the Master component, it is defined by the following Runner interface:

package org.objectweb.proactive.examples.userguide.components.api.composite;

import java.util.List;


/**
 * @author The ProActive Team
 */
public interface Runner {
    public void run(List<String> arg);
}

which is implemented by the MasterImpl class:

package org.objectweb.proactive.examples.userguide.components.api.composite;

import java.util.List;

import org.objectweb.fractal.api.NoSuchInterfaceException;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.IllegalBindingException;
import org.objectweb.fractal.api.control.IllegalLifeCycleException;


/**
 * @author The ProActive Team
 */
public class MasterImpl implements Runner, BindingController {
    public static String ITF_CLIENT = "i1";
    private Itf1 i1;

    public void run(List<String> arg) {
        i1.compute(arg);
    }

    public void bindFc(String clientItfName, Object serverItf) throws NoSuchInterfaceException,
            IllegalBindingException, IllegalLifeCycleException {
        if (ITF_CLIENT.equals(clientItfName)) {
            i1 = (Itf1) serverItf;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public String[] listFc() {
        return new String[] { ITF_CLIENT };
    }

    public Object lookupFc(String clientItfName) throws NoSuchInterfaceException {
        if (ITF_CLIENT.equals(clientItfName)) {
            return i1;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }

    public void unbindFc(String clientItfName) throws NoSuchInterfaceException, IllegalBindingException,
            IllegalLifeCycleException {
        if (ITF_CLIENT.equals(clientItfName)) {
            i1 = null;
        } else {
            throw new NoSuchInterfaceException(clientItfName);
        }
    }
}

This class contains an Itf1 member representing the client interface which is used in the BindingController method. These methods are:

The only things that remain to do now so as to be able to use our composite component are first, to define all the three components (Slave, Master and Composite) in our main() method using the Java API and then, to add the two sub-components (Master and Slave) to the Composite component and to write the two bindings.

Here is the Main class that you have to fill in:

package org.objectweb.proactive.examples.userguide.components.api.composite;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.ContentController;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {
        Component boot = Utils.getBootstrapComponent();
        GCMTypeFactory tf = GCM.getGCMTypeFactory(boot);
        GenericFactory gf = GCM.getGenericFactory(boot);
        ComponentType tComposite = tf.createFcType(new InterfaceType[] { tf.createFcItfType("runner",
                Runner.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });

        // TODO: Create the Master Component type

        ComponentType tSlave = tf.createFcType(new InterfaceType[] { tf.createFcItfType("i1", Itf1.class
                .getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });

        Component slave = gf.newFcInstance(tSlave, new ControllerDescription("slave", Constants.PRIMITIVE),
                SlaveImpl.class.getName());

        // TODO: Create the Master Component

        Component composite = gf.newFcInstance(tComposite, new ControllerDescription("composite",
            Constants.COMPOSITE), null);

        // TODO: Add slave and master components to the composite component

        // TODO: Do the bindings

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

We propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.api.composite

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the api-composite.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node480011239Slave: org.objectweb.proactive.examples.userguide.components.api.composite.SlaveImpl@c62080
arg: hello - world

Here is how you should have filled in the Main class:

package org.objectweb.proactive.examples.userguide.components.api.composite;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.control.ContentController;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {
        Component boot = Utils.getBootstrapComponent();
        GCMTypeFactory tf = GCM.getGCMTypeFactory(boot);
        GenericFactory gf = GCM.getGenericFactory(boot);
        ComponentType tComposite = tf.createFcType(new InterfaceType[] { tf.createFcItfType("runner",
                Runner.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });

        // TODO: Create the Master Component type
        ComponentType tMaster = tf.createFcType(new InterfaceType[] {
                tf.createFcItfType("runner", Runner.class.getName(), TypeFactory.SERVER,
                        TypeFactory.MANDATORY, TypeFactory.SINGLE),
                tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.CLIENT, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE) });

        ComponentType tSlave = tf.createFcType(new InterfaceType[] { tf.createFcItfType("i1", Itf1.class
                .getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });

        Component slave = gf.newFcInstance(tSlave, new ControllerDescription("slave", Constants.PRIMITIVE),
                SlaveImpl.class.getName());

        // TODO: Create the Master Component
        Component master = gf.newFcInstance(tMaster,
                new ControllerDescription("master", Constants.PRIMITIVE), MasterImpl.class.getName());

        Component composite = gf.newFcInstance(tComposite, new ControllerDescription("composite",
            Constants.COMPOSITE), null);

        // TODO: Add slave and master components to the composite component
        ContentController cc = GCM.getContentController(composite);
        cc.addFcSubComponent(slave);
        cc.addFcSubComponent(master);

        // TODO: Do the bindings
        BindingController bcMaster = GCM.getBindingController(master);
        bcMaster.bindFc("i1", slave.getFcInterface("i1"));
        BindingController bcComposite = GCM.getBindingController(composite);
        bcComposite.bindFc("runner", master.getFcInterface("runner"));

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

In this tutorial, we will add a new server interface to the Slave component and bind it to a new client interface of the Master component. Our composite component will therefore look like as follows:

Figure 3.7. Composite component with the new interface

We introduce a second interface named Itf2 which source code is the following one:

package org.objectweb.proactive.examples.userguide.components.api.interfaces;

/**
 * @author The ProActive Team
 */
public interface Itf2 {
    void doNothing();
}

The aim of this tutorial is to make you modify the previous code in order to add this new interface using the API. All the necessary modification are made into the Main class.

Here is the main() method that you have to complete:

package org.objectweb.proactive.examples.userguide.components.api.interfaces;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {
        Component boot = Utils.getBootstrapComponent();
        GCMTypeFactory tf = GCM.getGCMTypeFactory(boot);
        GenericFactory gf = GCM.getGenericFactory(boot);
        ComponentType tComposite = tf.createFcType(new InterfaceType[] { tf.createFcItfType("runner",
                Runner.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });
        ComponentType tMaster = tf.createFcType(new InterfaceType[] {
                tf.createFcItfType("runner", Runner.class.getName(), TypeFactory.SERVER,
                        TypeFactory.MANDATORY, TypeFactory.SINGLE),
                tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.CLIENT, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                //TODO: Add the new client interface
                });
        ComponentType tSlave = tf.createFcType(new InterfaceType[] {
                tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                //TODO: Add the new server interface
                });
        Component slave = gf.newFcInstance(tSlave, new ControllerDescription("slave", Constants.PRIMITIVE),
                SlaveImpl.class.getName());
        Component master = gf.newFcInstance(tMaster,
                new ControllerDescription("master", Constants.PRIMITIVE), MasterImpl.class.getName());
        Component composite = gf.newFcInstance(tComposite, new ControllerDescription("composite",
            Constants.COMPOSITE), null);

        BindingController bcComposite = GCM.getBindingController(composite);
        bcComposite.bindFc("runner", master.getFcInterface("runner"));
        BindingController bcMaster = GCM.getBindingController(master);
        bcMaster.bindFc("i1", slave.getFcInterface("i1"));

        // TODO: Do the binding for the new interface

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

Thus, we propose you to:

To build your work, go to the compile directory into the tutorials directory and type:

build components.api.interfaces

Once you get a successful compilation, go to the scripts/Components directory located into the tutorials one and launch the api-interfaces.[sh|bat] script. You should then see a display looking like this:

rmi://kisscool.inria.fr:6618/Node275638725Slave: org.objectweb.proactive.examples.userguide.components.api.interfaces.SlaveImpl@3aa791
arg: hello - world

rmi://kisscool.inria.fr:6618/Node275638725Slave: org.objectweb.proactive.examples.userguide.components.api.interfaces.SlaveImpl@3aa791
I do nothing

Here is the solution:

package org.objectweb.proactive.examples.userguide.components.api.interfaces;

import java.util.ArrayList;
import java.util.List;

import org.etsi.uri.gcm.api.type.GCMTypeFactory;
import org.etsi.uri.gcm.util.GCM;
import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.control.BindingController;
import org.objectweb.fractal.api.factory.GenericFactory;
import org.objectweb.fractal.api.type.ComponentType;
import org.objectweb.fractal.api.type.InterfaceType;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.component.Constants;
import org.objectweb.proactive.core.component.ControllerDescription;
import org.objectweb.proactive.core.component.Utils;


/**
 * @author The ProActive Team
 */
public class Main {

    public static void main(String[] args) throws Exception {
        Component boot = Utils.getBootstrapComponent();
        GCMTypeFactory tf = GCM.getGCMTypeFactory(boot);
        GenericFactory gf = GCM.getGenericFactory(boot);
        ComponentType tComposite = tf.createFcType(new InterfaceType[] { tf.createFcItfType("runner",
                Runner.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY, TypeFactory.SINGLE) });
        ComponentType tMaster = tf.createFcType(new InterfaceType[] {
                tf.createFcItfType("runner", Runner.class.getName(), TypeFactory.SERVER,
                        TypeFactory.MANDATORY, TypeFactory.SINGLE),
                tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.CLIENT, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                //TODO: Add the new client interface
                ,
                tf.createFcItfType("i2", Itf2.class.getName(), TypeFactory.CLIENT, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                });
        ComponentType tSlave = tf.createFcType(new InterfaceType[] {
                tf.createFcItfType("i1", Itf1.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                //TODO: Add the new server interface
                ,
                tf.createFcItfType("i2", Itf2.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY,
                        TypeFactory.SINGLE)
                });
        Component slave = gf.newFcInstance(tSlave, new ControllerDescription("slave", Constants.PRIMITIVE),
                SlaveImpl.class.getName());
        Component master = gf.newFcInstance(tMaster,
                new ControllerDescription("master", Constants.PRIMITIVE), MasterImpl.class.getName());
        Component composite = gf.newFcInstance(tComposite, new ControllerDescription("composite",
            Constants.COMPOSITE), null);

        BindingController bcComposite = GCM.getBindingController(composite);
        bcComposite.bindFc("runner", master.getFcInterface("runner"));
        BindingController bcMaster = GCM.getBindingController(master);
        bcMaster.bindFc("i1", slave.getFcInterface("i1"));

        // TODO: Do the binding for the new interface
        bcMaster.bindFc("i2", slave.getFcInterface("i2"));

        GCM.getGCMLifeCycleController(composite).startFc();

        Runner runner = (Runner) composite.getFcInterface("runner");
        List<String> arg = new ArrayList<String>();
        arg.add("hello");
        arg.add("world");
        runner.run(arg);

        GCM.getGCMLifeCycleController(composite).stopFc();

        System.exit(0);
    }
}

A multicast interface transforms a single invocation into a list of invocations

A multicast interface is an abstraction for 1-to-n communications. When a single invocation is transformed into a set of invocations, these invocations are forwarded to a set of connected server interfaces. A multicast interface is unique and it exists at runtime (it is not lazily created). The semantics of the propagation of the invocation, of the distribution of the invocation parameters and of the result (if there is) are customizable (through annotations).

Invocations forwarded to the connected server interfaces occur in parallel, which is one of the main reasons for defining this kind of interface: it enables parallel invocations, with automatic distribution of invocation parameters .

Figure 4.2. Multicast interfaces for primitive and composite components

A multicast invocation leads to the invocation services offered by one or several connected server interfaces, with possibly distinct parameters for each server interface.

If some of the parameters of a given method of a multicast interface are lists of values, these values can be distributed in various ways through method invocations to the server interfaces connected to the multicast interface. The default behavior - namely broadcast - is to send the same parameters to each of the connected server interfaces. In the case where some parameters are lists of values, copies of the lists are sent to each receiver. However, similar to what SPMD programming offers, it may be adequate to strip some of the parameters so that the bound components will work on different data. In MPI for instance, this can be explicitly specified by stripping a data buffer and using the scatter primitive.

The following figure illustrates such distribution mechanisms: broadcast (a.) and scatter (b.)

Figure 4.3. Broadcast and scatter of invocation parameters

Invocations occur in parallel and the distribution of parameters is automatic.

@ParamDispatchMetadata(mode=ParamDispatchMode.CUSTOM, customMode=CustomParametersDispatch.class))

4.3.2.2.2. Configuration through annotations

	Note
	This implementation of collective interfaces extensively uses new features of the Java language introduced in Java 5, such as generics and annotations.

The distribution of parameters in this framework is specified in the definition of the multicast interface, using annotations.

Elements of a multicast interface which can be annotated are: interface, methods and parameters. The different distribution modes are explained in the next section. The examples in this section all specify broadcast as the distribution mode.

Interface annotations

A distribution mode declared at the level of the interface defines the distribution mode for all parameters of all methods of this interface, but may be overridden by a distribution mode declared at the level of a method or of a parameter.

The annotation for declaring distribution policies at level of an interface is @org.objectweb.proactive.core.component.type.annotations.multicast.ClassDispatchMetadata

and is used as follows:

import java.util.List;
import org.objectweb.proactive.examples.documentation.classes.T;

import org.objectweb.proactive.core.component.type.annotations.multicast.ClassDispatchMetadata;

import org.objectweb.proactive.core.component.type.annotations.multicast.ParamDispatchMetadata;
import org.objectweb.proactive.core.component.type.annotations.multicast.ParamDispatchMode;


@ClassDispatchMetadata(mode = @ParamDispatchMetadata(mode = ParamDispatchMode.BROADCAST))
interface MyMulticastItf {

    public void foo(List<T> parameters);



}

Method annotations

A distribution mode declared at the level of a method defines the distribution mode for all parameters of this method, but may be overridden at the level of each individual parameter.

The annotation for declaring distribution policies at level of a method is @org.objectweb.proactive.core.component.type.annotations.multicast.MethodDispatchMetadata

and is used as follows:

import java.util.List;
import org.objectweb.proactive.examples.documentation.classes.T;

import org.objectweb.proactive.core.component.type.annotations.multicast.MethodDispatchMetadata;

import org.objectweb.proactive.core.component.type.annotations.multicast.ParamDispatchMetadata;
import org.objectweb.proactive.core.component.type.annotations.multicast.ParamDispatchMode;


interface MyMulticastItf {

    @MethodDispatchMetadata(mode = @ParamDispatchMetadata(mode = ParamDispatchMode.BROADCAST))
    public void foo(List<T> parameters);



}

Moreover, an another feature, inherited from the group framework of ProActive, is available: the dynamic dispatch.

The org.objectweb.proactive.core.group.DispatchMode.DYNAMIC mode is applicable when there are more parameter partitions than binded server interfaces. A partitions is a set of arguments (list elements) that will be sent to server interfaces. For instance, instead of giving arguments one-by-one, you can use a 5-size partition which will send the first 5 arguments to the first server interface, the 5 next to the second interface and so on. Dynamic dispatch uses a knowledge-based policy, i.e. it collects information about request execution by server interfaces, and maintains a ranking among server interfaces so that partitions are dispatched to the "best" server interface. A buffer can be configured, in which case buffered partitions are statically allocated to server interfaces, according to the static dispatch policy.

Dynamic dispatch must be used like this:

@Dispatch(mode = DispatchMode.DYNAMIC, bufferSize = 1024)
public void foo(List<T> parameters);

Parameter annotations

The annotation for declaring distribution policies at level of a parameter is @org.objectweb.proactive.core.component.type.annotations.multicast.ParamDispatchMetadata

and is used as follows:

public void bar(@ParamDispatchMetadata(mode = ParamDispatchMode.BROADCAST)
List<T> parameters);

public List<T> foo();

public void bar();

import java.util.List;

import org.objectweb.proactive.core.component.type.annotations.multicast.Reduce;
import org.objectweb.proactive.core.component.type.annotations.multicast.ReduceMode;
import org.objectweb.proactive.examples.documentation.classes.T;


public interface MyMulticastItf2 {

    @Reduce(reductionMode = ReduceMode.SELECT_UNIQUE_VALUE)
    public T baz();
}

@Reduce(reductionMode = ReduceMode.CUSTOM, customReductionMode = GetLastReduction.class)
public T foobar();

package functionalTests.component.collectiveitf.reduction.composite;

import java.io.Serializable;
import java.util.List;

import org.objectweb.proactive.core.component.exceptions.ReductionException;
import org.objectweb.proactive.core.component.type.annotations.multicast.ReduceBehavior;


public class GetLastReduction implements ReduceBehavior, Serializable {
    /**
     * 
     */
    private static final long serialVersionUID = 51L;

    public Object reduce(List<?> values) throws ReductionException {
        System.out.println("--------------");
        System.out.println("Getting last out of " + values.size() + " elements");
        System.out.println("--------------");
        return values.get(values.size() - 1);
    }
}

Multicast interfaces manipulate lists of parameters (sayList<ParamType>) and expect lists of results (say List<ResultType>). With respect to a multicast interface, connected server interfaces, on the contrary, may work with lists of parameters ( List<ParamType>), but also with individual parameters ( ParamType) and return individual results (ResultType).

Therefore, the signatures of methods differ from a multicast client interface to its connected server interfaces . This is illustrated in the following figure: in picture a, the foo method of the multicast interface returns a list of elements of type T collected from the invocations to the server interfaces and in the picture b, the bar method distributes elements of type A to the connected server interfaces.

Figure 4.4. Comparison of signatures of methods between client multicast interfaces and server interfaces

For a given multicast interface, the type of server interfaces which may be connected to it can be inferred by applying the following rules:

For a given multicast interface,

The compatibility of interface signatures is verified automatically at binding time, resulting in a documented IllegalBindingException if signatures are incompatible.

A gathercast interface transforms a list of invocations into a single invocation

A gathercast interface is an abstraction for n-to-1 communications. It handles data aggregation for invocation parameters, as well as process coordination. It gathers incoming data, and can also coordinate incoming invocations before continuing the invocation flow, by defining synchronization barriers.

Gathering operations require knowledge of the participants on the collective communication (i.e. the clients of the gathercast interface). Therefore, the binding mechanism, when performing a binding to a gathercast interface, provides references on client interfaces bound to the gathercast interface. This is handled transparently by the framework. As a consequence, bindings to gathercast interfaces are bidirectional links.

Figure 4.5. Gathercast interfaces for primitive and composite components

Gathercast interfaces aggregate parameters from method invocations from client interfaces into lists of invocations parameters, and they redistribute results to each client interface.

4.3.3.2.1. Gathering of invocation parameters

Invocation parameters are simply gathered into lists of parameters. The indexes of the parameters in the list correspond to the index of the parameters in the list of connected client interfaces, managed internally by the gathercast interface.

Figure 4.6. Aggregation of parameters with a gathercast interface

Gathercast interfaces manipulate lists of parameters (say List<ParamType>) and return lists of results (say List<ResultType>). With respect to a gathercast interface, connected client interfaces work with parameters which can be contained in the lists of parameters of the methods of the bound gathercast interface (ParamType), and they return results which can be contained in the lists of results of the methods of the bound gathercast interface (ResultType).

Therefore, by analogy to the case of multicast interfaces, the signatures of methods differ from a gathercast server interface to its connected client interfaces . This is illustrated in the following figure: the foo methods of interfaces which are client of the gathercast interface exhibit a parameter of type V, the foo method of the gathercast interface exhibits a parameter of type List<V>. Similarly, the foo method of client interfaces return a parameter of type T whereas the foo method of the gathercast interface returns a parameter of type List<T>.

The compatibility of interface signatures is verified automatically at binding time, resulting in a documented IllegalBindingException if signatures are incompatible.

Figure 4.7. Comparison of method signatures for bindings to a gathercast interface

An invocation from a client interface to a gathercast interface is asynchronous, which matches with the usual conditions for asynchronous invocations in ProActive. However the gathercast interface only creates and executes a new invocation with gathered parameters when all connected client interfaces have performed an invocation on it.

It is possible to specify a timeout, which corresponds to the maximum amount of time between the moment when the first invocation of a client interface is processed by the gathercast interface, and those when the invocation of the last client interface is processed. Indeed, the gathercast interface will not forward a transformed invocation until all invocations of all client interfaces are processed by this gathercast interface.

Timeouts for gathercast invocations are specified by an annotation on the method subject to the timeout, the value of the timeout is specified in milliseconds:

@org.objectweb.proactive.core.component.type.annotations.gathercast.MethodSynchro(timeout=20)

If a timeout is reached before a gathercast interface could gather and process all incoming requests, a org.objectweb.proactive.core.component.exceptions.GathercastTimeoutException is returned to each client participating in the invocation. This exception is a runtime exception.

It is also possible for gathercast interface not to wait for all invocations from connected client interfaces to perform an invocation by specifying the waitForAll attribute. Therefore, the gathercast interface will create and execute a new invocation on the first invocation received from any of the connected client interfaces.

Thus, this specific feature can be used by the same annotation as for the timeout but with a different attribute:

@org.objectweb.proactive.core.component.type.annotations.gathercast.MethodSynchro(waitForAll=false)

Therefore, the waitForAll attribute accepts boolean values and has for default value "true" (same behavior as if the annotation is not specified).

Furthermore, it is forbidden to combine timeout and waitForAll set to false (an org.objectweb.fractal.api.factory.InstantiationException would be raised) because it would be incoherent.

To create a distributed component system, a deployment framework is available: the GCM Deployment.

Distribution is achieved in a transparent manner over the Java RMI protocol thanks to the use of a stub/proxy pattern. Components are manipulated indifferently of their location (local or on a remote JVM). A complete description of the GCM Deployment can be found at Chapter 14. ProActive Grid Component Model Deployment.

In brief, this framework:

The first step to distribute components is to initiate the deployment by loading the GCM Application Descriptor:

GCMApplication gcma = PAGCMDeployment.loadApplicationDescriptor(filePath);

Then, the deployment must be started (i.e. creation of the remote JVMs):

gcma.startDeployment();

The next step, distribute components, may be done through the ADL or the API.

Distribute components with ADL is quite simple:

Thus, the component will be instantiated in a node of the virtual node specified in the ADL component definition (if a virtual node of the same name has also been defined in the GCM Application Descriptor).

To distribute components with the API, the first thing to do is to get a node from a virtual node defined by the GCM Application Descriptor:

Map<String, GCMVirtualNode> vns = gcma.getVirtualNodes();
vns.get("VN1").waitReady();
Node node = vns.get("VN1").getANode();

Then, the component must be instanced thanks to one of the methods provided by org.objectweb.proactive.core.component.factory.PAGenericFactory, taking as parameter the node obtained previously:

Component component = gf.newFcInstance(componentType, controllerDescription, contentDescription, node);

It is possible to customize controllers, by specifying a control interface and an implementation.

Controllers are configured in a simple XML configuration file, which has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<componentConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../../../../../../Core/org/objectweb/proactive/core/component/config/component-config.xsd" 
    name="MyConfigurationName">
    <controllers>
        <controller>
            <interface>
                ControllerInterface
            </interface>
            <implementation>
                ControllerImplementation
            </implementation>
        </controller>
        <!-- other controllers -->
    </controllers>
</componentConfiguration>

Unless these controllers are also interceptors (see later on), the controllers do not have to be ordered.

A default configuration file is provided, it defines the default controllers available for every ProActive component (super, binding, content, naming, lifecycle, multicast, gathercast and monitor controllers, the priority controller is not available by default).

A custom configuration file can be specified (in this example with "thePathToMyConfigFile") for any component in the controller tag of the ADL definition:

<definition name="name">
    ...
    <controller desc="thePathToMyControllerConfigFile"/>
    </definition>
                

Or in the controller description parameter of the newFcInstance method from the Fractal/GCM API:

componentInstance = componentFactory.newFcInstance(myComponentType,
   new ControllerDescription("name",myHierarchicalType,thePathToMyControllerConfigFile),
   myContentDescription);
                

The controller interface is a standard interface which defines which methods are available.

When a new implementation is defined for a given controller interface, it has to conform to the following rules:

Controllers can also act as interceptors: they can intercept incoming invocations and outgoing invocations. For each invocation, pre and post processings are defined in the methods beforeInputMethodInvocation, afterInputMethodInvocation, beforeOutputMethodInvocation, and afterOutputMethodInvocation. These methods are defined in the interfaces InputInterceptor and OutputInterceptor and take a MethodCall object as an argument. MethodCall objects are reified representations of method invocations and they contain Method objects as well as the parameters of the invocation.

Interceptors are configured in the controllers XML configuration file, by simply adding input-interceptor="true" or/and output-interceptor="true" as attributes of the controller element in the definition of a controller (specify of course if the interceptor is an input or/and output interceptor). For example a controller that would be an input interceptor and an output interceptor would be defined as follows:

<controller input-interceptor="true" output-interceptor="true">
    <interface>
        InterceptorControllerInterface
    </interface>
    <implementation>
        ControllerImplementation
    </implementation>
</controller>

Interceptors can be composed in a sequentially manner.

For input interceptors, the beforeInputMethodInvocation method is called sequentially for each controller in the order they are defined in the controllers configuration file. The afterInputMethodInvocation method is called sequentially for each controller in the reverse order they are defined in the controller configuration file.

In the controller configuration file, if the list of input interceptors is in this order (the order in the controller configuration file is from top to bottom):

InputInterceptor1 InputInterceptor2

This means that an invocation on a server interface will follow this path:

—> caller —> InputInterceptor1.beforeInputMethodInvocation —> InputInterceptor2.beforeInputMethodInvocation —> callee.invocation —> InputInterceptor2.afterInputMethodInvocation —> InputInterceptor1.afterInputMethodInvocation

For output interceptors, the beforeOutputMethodInvocation method is called sequentially for each controller in the order they are defined in the controllers configuration file. The afterOutputMethodInvocationmethodM is called sequentially for each controller in the reverse order they are defined in the controller configuration file.

In the controller configuration file, if the list of input interceptors is in this order (the order in the controller configuration file is from top to bottom):

OutputInterceptor1 OutputInterceptor2

This means that an invocation on a server interface will follow this path:

—> currentComponent —> OutputInterceptor1.beforeOutputMethodInvocation —> OutputInterceptor2.beforeOutputMethodInvocation —> callee.invocation —> OutputInterceptor2.afterOutputMethodInvocation —> OutputInterceptor1.afterOutputMethodInvocation

An interceptor being a controller, it has to follow the rules explained above for the creation of a custom controller.

Input interceptors and output interceptors has to implement respectively the interfaces InputInterceptor and OutputInterceptor, which declare interception methods (pre/post interception) that have to be implemented.

Here is a simple example of an input interceptor:

package org.objectweb.proactive.examples.documentation.components;

import org.objectweb.fractal.api.Component;
import org.objectweb.fractal.api.factory.InstantiationException;
import org.objectweb.fractal.api.type.TypeFactory;
import org.objectweb.proactive.core.ProActiveRuntimeException;
import org.objectweb.proactive.core.component.control.AbstractPAController;
import org.objectweb.proactive.core.component.interception.InputInterceptor;
import org.objectweb.proactive.core.component.type.PAGCMTypeFactoryImpl;
import org.objectweb.proactive.core.mop.MethodCall;


public class MyInputInterceptor extends AbstractPAController implements InputInterceptor, ControllerItf {

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

    public MyInputInterceptor(Component owner) {
        super(owner);
    }

    protected void setControllerItfType() {
        try {
            setItfType(PAGCMTypeFactoryImpl.instance().createFcItfType("mycontroller",
                    ControllerItf.class.getName(), TypeFactory.SERVER, TypeFactory.MANDATORY,
                    TypeFactory.SINGLE));
        } catch (InstantiationException e) {
            throw new ProActiveRuntimeException("cannot create controller" + this.getClass().getName());
        }
    }

    // foo is defined in the MyController interface
    public void foo() {
        // foo implementation
    }

    public void afterInputMethodInvocation(MethodCall methodCall) {
        System.out.println("post processing an intercepted an incoming functional invocation");
        // interception code
    }

    public void beforeInputMethodInvocation(MethodCall methodCall) {
        System.out.println("pre processing an intercepted an incoming functional invocation");
        // interception code
    }
}

The configuration file would state:

<controller input-interceptor="true">
    <interface>
        org.objectweb.proactive.examples.documentation.components.ControllerItf
    </interface>
    <implementation>
        org.objectweb.proactive.examples.documentation.components.MyInputInterceptor
    </implementation>
</controller>

This feature allows to expose interfaces of a component as a web service and thus, to call them 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 component interface 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.8. Steps taken when an active object is called via SOAP

If you want to expose your components 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.

There are two ways of exposing and unexposing a component as a web service: the first one is the same as we can do with active objects and the second one uses the PAWebServicesController, which is a component controller dedicated to the web services exposition. This section deals with the first method.

The steps for exporting and using a component as a web service are the following:

As said in the previous section, it is possible to expose web services in two differents manners. This section explains how to proceed with the dedicated web services controller.

When you call the exposition of your component, 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 component 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 component 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 component using this implementation of InitActive.

// Get the Axis2 InitActive in charge of deploying the Axis2 Servlet
InitActive axis2InitActive = WebServicesInitActiveFactory.getInitActive("axis2");
Component myComponent = ((PAGenericFactory) genericFactory).newFcInstance(componentType,
        new ControllerDescription("myControllerName", Constants.PRIMITIVE), new ContentDescription(
            HelloWorldComponent.class.getName(), null, axis2InitActive, null), myNode);

If you have chosen to use the PAWebServicesController controller, you do not need to modified your component instantiation but instead, before the first exposition, you just have to call the following method on the controller:

// Deploy the web service servlet on the jetty server corresponding to the node where the component has been
// deployed.
wsc.initServlet();

Now, let us assume that your component 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. If you are using the web services controller, it is really straight forward. You just have to put a node as an argument of the previous method:

// To expose a component on a remote host where this servlet has not been deployed yet, add
// the node started on this host as argument. You can put as many nodes as you want.
wsc.initServlet(myNode);

If you are not using the controller, you can use the following line:

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

Then, you can expose your component as a web service as in Section 4.5.2.4, “Steps to expose/unexpose a component as a web services using the WebServices interface”.

Once the component interface exposed, 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 component interface. 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 'componentTest_computeItf', you can get the WSDL document at http://[host]:[port]/proactive/services/componentTest_computeItf?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 component 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 criterion due to the serialization and Axis2/CXF 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 ignore the exception for oneWayCall. This is not the best solution since other exceptions will be ignored 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.

Let's start with a simple example, an Helloworld component with two interfaces exposed as a web service:

First, below are the two server interfaces of the component:

public interface HelloWorldItf {

    public String helloWorld(String arg0);

    public String sayHello();

    public String sayText();

    public void setText(String arg0);

}

public interface GoodByeWorldItf {

    public String goodByeWorld(String arg0);

    public String sayGoodBye();

    public void setText(String arg0);

    public String sayText();
}

The implementation class of the component is the following one:

public class HelloWorldComponent implements HelloWorldItf, GoodByeWorldItf, Serializable {

    /**
     * 
     */
    private static final long serialVersionUID = 51L;
    private String text;

    public String sayText() {
        return text;
    }

    public void setText(String text) {
        this.text = text;
    }

    public HelloWorldComponent() {
    }

    public String helloWorld(String arg0) {
        return "Hello " + arg0 + " !";
    }

    public String goodByeWorld(String arg0) {
        return "Good Bye " + arg0 + " !";
    }

    public String sayHello() {
        return "Hello ProActive Team !";
    }

    public String sayGoodBye() {
        return "Good bye ProActive Team !";
    }

}

The following piece of code creates the component and exposes its interfaces as a web services.

Component componentBoot = Utils.getBootstrapComponent();

GCMTypeFactory typeFactory = GCM.getGCMTypeFactory(componentBoot);
GenericFactory genericFactory = GCM.getGenericFactory(componentBoot);

// type of server component
ComponentType componentType = typeFactory.createFcType(new InterfaceType[] {
        typeFactory
                .createFcItfType("hello-world", HelloWorldItf.class.getName(), false, false, false),
        typeFactory.createFcItfType("goodbye-world", GoodByeWorldItf.class.getName(), false, false,
                false) });

// create server component
Component helloWorld = genericFactory.newFcInstance(componentType, new ControllerDescription(
    "server", Constants.PRIMITIVE), new ContentDescription(HelloWorldComponent.class.getName()));
//start the component
GCM.getGCMLifeCycleController(helloWorld).startFc();

// If you want the default WebServicesFactory, you can use
// WebServicesFactory.getDefaultWebServicesFactory()
WebServicesFactory webServicesFactory = AbstractWebServicesFactory.getWebServicesFactory("cxf");

// If you want to use the local Jetty server, you can use
// AbstractWebServicesFactory.getLocalUrl() to get its url with
// its port number (which is random except if you have set the
// proactive.http.port variable)
WebServices webservices = webServicesFactory.getWebServices("http://localhost:8080/");

// If you want to expose only the goodbye-world interface for example,
// use the following line instead:
// webservices.exposeComponentAsWebService(helloWorld, "MyHelloWorldComponentService", new String[] { "goodbye-world" });
webservices.exposeComponentAsWebService(helloWorld, "MyHelloWorldComponentService");

If you want to use the web service controller, you should write the following line:

Component componentBoot = Utils.getBootstrapComponent();

GCMTypeFactory typeFactory = GCM.getGCMTypeFactory(componentBoot);
GenericFactory genericFactory = GCM.getGenericFactory(componentBoot);

// type of server component
ComponentType componentType = typeFactory.createFcType(new InterfaceType[] {
        typeFactory
                .createFcItfType("hello-world", HelloWorldItf.class.getName(), false, false, false),
        typeFactory.createFcItfType("goodbye-world", GoodByeWorldItf.class.getName(), false, false,
                false) });

// Get the web services controller corresponding to the chosen framework (here cxf)
String controllerPath = AbstractPAWebServicesControllerImpl.getControllerFileUrl("cxf").getPath();

// Create the component using this controller
ControllerDescription controllerDesc = new ControllerDescription("server", Constants.PRIMITIVE,
    controllerPath);

// Create server component
Component helloWorldComponent = genericFactory.newFcInstance(componentType, controllerDesc,
        new ContentDescription(HelloWorldComponent.class.getName()));

// Start the component
GCM.getGCMLifeCycleController(helloWorldComponent).startFc();

// Get the web services controller
PAWebServicesController wsController = org.objectweb.proactive.extensions.webservices.component.Utils
        .getPAWebServicesController(helloWorldComponent);

// Set the Url where the component has to be exposed
wsController.setUrl("http://localhost:8080/");

// Expose the component as a web service
wsController.exposeComponentAsWebService("MyHelloWorldComponentService");

All the interfaces (hello-world and goodbye-world) of the component helloWorld have been deployed as web services on the web server located at http://localhost:8080/proactive/services/ and its service names are "MyHelloWorldComponentService_hello-world" and "MyHelloWorldComponentService_goodbye-world". You can see the wsdl files through http://localhost:8080/proactive/services/MyHelloWorldComponentService_hello-world?wsdl and http://localhost:8080/proactive/services/MyHelloWorldComponentService_goddbye-world?wsdl and you can call the sayHello method of the hello-world interface with your browser through http://localhost:8080/proactive/services/MyHelloWorldComponentService_hello-world/sayHello.

If you have exposed a method which requires arguments, you can call it using the same link as previously but adding ?[arg0]=[value]&[arg1]=[value]... where [argn] is the name of the n-th argument as written in the WSDL file.

You can also call a webservice using the ProActive client which uses, depending on the chosen framework, either an Axis2 or a CXF client. Here is an example:

// Instead of using "cxf", you can also use webServicesFactory.getFrameWorkId()
// in order to be sure to get the same framework as the service
// has used to be exposed. However, you can call a cxf service
// using an axis2 client but there exists some incompatibility
// between these two frameworks.
// If you want the default ClientFactory, you can use
// ClientFactory.getDefaultClientFactory()
ClientFactory cFactory = AbstractClientFactory.getClientFactory("cxf");

// Instead of using "http://localhost:8080/", you can use ws.getUrl() to
// ensure to get to good service address.
Client serviceClient = cFactory.getClient("http://localhost:8080/",
        "MyHelloWorldComponentService_goodbye-world", GoodByeWorldItf.class);

// Call which returns a result
Object[] result = serviceClient.call("goodByeWorld", new Object[] { "ProActive Team" }, String.class);
System.out.println((String) result[0]);

// Call which does not return a result
serviceClient.oneWayCall("setText", new Object[] { "Hi ProActive Team!" });

// Call with no argument
result = serviceClient.call("sayText", null, String.class);

System.out.println((String) result[0]);

Here we present a simple example that shows the advantages of componentizing controllers of components. In our example, we are considering a naive solution for securing communications of a composite component. As described in Figure 4.9, “Example: architecture of a naive solution for secure communications”, secure communications are implemented by three components inside the membrane: Interceptor, Decrypt, and Alert. The scenario of the example is the following: the composite component receives encrypted messages on its server functional interface. The goal is to decrypt those messages. First, the incoming messages are intercepted by the Interceptor component. It forwards all the intercepted communications to Decrypt, which can be an off-the-shelf component (written by cryptography specialists) implementing a specific decryption algorithm. The Decrypt component receives a key for decryption through the non-functional server interface of the composite (interface number 1 on the figure). If it successfully decrypts the message, the Decrypt component sends it to the internal functional components, using the functional internal client interface (2). If a problem during decryption occurs, the Decrypt component sends a message to the Alert component. The Alert component is in charge of deciding on how to react when a decryption fails. For example, it can contact the sender (using the non-functional client interface – 3) and ask it to send the message again. Another security policy would be to contacta “trust and reputation” authority to signal a suspicious behaviour of the sender. The Alert component is implemented by a developer who knows the security policy of the system. In this example, we have three well-identified components, with clear functionalities and connected through well-defined interfaces. Thus, we can dynamically replace the Decrypt component by another one, implementing a different decryption algorithm. Also, for changing the security policy of the system, we can dynamically replace the Alert component and change its connexions. Compared to a classical implementation of secure communications (for example with objects), using components brings to the membrane a better structure and reconfiguration possibilities. To summarize, componentizing the membrane in this example provides dynamic adaptability and reconfiguration; but also re-usability and composition from off-the-shelf components.

Figure 4.9. Example: architecture of a naive solution for secure communications

Figure 4.10. Structure for the membrane of Fractal/GCM components

Figure 4.10, “Structure for the membrane of Fractal/GCM components” shows the structure we suggest for the component membrane. The membrane (in gray) consists of one object controller and two component controllers, the component controllers are connected together and with the outside of the membrane by different bindings. For the moment, we do not specify whether components are localized with the membrane, or distributed.

Before defining an API for managing components inside the membrane, the definition of the membrane given by the GCM specification needs some refinements. Those refinements, discussed in this section, provide more details about the structure a membrane can adopt. Figure 4.10, “Structure for the membrane of Fractal/GCM components” represents the structure of a membrane and gives a summary of the different kinds of interface roles and bindings that a component can provide. As stated in the GCM specification, NF interfaces are not only those specified in the Fractal specification, which are only external server ones. Indeed, in order to be able to compose NF aspects, the GCM requires the NF interfaces to share the same specification as the functional ones: role, cardinality, and contingency. For example, in GCM, client NF interfaces allow the composition of NF aspects and reconfigurations at the NF level. Our model is also flexible, as all server NF interfaces can be implemented by both objects or components controllers.

All the interfaces showed in Figure 4.10, “Structure for the membrane of Fractal/GCM components” give the membrane a better structure and enforce decoupling between the membrane and its externals. For example, to connect nfc with fns, our model adds an additional stage: we have first to perform binding b3, and then binding b9. This avoids nfc to be strongly coupled with fns: to connect nfc to another fns, only binding b9 has to be changed. In Figure 4.10, “Structure for the membrane of Fractal/GCM components”, some of the links are represented with dashed arrows. Those links are not real bindings but “alias” bindings (e.g. b3); the source interface is the alias and it is “merged” with the destination interface. These bindings are similar to the export/import bindings existing in Fractal (b6, b10) except that no interception of the communications on these bindings is allowed.

Communications between components in a hierarchical model may involve the crossing of several membranes, and therefore paying the cost of several indirections. If the invocations are not intercepted in the membranes, then it is possible to optimize the communication path by shortcutting: communicating directly from a caller component to a callee component by avoiding indirections in the membranes.

In the Julia implementation, a shortcut mechanism is provided for components in the same JVM, and the implementation of this mechanism relies on code generation techniques.

We provide a shortcut mechanism for distributed components, and the implementation of this mechanism relies on a "tensioning" technique: the first invocation determines the shortcut path, then the following invocations will use this shortcut path.

For example, in the following figure, a simple component system, which consists of a composite containing two wrapped primitive components, is represented with different distributions of the components. In a, all components are located in the same JVM, therefore all communications are local communications. If the wrapping composites are distributed on different remote JVMs, all communications are remote because they have to cross composite enclosing components. The short cut optimization is a simple bypassing of the wrapper components, which results in 2 local communications for the sole functional interface.

Figure 4.13. Using shortcuts for minimizing remote communications

Shortcuts are available when composite components are synchronous components (this does not break the ProActive model, as composite components are structural components). Components can be specified as synchronous in the ControllerDescription object that is passed to the component factory:

ControllerDescription controllerDescription = new ControllerDescription("name", Constants.COMPOSITE, Constants.SYNCHRONOUS);

When the system property proactive.components.use_shortcuts is set to true, the component system will automatically establish short cuts between components whenever possible.