Parallel Services are a set of Web Services that aims to represent an access point to the ProActive Scheduler from outside of the Grid infrastructure domain where the Scheduler is installed in. There are essentially two main needs that motivates the introduction of these services: from the interoperability point of view a Web Service standard access to the ProActive Scheduler enables or simplifies users running in a specific administrative domain to take advantage of a Grid infrastructure deployed and managed in a separate administrative domain; from the system integration and software reusing point of view, exposing parallel mechanisms as services is a way to be able to reuse and compose them in a standard workflow language. The last aspect is quite important in a Service Oriented approach, where the main goal is to build a collection of services that hides the complexity of implementation details and that may be reused to easily build new services increasing organization agility.

Basically a Parallel Service is a service potentially executed in parallel on several machines, since its logic is dynamically mapped onto hosts by the ProActive Scheduler.

In the context of a Service Oriented Architecture (SOA), the Grid infrastructure exposes Parallel Services to external users, that are part of the SOA domain, in order to let them reuse Grid functionalities in an easy way. Functionalities exposed by the Grid infrastructure are not high level business functionalities directly usable by the end user at the business level, but they represent technical services that could be easily reused in a Service Oriented context. Technical services providing parallelism functionalities and hiding the complexity of grid parallelism management details, could be used to build higher level functional services that may internally be composed of several technical services. The advantages of this approach are the separation of concerns and the definition of a common and standard API able to introduce a loosely coupling dependence between the involved parties.

Figure 1.1. An high level view of a SOA / GRID infrastructure

The picture above aims at giving a view of a possible use of ProActive Parallel Services in a Service Oriented Architecture. The picture shows the main components: the end user can access to some higher level functionalities using his specific application. This end user application represents the entry point to the business processes of the organization, or to some of them. When the user triggers the execution of a business process, its execution is started and controlled by the Business Process Engine (typically a BPEL Engine). A process that is composed using some ProActive Parallel Services, invokes a Parallel Service at some point to leverage Grid capabilities. The Service creates ProActive jobs and submits them to the ProActive Scheduler running on the Grid Infrastructure. The Scheduler interacts with the ProActive Resource Manager to retrieve Grid resources where to schedule jobs on. When the Grid computation is finished, the result is returned back to the business process that can continue its elaboration and can give back the business result to the end user.

In ProActive Parallel Services, there are two kinds of services:

All of these Parallel Services use a support service that is a repository service, named PSRepository, used to store all the user resources needed to execute a Parallel Service.

Following an high level view of the whole set of the services we are speaking about.

Figure 1.2. Parallel Services overview

The parallel services represent the access point to the Grid environment via the ProActive Scheduler/Resource Manager installation. The repository service provides the storage management of the user resources (like archives of execution logic units, data and job resources) needed by the parallel service execution. In this way, the external user resources not accessible from inside the Grid infrastructure can be transferred on the Grid side; the resource transfer happens in a phase distinct from the call and execution of the service instance that will use it, so that an uploaded resource can be reused in more than one service execution and the service call is lighter than the case of a big data transfer during the service call.

All the Web Services described above are securized using the WS-Security standard specifications. The WS-SecurityPolicy implemented is the UsernameToken policy and HTTPS connection is required at transport level. The implementation is based on Rampart, the Axis2 module for WS-Security support.

The Parallel Services implementation is based one the Apache Axis2 Web Services open source engine.

