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.