Exporting Active Objects and components as Web Services

34.1. Overview

This feature allows the call and monitoring of active objects and GCM components from any client written in any foreign language.

Indeed, applications written in C#, for example, cannot communicate with ProActive applications. We choose the web services technology that enable interoperability because they are based on XML and HTTP. Thus, any active object or component can be accessible from any enabled web service language.

34.2. Principles

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:

  • The SOAP Message

    The SOAP message is used to exchange XML based data over the internet. It can be sent via HTTP and provides a serialization format for communicating over a network.

  • The HTTP Server

    HTTP is the standard web protocol generally used over the 80 port. In order to receive SOAP messages you need to install an HTTP server that will be responsible of the data transfer. This server is not sufficient to treat a SOAP request.

  • The SOAP Engine

    A SOAP Engine is the mechanism responsible of making transparent the unmarshalling of the request and the marshalling of the response. Thus, the service developer doesn't have to worry with SOAP. In our case, we use Apache SOAP which is installed on a Jakarta Tomcat web server. Moreover, Apache SOAP contains a web based administration tool that permit to list, deploy and undeploy services.

  • The client

    Client's role is to consume a web service. It is the producer of the SOAP message. The client developer doesn't have to worry about how the service is implemented.

This figure shows the steps when an active object is called via SOAP.

Figure 34.1. This figure shows the steps when an active object is called via SOAP.


34.3. Pre-requisite: Installing the Web Server and the SOAP engine

First of all, you need to install the Jakarta Tomcat web server here and install it. You can find some documentation about it here, any version should be fine.

You don't really have to do a lot of installation. Just uncompress the archive.

To start and stop the server, launch the start and the shutdown scripts in the bin directory.

The last part consists in generating the web archive file using the ant target called 'proActiveWar' and copying it under the TOMCAT/webapps directory. Tomcat will automatically uncompress and install the web application.

34.4. Steps to expose an active object or a component as a web services

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

  • Write your active object or your component in a classic way; for example:

     A a = (A)PAActiveObject.newActive("A", new Object [] {}); 
    
  • Once the element is created and activated, deploy it onto a web server by using org.objectweb.proactive.extensions.webservices.WebServices API:

    • For an active object:

       WebServices.exposeAsWebService(Object o, String url, String urn, String [] methods); 
      

      where:

      • o is the active object

      • url is the url of the web server; typically http://localhost:8080.

      • urn is the service name which identify the active object on the server.

      • methods a String array containing the methods name you want to make accessible. If this parameter is null, all the public methods will be exposed.

    • For a component:

      WebServices.exposeComponentAsWebService(Component component, String url, String componentName);  
      

      where:

      • component is the component whose interfaces will be exposed as web services

      • url is the url of the web server; typically http://localhost:8080.

      • componentName is the name of the component. Each service available in this way will get a name composed by the component name followed by the interface name: componentName_interfaceName

34.5. Undeploy the services

To undeploy an active object as a service, use the ProActive static method:

WebServices.unExposeAsWebService ( String urn, String url );  

where:

  • urn is the service name

  • url the url of the server where the service is deployed

To undeploy a component you have to specify the component name and the component( needed to know the interfaces to undeploy):

WebServices.unExposeAsWebService ( String componentName , String url,  Component component);

34.6. Accessing the services

