The first parameter of newActive is a string containing the fully-qualified name of the class we want to make active. Parameters to the constructor have to be passed as an array of Object. Then, according to the type of the elements of this array, the ProActive runtime determines which constructor of class A to call. Nevertheless, there is still room for some ambiguity in resolving the constructor because:

    public A (int i) {
        //
    }
    public A (Integer i) {
        //
    }
    public A (int i, String s) {
        //
    }
    public A (int i, Vector v) {
        //
    }

It is possible to pass a third parameter to the call to newActive in order to create the new active object on a specific JVM, possibly remote. The JVM is identified using a Node object that offers the minimum services ProActive needs on a given JVM to communicate with this JVM. If that parameter is not given, the active object is created in the current JVM and is attached to a default Node.

A node is identified by a node URL which is formed using the protocol, the hostname hosting the JVM where is the node located and the name of the node. The NodeFactory allows to create or lookup nodes. The method newActive can take in parameter a nodeURL as a String or a Node object that points to an existing node. Here an example:

      a = (A) ProActive.newActive("example.A", params, "rmi://pluto.inria.fr/aNode");
  or
      Node node = NodeFactory.getNode("rmi://pluto.inria.fr/aNode");
      a = (A) ProActive.newActive("example.A", params, node);

The algorithms that decide for each phase what to do are the following (activity is the eventual object passed as a parameter to newActive or turnActive):

InitActive

if activity is non null and implements InitActive
  we invoke the method initActivity defined in the object activity
else if the class of the reified object implements InitActive
  we invoke the method initActivity of the reified object
else
  we don't do any initialization

RunActive

if activity is non null and implements RunActive
  we invoke the method runActivity defined in the object activity
else if the class of the reified object implements RunActive
  we invoke the method runActivity of the reified object
else
  we run the standard FIFO activity

EndActive

if activity is non null and implements EndActive
  we invoke the method endActivity defined in the object activity
else if the class of the reified object implements EndActive
  we invoke the method endActivity of the reified object
else
  we don't do any cleanup

Implementing the interfaces directly in the class used to create the active object is the easiest solution when you control the class that you make active. Depending on which phase in the life of the active object you want to customize, you implement the corresponding interface (one or more) amongst InitActive, RunActive and EndActive. Here is an example that has a custom initialization and activity.

  import org.objectweb.proactive.*;
  public class A implements InitActive, RunActive {
        private String myName;
         public String getName() {
         return myName;
        }
        // -- implements InitActive
        public void initActivity(Body body) {
        myName = body.getName();
        }
        // -- implements RunActive for serving request in a LIFO fashion
         public void runActivity(Body body) {
        Service service = new Service(Body);
        while (body.isActive()) {
         service.blockingServeYoungest();
        }
        }
        public static void main(String[] args) throws Exception {
        A a = (A) ProActive.newActive("A",null);
        System.out.println("Name = "+a.getName());
        }
  }

import org.objectweb.proactive.*;
public class Simulation implements RunActive {
      private boolean stoppedSimulation=false;
        private boolean startedSimulation=false
        private boolean suspendedSimulation=false;
        private boolean notStarted = true;
        public void startSimulation(){
        //Simulation starts
        notStarted = false;
        startedSimulation=true;
        }
        public void restartSimulation(){
        //Simulation is restarted
        startedSimulation=true;
        suspendedSimulation=false;
        }
        public void suspendSimulation(){
        //Simulation is suspended
        suspendedSimulation=true;
        startedSimulation = false;
        }
        public void stoppedSimulation(){
        //Simulation is stopped
        stoppedSimulation=true;
        }
        public void runActivity(Body body) {
         Service service = new Service(Body);
        while (body.isActive()) {
        //If the simulation is not yet started wait until startSimulation method
        if(notStarted) service.blockingServeOldest(startSimulation());
       // If the simulation is started serve request with FIFO
        if(startedSimulation) service.blockingServeOldest();
        // If simulation is suspended wait until restartSimulation method
        if(suspendedSimulation) service.blockingServeOldest(restartSimulation());
        // If simulation is stopped, exit
        if(stoppedSimulation) exit();
        }
}

public class BusyButReactive implements RunActive {
public void  runActivity(Body body) {
Service service = new Service(body);
while ( ! hasToTerminate ) {
        ...    // Do some activity on its own
        ...
        ...    // Non blocking service
        ...
        service.serveOldest("changeParameters", "terminate");   ... 
      }
    }
public void changeParameters () {...   // change computation parameters}
public void terminate (){ hasToTerminate=true;}
}

It also allows one to specify explicit termination of AOs (there is currently no Distributed Garbage Collector). Of course, the reactivity is up to the length of going around the loop.

Passing an object implementing the interfaces when creating the active object is the solution to use when you do not control the class that you make active or when you want to write generic activities policy and reused them with several active objects. Depending on which phase in the life of the active object you want to customize, you implement the corresponding interface (one or more) amongst InitActive, RunActive and EndActive. Following is an example that has a custom activity.

Comparing to the solution above where interfaces are directly implemented in the reified class, there is one restriction here: you cannot access the internal state of the reified object. Using an external object should therefore be used when the implementation of the activity is generic enough not to have to access the member variables of the reified object.

