User guide

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 and of the distribution of the invocation parameters are customizable (through annotations), and the result of an invocation on a multicast interface - if there is a result - is always a list of results.

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 26.1.  Multicast interfaces for primitive and composite component

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 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 26.2.  Broadcast and scatter of invocation parameters

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

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

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

									public void foo(List<T> parameters);
								}
							

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

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

							public List<Something> foo();

							public void bar();
						

							@Reduce(reductionMode =
							ReduceMode.SELECT_UNIQUE_VALUE)
						

							@Reduce(reductionMode = ReduceMode.CUSTOM,
							customReductionMode = MyReduction.class)
						

Multicast interfaces manipulate lists of parameters (say, List<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 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 b. the bar method distributes elements of type A to the connected server interfaces.

Figure 26.3.  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 infered 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 of 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 26.4.  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.

26.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 the index of the parameters in the list of connected client interfaces, managed internally by the gathercast interface.

Figure 26.5.  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 interface 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 method 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 , and 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 26.6.  Comparison of signature of methods for bindings to a gathercast interface

An invocation from a client interface to a gathercast interface is asynchronous, provided it matches 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 the first invocation of a client interface is processed by the gathercast interface, and the moment 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 is raised) because il would be incoherent.

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:

          <componentConfiguration>
            <controllers>
              <controller>
                <interface>
                  ControllerInterface
                </interface>
                <implementation>
                  ControllerImplementation
                </implementation>
              </controller>
              ...
        

Unless they some 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 and component parameters controllers).

A custom configuration file can be specified (in this example with "thePathToMyConfigFile") for any component in the controller description parameter of the newFcInstance method from the Fractal 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:

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

					protected void setControllerItfType() {
						try {
							setItfType(ProActiveTypeFactory.instance().createFcItfType(
								"Name of the controller", TypeFactory.SINGLE));
						}
						catch (InstantiationException e) {
							throw new ProActiveRuntimeException("cannot create controller type: "
								+ this.getClass().getName());
						}
					}
				

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, along with 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 (provided of course the specified 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:

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

Interceptors can be composed in a basic manner: sequentially.

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 controllers configuration file.

If in the controller configuration file, 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 afterOutputMethodInvocationmethod is called sequentially for each controller in the reverse order they are defined in the

controllers configuration file.

If in the controller configuration file, 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 must follow the rules explained above for the creation of a custom controller.

Input interceptors and output interceptors must 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:

					public class MyInputInterceptor extends AbstractProActiveController
															implements InputInterceptor, MyController {
						public MyInputInterceptor(Component owner) {
							super(owner);
						}

						protected void setControllerItfType() {
							try {
								setItfType(ProActiveTypeFactory.instance().createFcItfType("mycontroller",
																				MyController.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:

          <componentConfiguration>
            <controllers>
              ...
              <controller input-interceptor="true">
                <interface>
                  MyController
                </interface>
                <implementation>
                  MyInputInterceptor
                </implementation>
              </controller>
              ...
        

Here we present a simple example that shows the advantages of componen tizing controllers of GCM components. In our example, we are considering a naive solution for securing communications of a composite component. As described in Figure Figure 26.7, “ 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 charge to decide 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 contact a “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 26.7.  Example: architecture of a naive solution for secure communications

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

Figure Figure 26.8, “ 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 Figure 26.8, “ 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 a GCM 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 for 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 Figure 26.8, “ 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 Figure 26.8, “ 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.