Once the active object or the interfaces component are deployed, you can access it via any web service enabled client (such as C#).

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

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 perform the right call then returns the reply into another SOAP message to the client.

34.7. Limitations

Apache Soap supports all defined types in the SOAP 1.1 specification. All Java primitive types are supported but it is not always the case for complex types. For Java Bean Objects, ProActive register them in the Apache SOAP mapping registry, in order to use a specific (de)serializer when such objects are exchanged. All is done automatically, you don't have to matter about the registering of the type mapping. However, if the methods attributes types or return types are Java Beans, you have to copy the beans classes you wrote into the $APACHE_SOAP_HOME/WEB_INF/classes.

34.8. A simple example: Hello World

34.8.1. Hello World web service code

Let's start with a simple example, an Hello world active object exposed as a web service:

public class HelloWorld implements Serializable {
   public HelloWorld () {}
   public String helloWorld (String name) {
      return "Hello world !";
   }
   public static void main (String [] args) {

    try {
        HelloWorld hw = (HelloWorld)PAActiveObject.newActive("HelloWorld", new Object []{});
        WebServices.exposeAsWebService(hw,
        "helloWorld","http://localhost:8080", new String [] { "helloWorld" }); 

    } catch (ActiveObjectCreationException e) {
            e.printStackTrace();
    } catch (NodeException e) {
            e.printStackTrace();
    }
   }
}

The active object hw has been deployed as a web service on the web server located at "http://localhost:8080" . The accessible service method is helloWorld.

Now that the server-side Web service is deployed, we can create a new client application in Visual Studio .NET.

34.8.2. Access with Visual Studio

In your new Visual Studio Project:

  • In the Solution Explorer window, right-click References and click Add Web Reference.

  • In the address box enter the WSDL service address, for example: http://localhost:8080/proactive/servlet/wsdl?id=helloWorld. When clicking the 'add reference' button, this will get the service's WSDL and creates the specific proxy to the service.

  • Once the web reference is added, you can use the helloWorld service as an object and perform calls on it:

    ...
    localhost.helloWorld hw = new localhost.helloWorld();
    string s = hw.helloWorld ();
    ...
    

34.9. C# interoperability: an example with C3D

34.9.1. Overview

C3D is a Java benchmark application that measures the performance of a 3D raytracer renderer distributed over several Java virtual machines using ProActive. C3D is composed of several parts: the distributed engine (renderers) and the dispatcher that is an active objet. This dispactcher permits users to see the 3D scene and to collaborate. Users can send messages and render command to this dispatcher. This enhancement of C3D is to send commands to the dispatcher from any language. To perform such an enhancement, the Dispatcher object must be exposed as a web service in order to a C# client for example controls it. Only one instruction has been added in the main method:

WebServices.exposeAsWebService (dispatcher, "C3DDispatcher",
                    "http://localhost:8080",  new String [] {
                    "rotateRight", "getPicture", "rotateLeft", "rotateUp",
                    "rotateDown", "getPixels", "getPixelMax", "waitForImage",
                    "spinClock", "spinUnclock", "addRandomSphere", "resetScene",
                    "registerWSUser", "unregisterWSUser"
                });

Once the dispatcher is deployed as a web service, we have a WSDL url: http://localhost:8080/proactive/servlet/id=C3DDispatcher. It will be usefull to construct the dispatcher client.

34.9.2. Access with a C# client

First of all, we have to generate the service proxy following the steps described for the hello world access.

All the SOAP calls will be managed by the generated proxy localhost.C3DDispatcher.

The dispatcher handling all calls

Figure 34.2. The dispatcher handling all calls


34.9.3. Dispatcher methods calls and callbacks

C# client registers to the C3D dispatcher and then can send commands. C3D is a collaborative application. Indeed, when a client performs a call, all others users must be advised by the dispatcher. Although dispatcher can contact ProActive applications, it cannot communicate with other applications (it cannot initiate the communication). In other words, the dispacher must communicate remotely with an application written in another language.

The answer to this problem is to use .Net web service on the C# user machine. Such a web service is waiting for callback requests that come from dispatcher. When receiving a request, the service sends it to the client via a .Net Remoting shared object. Thus, when the .Net web service receives a callback request, the C# client is updated thanks to propagated events.

Here are screenshots of the user application:

The first screenshot is a classic ProActive application

Figure 34.3. The first screenshot is a classic ProActive application


C# application communicating via SOAP

The application is using the same dispatcher the ProActive user uses.

Figure 34.4. C# application communicating via SOAP


34.9.3.1. Download the C# example

You can find here the whole C# Visual Studio .Net project. N.B: In order to run this project, you must install the Microsoft IIS server.