The development of all the services follows a WSDL first approach in order to exactly define all the details of the WSDL/XSD definitions, which represent the interface effectively seen by external requesters. Once defined these interfaces, the code auto-generated by Axis2 will manage marshalling/unmarshalling of SOAP messages, while some skeleton classes implement the business logic of the service. The following diagram shows a view of the main packages of the ParallelServices subsystem.

	Warning
	In the whole chapter, all the package names are not reported entirely for a better visualization (all the reported package's complete names have the suffix org.ow2.proactive.parallelservices.).

Figure 3.1. Parallel Services subsystem

	Note
	In the ParallelServices subsystem only the main packages are shown (the autogenerated packages are not reported in this diagram). For each service a more detailed view is given in the sections below.

The ParallelServices subsystem depends directly on the ProActive Scheduler.

For each service the package having the name suffix .customskel contains the skeleton classes and any other Axis2 specific class customized with user's logic to override the default Axis2 behavior. For each service, the only package that depends on the WSDL definition is the .customskel package. For the PSRepository service, the repositoryimpl.internalrep contains the core logic of the service. In the same way, schedulerwsimpl.gridscheduler represents the SchedulerInterface's core logic, as paramsweepingimpl.internal represents the ParameterSweeping's core logic. A common package is used by all the .customskel packages, even if these dependencies are not reported in the diagram to keep it lighter.

The PSRepository service implementation includes several main packages, as shown in the following diagram:

Figure 3.2. PSRepository main packages

As said above, the repositoryimpl.customskel package contains the main skeleton class used to define the business logic of the service and classes that override the default behavior of the service once deployed in the Axis2 container. It is the only package that depends on the Axis2 automatically generated classes, contained in the two packages repository and repository.types, that are needed to manage the marshalling/unmarshalling of SOAP messages. The PSRepository core implementation is contained in the repositoryimpl.internalrep package, which is divided into two sub-packages. The repositoryimpl.internalrep.api contains classes and interfaces that define a simple API designed to provide the functionalities needed by the PSRepository service.

Figure 3.3. Repository Interface API

The package repositoryimpl.internalrep.db contains a Data Base based implementation of that API.

Figure 3.4. Repository Interface data base implementation

The current implementation stores in a Data Base all the meta information about stored archives, while the binary content of each archive is stored in a configured location on the file system. The Data Base access is based on JDBC. In the current release the open source relational database Apache Derby is used as in memory Data Base Management System.

The SchedulerInterface service implementation includes several main packages, as shown in the following diagram:

Figure 3.5. SchedulerInterface main packages

The schedulerwsimpl.customskel package contains the main skeleton class used to define the business logic of the service and classes that override the default behavior of the service once deployed in the Axis2 container. It is the only package that depends on the Axis2 automatically generated classes, contained in the packages schedulerws, schedulerws.types and _0._3.jobdescriptor.proactive, that are needed to manage the marshalling/unmarshalling of SOAP messages. This package depends on the package repositoryimpl.internalrep.api, that manages the archives stored in the repository and accessed by this service, and it depends also on the package schedulerimpl.gridscheduler that contains the main logic to access the ProActive grid scheduler. Basically the package schedulerimpl.gridscheduler contains the classes that access the ProActive Scheduler, adapting the behaviour to the requirements of the ParallelServices. There are classes that are in charge of the simple access to the ProActive Scheduler functions, classes that are in charge of the asynchronous behaviour of some services, and classes that are in charge of the management of the job submission starting from the archive stored in the repository via the PSRepository service

Let's give an idea of the interactions between main classes involved in the job submission via the a Job archive.

Figure 3.6. Job Submission via archive

In the picture reported above, we can see the sequence of the main steps followed by the implementation in order to submit a job to the ProActive Scheduler starting from an existing archive and giving new inputs, as described in the functional description of the SchedulerInterface. In the current implementation, once the client invokes the submitJobByRef operation on the SchedulerInterface service, the CustomSchedulerInterfaceSkeletonDelegate is invoked by Axis2 (step 1) and the implementation starts retrieving from the repository (via the RepositoryInterface) the archives previously stored with the archive reference archiveRef (step 2). Once retrieved the stored job archive, the JobInstanceDirManager is called (step 4). The JobInstanceDirManager is a manager of the directories that are dedicated to the execution of the jobs. As said in the functional description, for each job a working directory can be used by the user if needed, so this entity is in charge of instantiate that. The location for the working directory root is configured by the user in the schedconf.properties configuration file. At this point the ArchiveJobFactory can create the job starting from the job archive, the new job inputs given by the client, and the working directory dedicated to that instance (step 6). The job archive could contain several directories (for lib, scripts, etc.) and the path of these directories has to be referenced in the job descriptor file using some predefined variables. So a JobDescriptorPreprocessor is involved in the interaction at this point (see the step 7 in the diagram) in order to add in the job descriptor file the predefined variables that point to the referenced directories. In this step , the preprocessor is also in charge of update in the job descriptor, the value of the variables given as new input for the current job execution. At this point the job descriptor is ready to be crated (step 9) and at this point the location of all the classes and lib files needed by the job are added to the job environment (step 10). Now the job is submitted to the Scheduler (step 12) and the job identifier is returned back to the client.

The packages included in the Parameter Sweeping Web Service implementation are shown in the figure bellow.

Figure 3.7. Parameter Sweeping main packages

As said above, the paramsweepingimpl.customskel package contains the main skeleton classes to define the business logic of the service and classes that override the default behavior of the service once deployed in the Axis2 container. It is the only package that depends on the Axis2 automatically generated classes, contained in the three packages types, parametersweeping and parametersweeping.types, that are needed to manage the marshalling/unmarshalling of SOAP messages. The parameter sweeping Web Service core implementation is contained in the parametersweeping.customskel and parametersweeping.internal packages.

The parametersweeping.hotspots package defines the interfaces and abstract classes to be extended by the user in order to implement the business logic of the application according to the Parameter Sweeping pattern.

The schedulerwsimpl.gridscheduler package contains classes that offer interaction with the ProActive Scheduler.

The repositoryimpl.internalrep.api package contains classes that offer access to the archives repository.

The business logic for the operations exposed by the web service is treated at the level of CustomParameterSweepingServiceSkeletonDelegate class, in the parametersweeping.customskel package. The service needs to create a Job (ProActive Scheduling) and submit it to The ProActive Scheduler. We recall that a ProActive Job is composed of a bag of tasks. Each task can be executed independently on a remote resource.

A parallel service delegates the creation of the Job to be submitted to the Scheduler to a JobFactory. For the Parameter Sweeping Web Service the factory used is the ParSweepingjobFactory. For the creation of the job, the JobFactory needs: the archive containing the business code for the parameter sweeping pattern, the name of the classes that implement the hotspots, the input data, configuration data and the context info. All these information have been provided as argument, by the end client, when calling the web service.

Once the job is created by the factory, it will be sent to the ProActive Scheduler for execution. An event handler will also be sent to the Scheduler in order to receive an event when the job is finished.

If the operation has been triggered synchronously, via the ParameterSweepingPortType (see Section 2.3.4, “The ParameterSweeping Functionalities”) the handler will wake the calling thread in order to send the response to the end client, when a "job finished" event is received.

For the asynchronous call, the Handler is responsible to contact the end client and send the response when a "job finished" event occurs.

Below, a sequence diagram illustrating the asynchronous call to the Parameter Sweeping Web Service.

	Note
	Not all the entities involved into the process are shown in the diagram.

Figure 3.8. Parameter Sweeping invocation scenario - asynchronous

The ParSweepingJobFactory is responsible for calling the concrete implementation of the Sweeper hotspot. The factory will use the output of the Sweeper in order to create input arguments for Tasks for the Job. The business code for each task is given by the concrete implementation of the second hotspot, the DataSliceTreater.

ProActive Parallel Services have been developed using Apache Axis2 Web Services container. The actual distribution of Parallel Services is based on Axis2 1.5.3 version and they use the release 3.0.0 of ProActive Scheduler / Resource Manager.

To run the services, the following components are needed:

To install and configure the environment you need to perform the following operations:

At this point you can configure and deploy the Parallel Services.

Parallel Services are distributed as a service archive, having the Axis2 service archive format. The ParallelServices.aar archive contains all the ProActive Parallel Services to be deployed as an Axis2 servicegroup.

Since the configuration for the services is contained inside the service archive, before deploying the archive you need to modify some of the following configuration files contained in the archive (uncompress the archive to edit them):

Once you have modified these configuration files, re-create the archive with the modified configuration files (just compress everything one more time), and deploy the services group (just copy the archive ParallelServices.aar under the Axis2 services repository, the WEB-INF/services directory).

Once you have installed and configured everything as said above, you are ready to run the services.

Once the project is checked out, its contents is organized as described in the following extract of its readme.txt file.

                
PROJECT CONTENTS
--------------------------------

The project is organized as follows:

./src/parallelservices/src/repository    : src for the PSRepository service
./src/parallelservices/src/scheduler     : src for the SchedulerInterface service
./src/parallelservices/src/paramsweeping : src for the ParameterSweeping service
./src/parallelservices/src/common        : src commons to all the other services (or some of them)
./src/parallelservices/src/utils         : src for utilities classes
./src/parallelservices/tests             : src for tests
./src/parallelservices/client            : src for client stub and sample client code
          
./compile :
 - lib, formatlib, eclipse_formatter_config.properties and eclipse_formatter_config.xml: 
   libs and ant artifacts specific for ant target execution
 - build-res: contains everything needed to compile and build the deployment version of the Parallel Services, such as:
         - configprop: contains all the configuration files to configure the services 
         - pa_stub_generation: contains a build file used to generate the ProActive stubs needed by the application
         - servicesxml: contains the services.xml file to build the deployment archive for 
           the Parallel Services group
        This directory will contain also all the resources automatically generated by the building process:
        - dist-tmp: this directory is created to contain the distribution archives,
           that will be generated by the building process.
        - classes: all the class files, except test classes
        - test-classes: all the test class files
        - output: all the source files automatically generated (by the build process using wsdl2java tool)
        - junitReports: all the jUnit report files generated by jUnit tests when launched via the building process  
        
          
 - build.xml : the main ant build file for building process. 
               It imports all the other ant files. All the ant targets 
                MUST be started running ant from this build file.
 - build.properties : it contains the properties that are specific to the user environment 
                       and that should be changed in order to perform some of the building steps.
 - build : executable script to use to run ant on Linux platforms
 - build.bat : executable script to use to run ant on Windows platforms 

./dist : the directory that will contain all the distribution files 

./doc : contains all the resources needed to generate the project's documentation.
        IMPORTANT: this directory will contain all the generated documentation, 
        in a 'dist' directory automatically created by the building process.          

./jobArs : contains some sample job archives. 
           They have been built starting from the samples of the ProActive Scheduler distribution, 
           adapting, where necessary, the job descriptor and the needed resources in order to build 
           correctly the corresponding job archive. (These archives can be used as testing/sample
           archives, since they can be stored in the repository, via PSRepository service, and can 
           be submitted to the ProActive Scheduler via the SchedulerInterface service, using their 
           reference in the repository)

./lib/junit : contains the jUnit jar files         
./lib/4WSRep : contains all the jar files needed to manage and access the repository
./lib/currentSchedDistLib : contains all the jar files of the Scheduler distribution currently used
./lib/axis2_rampart : contains all the jar files of the axis2/rampart installation actually used
                      
                      Actually these set of jar files is composed of : 
                    - all the Axis2 1.5.3 jar files
                    - all the Rampart 1.5 jar files (Rampart is the module providing WS-Security support for Axis2)
                    

./proactive: contains a sample ProActiveConfiguration.xml file

./psArs : contains sample parameter sweeping archives.
          (These archives can be used as testing/sample parameter sweeping archives, since they can 
          be stored in the repository, via PSRepository service, and can be submitted to the 
          ProActive Scheduler, via the ParameterSweeping service)

./test-res : contains resources needed for test execution

./wsdl : contains all the WSDL and XSD files for all the parallel services.

            

Check the readme.txt file in order to have all the information related to the source project.

Once the check-out is complete, in the whole project, several source files are missing. The development of each service follows the WSDL-first approach. Starting from the service contract, such as the WSDL definition of the service, (contained in the ./wsdl/parallel_services dir) the skeleton sources are automatically generated by the wsdl2java tool provided by Axis2 (that's why these source files are not under version control, while the WSDL files are). This code is generated launching the ant target cleanAndGenerate.all (Each time the operation is performed, the old generated sources are replaced by the new ones) Once done that, the source code is complete and ready to build the services to deploy. BE CAREFUL: all the ant targets have to be run starting from the main build file: ./compile/build.xml and including in the ant classpath the jar files contained in the ./compile/lib directory.

In the source project, you can set the configuration files we have spoken about in Section 4.3, “Web Services Configuration and Deployment” editing them in the directory ./compile/build-res/configprop. Once done, you can automatically build the services archive just running the aar ant target. It will produce the archive ./compile/build-res/dist/ParallelServices.aar that you could deploy under Axis2 as said above. Otherwise, if your Axis2 container is already installed and it is on the local machine (or on a machine where its folder is reachable via file system) you can directly build and deploy the parallel services group under your Axis2 installation. To do that:

At this point you could switch on all the configured servers and test the Parallel Services.