  import org.objectweb.proactive.*;
  public class LIFOActivity implements RunActive {
    // -- implements RunActive for serving request in a LIFO fashion
    public void runActivity(Body body) {
      Service service = new Service(Body);
      while (body.isActive()) {
        service.blockingServeYoungest();
      }
    }
  }
  import org.objectweb.proactive.*;
  public class A implements InitActive {
    private String myName;
    public String getName() {
      return myName;
    }
    // -- implements InitActive
    public void initActivity(Body body) {
      myName = body.getName();
    }
    public static void main(String[] args) throws Exception {
      // newActive(classname, constructor parameter (null = none), 
      //           node (null = local), active, MetaObjectFactory (null = default)
      A a = (A) ProActive.newActive("A", null, null, new LIFOActivity(), null);
      System.out.println("Name = "+a.getName());
    }
  }

There are many cases where you may want to customize the body used when creating an active object. For instance, one may want to add some debug messages or some timing behavior when sending or receiving requests. The body is a non changeable object that delegates most of its tasks to helper objects called MetaObjects. Standard MetaObjects are already used by default in ProActive but one can easily replace any of those MetaObjects by a custom one.

We have defined the MetaObjectFactory interface (see code in core/body/MetaObjectFactory.java) able to create factories for each of those MetaObjects. This interface is implemented by ProActiveMetaObjectFactory (see code in core/body/ProActiveMetaObjectFactory.java) which provides all the default factories used in ProActive.

When creating an active object, as we saw above, it is possible to specify which MetaObjectFactory to use for that particular instance of active object being created. The class ProActive (see code in ProActive.java) provides extra newActive and turnActive methods for that:

ProActive.newActive(
  java.lang.String, 
  java.lang.Object[],
  org.objectweb.proactive.core.node.Node, 
  org.objectweb.proactive.Active,  
	org.objectweb.proactive.core.body.MetaObjectFactory)

ProActive.turnActive(
  java.lang.Object,
  org.objectweb.proactive.core.node.Node,
  org.objectweb.proactive.Active,
	org.objectweb.proactive.core.body.MetaObjectFactory)

First you have to write a new MetaObject factory that inherits from ProActiveMetaObjectFactory (see code in core/body/ProActiveMetaObjectFactory.java) or directly implements the MetaObjectFactory interface (see code in core/body/MetaObjectFactory.java), in order to redefine everything. Inheriting from ProActiveMetaObjectFactory is a great time saver as you only redefine what you really need to. Here is an example:

public class MyMetaObjectFactory extends ProActiveMetaObjectFactory {
  private static final MetaObjectFactory instance = new MyMetaObjectFactory();
  protected MyMetaObjectFactory() {
    super();
  }
  public static MetaObjectFactory newInstance() {
    return instance;
  }
  //
  // -- PROTECTED METHODS -----------------------------------------------
  //
  protected RequestFactory newRequestFactorySingleton() {
    return new MyRequestFactory();
  }
  //
  // -- INNER CLASSES -----------------------------------------------
  //
  protected class MyRequestFactory implements RequestFactory, java.io.Serializable {
    public Request newRequest(MethodCall methodCall, 
                      UniversalBody sourceBody, boolean isOneWay, long sequenceID) {
      return new MyRequest(methodCall, sourceBody, isOneWay, sequenceID, server);
    }
  } // end inner class MyRequestFactory
}

The factory above simply redefines the RequestFactory in order to make the body use a new type of request. The method protected RequestFactory newRequestFactorySingleton() is one convenience method that ProActiveMetaObjectFactory (see code in core/body/ProActiveMetaObjectFactory.java) provides to simplify the creation of factories as singleton. More explanations can be found in the javadoc of that class . The use of that factory is fairly simple. All you have to do is to pass an instance of the factory when creating a new active object. If we take the same example as before we have:

  Object[] params = new Object[] {new Integer (26), "astring"};
  try {
    A a = (A) ProActive.newActive("example.AA", params, null, null, 
                                    MyMetaObjectFactory.newInstance());
  } catch (Exception e) {
    e.printStackTrace() ;
  }

In the case of a turnActive we would have:

  A a = new A(26, "astring");
  a = (A) ProActive.turnActive(a, null, null, MyMetaObjectFactory.newInstance());

The role of the class Stub_B is to reify all method calls that can be performed through a reference of type B, and only these as calling a method declared in a subclass of B through downcasting would result in a runtime error). Reifying a call simply means constructing an object (in our case, all reified calls are instance of class MethodCall) that represents the call, so that it can be manipulated as any other object. This reified call is then processed by the other components of the active object in order to achieve the behavior we expect from an active object.

The idea of using a standard object for representing elements of the language that are not normally objects (such as method calls, constructor calls, references, types,...) is what metaobject programming is all about. The metaobject protocol (MOP) ProActive is built on is described in Chapter 52, MOP: Metaobject Protocol but it is not a prerequisite for understanding and using ProActive.

As one of our objectives is to provide transparent active objects, references to active objects of class B need to be of the same type as references to passive instances of B (this feature is called polymorphism between passive and active instances of the same class). This is why, by construction, Stub_B is a subclass of class B, therefore allowing instances of class Stub_B to be assigned to variables of type B.

Class Stub_B redefines each of the methods inherited from its superclasses. The code of each method of class Stub_B actually builds an instance of class MethodCall in order to represent the call to this method. This object is then passed to the BodyProxy, which returns an object that is returned as the result of the method call. From the caller's point of view, everything looks like if the call had been performed on an instance of B.

Now that we know how stubs work, we can understand some of the limitations of ProActive:

The role of the proxy is to handle asynchronism in calls to active object. More specifically, it creates future objects if possible and needed, forwards calls to bodies and returns future objects to the stubs. As this class operates on MethodCall objects, it is absolutely generic and does not depend at all on the type of the stub that feeds calls in through its reify method.

The body is responsible for storing calls (actually, Request objects) in a queue of pending requests and processing these request according to a given synchronization policy, whose default behavior is FIFO. The Body has its own thread, which alternatively chooses a request in the queue of pending ones and executes the associated call.

This is a standard instance of class B. It may contain some synchronized information in its live method, if any. As the body executes calls one by one, there cannot be any concurrent execution of two portions of code of this object by two different threads. This enables the use of pre- and post-conditions and class invariants. As a consequence, the use of the keyword synchronized in class B should not be necessary. Any synchronization scheme that can be expressed through monitors and synchronized statements can be expressed using ProActive's high-level synchronization mechanism in a much more natural and user-friendly way.

Whenever possible a method call on an active object is reified as an asynchronous request. If not possible the call is synchronous and blocks until the reply is received. In case the request is asynchronous, it immediately returns a future object.

This object acts as a placeholder for the result of the not-yet-performed method invocation. As a consequence, the calling thread can go on with executing its code, as long as it doesn't need to invoke methods on the returned object, in which case the calling thread is automatically blocked if the result of the method invocation is not yet available. Below are shown the different cases that can lead to an asynchronous call.

As we can see, the creation of a future depends not only on the caller type, but also on the return object type. Creating a future is only possible if the object is reifiable. Note although having a quite similar structure as an active object, a future object is not active. It only has a Stub and a Proxy as shown in figure below:

Figure 13.2. A future object

During its lifetime, an active object can create many future objects. There are all automatically kept in a FuturePool.

Each time a future is created, it is inserted in the future pool of the corresponding active object. When the result becomes available, the future object is removed from the pool. Although most of the methods of the FuturePool are for internal use only and are directly called by the proactive library we provide a method to wait until a result becomes available. Instead of blocking until a specific future is available, the call to waitForReply() blocks until any of the current futures become available. An application can be found in the FutureList class.

There are few things to remember with asynchronous method calls and futures, in order to avoid annoying debugging sessions:

An Automatic Continuation is due to the propagation of a future outside the activity that has sent the corresponding request.

Automatic Continuations allow to pass in parameter or return as a result future objects(or objects containing a future) without blocking to wait the result object of the future. When the result is available on the object that originated the creation of the future, this object must update the result in all objects to which it passed the future.

The following piece of code shows both cases: passing a future as parameter or as a result.

class C {
....
        public static void main(String[] args){
        ......
        A a = newActive(A);
        A b = newActive(B);
        Result r1 = a.foo();   //r1 is a future
        Result r2 = b.bar(r1); //r1 is passed as parameter
        Result r3 = b.bar2();  // see **
        ........
        }       //end of main
...
}       //end of class C

where

class A {
  ...
        public Result foo(){
        ...
        }
  ...
} //end of class A

and

class B {
...
         public Result bar (Result r) {
        ...
         }

        public Result bar2 () {
         A a = newActive(A);
        return a.foo();     //  ** future is sent as a result
         }
} //end of class B

We will illustrate here how a future is first created, then passed as parameter to a method later on.

Let us say that some piece of code in main method of an object C calls method foo() on an instance of class A.

This call is asynhronous and returns a future object Future_r1 of class Result.

Then method bar() is called on an instance of class B passing future Future_r1 as a parameter to the method

This call is asynhronous and returns a future object Future_r2 of class Result. B needs the value of Future_r1 which is not yet available in order to return the result of method bar(), so it gets the future too.

The value of the result for the call to method foo is now available, so A updates the value of Future_r1

C updates the value of Future_r1 for B

B returns the value for the call to method bar() and updates the value of Future_r2 for C

Only two classes are needed: one for the server object Hello and one for the client that accesses it HelloClient.

public class Hello {
  private String name;
  private String hi = "Hello world";
  private java.text.DateFormat dateFormat = new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss");
  public Hello() {
  }
  public Hello(String name) {
    this.name = name;
  }
  public String sayHello() {
    return hi + " at " + dateFormat.format(new java.util.Date())+
        " from node: " + org.objectweb.proactive.ProActive.getBodyOnThis().getNodeURL();
  }
  public static void main(String[] args) {
    // Registers it with an URL
    try {
      // Creates an active instance of class HelloServer on the local node
      Hello hello = (Hello)org.objectweb.proactive.ProActive.newActive(Hello.class.getName(), 
                             new Object[]{"remote"});
      java.net.InetAddress localhost = java.net.InetAddress.getLocalHost();
      org.objectweb.proactive.ProActive.register(hello, "//" + localhost.getHostName() + "/Hello");
    } catch (Exception e) {
      System.err.println("Error: " + e.getMessage());
      e.printStackTrace();
    }
  }
}

public class HelloClient {
  public static void main(String[] args) {
    Hello myServer;
    String message;
    try {
      // checks for the server's URL
      if (args.length == 0) {
        // There is no url to the server, so create an active server within this VM
        myServer = (Hello)org.objectweb.proactive.ProActive.newActive(Hello.class.getName(), 
                          new Object[]{"local"});
      } else {
        // Lookups the server object
        System.out.println("Using server located on " + args[0]);
        myServer = (Hello)org.objectweb.proactive.ProActive.lookupActive(Hello.class.getName(), 
                          args[0]);
      }
      // Invokes a remote method on this object to get the message
      message = myServer.sayHello();
      // Prints out the message
      System.out.println("The message is: " + message);
    } catch (Exception e) {
      System.err.println("Could not reach/create server object");
      e.printStackTrace();
      System.exit(1);
    }
  }
}

In order to run both the client and server in the same VM, the client creates an active object in the same VM if it doesn't find the server's URL. The code snippet which instantiates the Server in the same VM is the following:

if (args.length == 0) {
  // There is no url to the server, so create an active server within this VM
  myServer = (Hello)org.objectweb.proactive.ProActive.newActive(
        Hello.class.getName(), new Object[]{"local"});
}

To launch the Client and the Server, just type:

linux> java -Djava.security.policy=scripts/proactive.java.policy
 -Dlog4j.configuration=file:scripts/proactive-log4j
 org.objectweb.proactive.examples.hello.HelloClient

windows> java -Djava.security.policy=scripts\unix\proactive.java.policy
 -Dlog4j.configuration=file:scripts\unix\proactive-log4j
 org.objectweb.proactive.examples.hello.HelloClient &