<commit_before><chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hands_on_programming_CMA"><info><title>Active Object Tutorial</title></info>
  
<para>In this chapter we present a step by step introduction to
  programming with ProActive.</para>

  <para>The program that we will develop is a remote computation and monitoring agent. As we
  progress through the example we 
  will increase the complexity of the agent by using different features of ProActive.</para>

  <itemizedlist>
    <listitem>
      <para>In part one, we will code a 'client-server' application, the server
      being an active object that acts as a monitoring agent.</para>
    </listitem>

    <listitem>
      <para>In part two, we will see how we can control the activity of an active
      object.</para>
    </listitem>
 <listitem>
      <para>In part four the exercise will explain message synchronization and
      synchronous and asynchronous method calls using a monitoring agent that makes chained calls.</para>
    </listitem>

    <listitem>
      <para>In part five we will add mobility to this active object and have the agent migrate
      to another computer and report on the status of the JVM on the machine.</para>
    </listitem>
    <listitem>
      <para>In part six we will show how to use ProActive groups to monitor several machines
      at the same time.</para>
    </listitem>
	<listitem>
		<para>In part seven will show how to expose an active object as a web service. </para>
	</listitem>

   <listitem><para>
   		The next parts are dedicate to showing how we can transform a sequential application that finds a number of primes
   		into a distributed application. In this part we will also use the ProActive Master-Worker API. 
   </para></listitem>
  </itemizedlist>
	<para>
		All the exercises in this chapter are available as an Eclipse workspace. 
		The Eclipse environment is set up to run each exercises as soon as 
		the needed code is inserted. The tasks needed for the examples to run properly are annotated with
		//TODO tags and show up under the Eclipse tasks list. 
	</para>
	
	<para> To further learn what is needed for the 
		running ProActive applications read <xref linkend="Installation"/>. 
	</para>	
	
	<section xml:id="SimpleCMA"><info><title> Simple Computation And Monitoring Agent</title></info>
		
	<para>
		Welcome to your first ProActive program! This is one of the simplest applications that can be
		written using ProActive. We will create an active object locally and get the state of 
		the JVM through it. Our application is composed of three classes with a client-server structure. 
	</para>
		<para>	
		The example illustrates the creation of an active object from the 
		<literal>CMAgent</literal> class that will be
		used by the <literal>Main</literal> class to retrieve the JVM state
		 for a machine and print it to the standard output.		
		The <literal>Main</literal> class corresponds to the client, and is
		 only a container for the <literal>main()</literal> method, while 
		the <literal>CMAgent</literal> class corresponds to the server and
		 its instance is an active object which provides a <literal>getCurrentState()</literal>
		method as a remote service.
	</para>		
	<para>
		To safely use the <literal>CMAgent</literal> class as an active object
		we have to meet three requirements.
	</para>
		<itemizedlist>
			<listitem><para><emphasis role="bold">no direct access to field variables</emphasis> - If
							<literal>public</literal> variables are used then the stub class generated from
							the original class may become decoupled from the original class. If a change is
							affected on the public field variable in the stub instance, the change will not be 
							 propagated to the the class instance from which the stub was generated. The safe
							 way to change variables is to set them as <literal>private</literal> and access
							 them through <literal>public get/set</literal> methods.   </para></listitem>
			
			<listitem>
			<para><emphasis role="bold">provide a no-argument and preferably an empty constructor</emphasis> - A 
							no-argument constructor is necessary to create the stub class needed for communication.
							A stub cannot be created if there are only constructors with arguments since the 
							stub is only meant to abstract the communication from the active objects. 
							
							If there is no constructor defined, the Java compiler
							will automatically create a no-argument constructor that initializes all instance variables
							to the default value. However, if there is an already defined constructor with arguments 
							then no default no-argument constructor will be created by the compiler. In this case
							the definition of a no-argument constructor is mandatory for stub creation. The safest way is
							to always define a no-argument constructor.
							Also, the constructor should be empty so that on stub creation no 
							initialization is done on the stub.    
						</para>
			</listitem>
			<listitem><para><emphasis role="bold">provide remote functionalities as public methods with return types that can be subclassed and are serializable</emphasis> - Since
			the stub is created through inheritance, the only methods it can use for communication are
			the inherited public methods from the superclass. The return types of the methods have to be 
			 subclassable and therefore not final. ProActive provides several wrappers for Java types
			 that are final.The example uses the <literal>StringWrapper</literal> class in order to provide a wrapper for the 
			final <literal>String</literal> class.  Since ProActive uses a proxy mechanism and
			 the <literal>String</literal> class is final, it’s not
			possible to subclass a String and to perform asynchronous calls.	
			ProActive provides several wrappers for final classes: <literal>StringWrapper, BooleanWrapper, 
			IntegerWrapper, DoubleWrapper</literal> and <literal>FloatWrapper</literal>.
			 These have to be used in
			replacement of <literal>String, Boolean, Integer, Double</literal> and <literal>Float</literal>
			in classes which will be active objects. If you don’t use wrappers, method calls will be synchronous.
			In our case the return type is <literal>State</literal> which is not final.
			</para>	
			
			
			</listitem>
		</itemizedlist>	
	
	  <section><info><title> Classes Used </title></info>
		
		<itemizedlist><info><title>ProActive</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.api.PAActiveObject</literal> - used to create an instance of an active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.core.node.NodeException</literal> - used to catch the exceptions that the creation of the Node might throw</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.ActiveObjectCreationException</literal> - used to catch the exceptions that the creation of the active object might throw </para></listitem>
		</itemizedlist>
		<itemizedlist><info><title>Other</title></info>
			
				<listitem><para><literal>java.io.Serializable</literal> - used to make the <literal>State</literal> object serializable so it can 
				be sent across the network    </para></listitem>
				<listitem><para><literal>java.lang.management.ManagementFactory</literal> - used to get various information about the machine the active object is running on </para></listitem> 
				<listitem><para><literal>java.net.InetAddress</literal> - used to get the address of the active object is running on </para></listitem>
				<listitem><para><literal>java.net.UnknownHostException</literal>  - used to catch the exceptions that might be thrown when requesting host information </para></listitem>
				<listitem><para><literal>java.util.Date</literal> -  used to get the a time for the requested state </para></listitem>  
		</itemizedlist>
		</section>
  	<section><info><title>CMA Architecture and Skeleton Code </title></info>
		
	<figure><info><title> Client-Server architecture - the <literal>Main</literal> class acts as 
	a client and uses the <literal>CMAgent</literal> class as a server</title></info> 
		  <mediaobject>
          <imageobject>
            <imagedata scalefit="1" width="100%" contentdepth="100%"   fileref="guided_tour/pics/cma/simpleCMA.jpg" format="JPG" />
          </imageobject>
        </mediaobject>
      </figure>
	<para>For our Monitoring agent we use three classes. The first two classes are regular Java objects.
	The first class is <literal>State</literal> which we use to get some information on the JVM the 
	object is located on. This object will be use as return value for the <literal>getCurrentState()</literal>
	method in the <literal>CMAgent</literal> class.
	</para>
	
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/state_full.snip"/></textobject></programlisting>
	
	<para>
	
		The Monitoring agent class is a regular Java class  
	</para>	
	 <programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/fullCMA.snip"/></textobject></programlisting>
	<para>with only one method.</para>
	
	<para>
	
	 For this simple exercise we only need to add ProActive code in the Main class
	 where we instantiate the active object. 
	  </para>
	
	<programlisting xml:lang="java"><textobject><textdata fileref="guided_tour/code_snippets/CMAgent/simple_CMA_skeleton.txt"/></textobject></programlisting>
	
	</section>
	<section><info><title>Proposed Work</title></info>
		
		<para>
			You  can find the skeleton code for the exercise in the Eclipse exercises workspace under the name 
			<literal>1. SimpleCMAgent</literal>.
		</para>
	<orderedlist>
			<listitem><para>Create an active object using the <literal>org.objectweb.proactive.api.PAActiveObject.newActive(...)</literal> 
				static method.</para></listitem>
			<listitem><para>Call the  <literal>getCurrentState()</literal> method and display the results.</para></listitem>
			<listitem><para>Since the active object has a never ending thread we need to make an explicit call in order
			to stop it. Use <literal> PAActiveObject.terminateActiveObject(...)</literal> to stop the
			active object.</para>
			</listitem>
			<listitem><para>
				Remove the <literal>Serializable</literal> from the class <literal>State</literal> and explain the results when running the example.
				</para>
			</listitem>
		</orderedlist>
	</section>
	
	<section><info><title> Solutions and Full Code </title></info>
		
	
		<para>We will now show how to create the server object. For now, we want the
		<literal> CMAgent</literal> active object 
		 to be created on the current Node (we will see later how to distribute the program). To create an instance of
		  a remotely accessible object we must use the <literal>ProActive.newActive(...)</literal> static method. We pass
		  as an argument the name of the class to be instantiated  and arguments for the constructor of the class.
		  In our case <literal>CMAgent</literal> does not need any arguments for the constructor and therefore we use <literal>null </literal>. 
		  <programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_instatiation.snip"/></textobject></programlisting>
		</para>
	<para>
		Invoking a method on a remote active object is transparent and is similar 
		to  invoking a method on
		a local object of the same type. The user does not have to deal with catching exceptions
		related to the remote communication. The only modification brought to the code by ProActive
		is during the active objects creation. All the rest of the code can remain unmodified, 
		fostering software reuse. </para>
		
		<para>
			To invoke the <literal>getCurrentState()</literal> method  we execute:
		</para>
			
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_call.snip"/></textobject></programlisting>

	<para>To stop the active object we call the <literal> PAActiveObject.terminateActiveObject(ao, false)</literal> method. The 
	<literal>false</literal> argument is used in order to call the terminate method as a regular request. If the
	argument is <literal>true</literal> the method call is served as an immediate service (executed as soon as the
	current executing request is completed regardless of how many other requests might be waiting)
	and synchronously (the caller thread blocks until it receives the results). </para>
	
		<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_terminate_call.snip"/></textobject></programlisting>
	
	<para>Passive objects in ProActive are always passed by deep copy when returned as a method results.
	If the object State does not implement <literal>Serializable</literal> ProActive will not be able to 
	to make a deep copy of the object and will throw an exception. </para>
	
	<para> The full code of the <literal>Main</literal> class is the following. </para>
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_Main.snip"/></textobject></programlisting>
	
	</section>
	</section>

  <section xml:id="Active_Object_LifeCycle"><info><title>Active Objects Lifecycle: Using InitActive and EndActive</title></info>
    

    <para>Active objects, as their name indicates, have an activity of their
    own (an internal thread). By default the active object steps through
    the constructor, the <literal>initActivity</literal>, the <literal>runActivity</literal>,
     and when the <literal>terminate</literal> method is called on
    the <literal>Body</literal> of the active object through the <literal>endActivity</literal> method.
    It is possible to control the initialization, running, and ending phase of this
    thread by implementing three interfaces: <literal>InitActive</literal>, <literal>
    RunActive</literal>,and <literal>EndActive</literal>.These interfaces define the
    <literal>initActivity</literal>, <literal>runActivity</literal> and <literal>endActivity</literal>
    methods. One of the reasons for using <literal>initActivity</literal>
    method is the presence of the empty constructor in an active object. The <literal>initActivity</literal>
    method is automatically called on the creation of an active object in order to set up the 
    object without using the constructor. The <literal>runActivity</literal> method allows the user
    to control the active object request queue. By implementing the <literal>EndActive</literal> interface is also possible to 
    do clean up before the active object thread is stopped. </para>


    <para>The following example will help you to understand how and when you
    can initialize and clean the activity. The example will implement the <literal>InitActive</literal>, <literal>RunActive</literal>,
     and
    <literal>EndActive</literal> interfaces. However <literal>RunActive</literal> has a more complex structure than
    it is presented here. To understand how to use <literal>EndActive</literal>
    <literal>RunActive</literal> interface read <xref linkend="ActiveObjectCreation"/> </para>

	  <section><info><title> Classes Used </title></info>
		
		
		<itemizedlist><info><title>New classes used</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.Body</literal> - used to access the body of the active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.Service</literal> - used to access the queue of the active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.InitActive</literal> - used for defining the <literal>initActivity(Body body)</literal> method, which is run at active object initialization</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.EndActive</literal> - used for defining the <literal>endActivity(Body body)</literal> method, which is run at active object destruction </para></listitem>
			<listitem><para><literal>org.objectweb.proactive.RunActive</literal> - used for defining the <literal>runActivity(Body body)</literal> method, which manages the queue of requests</para></listitem>
			<listitem><para><literal> org.objectweb.proactive.core.util.wrapper.LongWrapper</literal> - used to wrap the <literal>Long</literal> return type</para></listitem>
		</itemizedlist>

		<itemizedlist><info><title>Previously used classes</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.api.PAActiveObject</literal> - used to create an instance of an active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.core.node.NodeException</literal> - used to catch the exceptions that the creation of the Node might throw</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.ActiveObjectCreationException</literal> - used to catch the exceptions that the creation of the active object might throw </para></listitem>
			<listitem><para><literal>java.io.Serializable</literal> - used to make the <literal>State</literal> object serializable so it can 
				be sent across the network  </para></listitem>
				<listitem><para><literal>java.lang.management.ManagementFactory</literal> - used to get various information about the machine the active object is running on </para></listitem> 
				<listitem><para><literal>java.net.InetAddress</literal> - used to get the address of the active object is running on </para></listitem>
				<listitem><para><literal>java.net.UnknownHostException</literal>  - used to catch the exceptions that might be thrown when requesting host information </para></listitem>
				<listitem><para><literal>java.util.Date</literal> -  used to get the a time for the requested state </para></listitem>  
		</itemizedlist>
		
	</section>

    <section><info><title>Initialized CMA Architecture and Skeleton Code</title></info>
      

      <para>The <literal>CMAgentInitialized</literal> class extends the
      <literal> CMAgent </literal>class from the previous example, and implements
      the interfaces <literal>InitActive</literal> and <literal>EndActive</literal>.
      It acts as a server for the <literal>Main</literal> class.</para>

      <para><figure><info><title> CMA Architecture and Skeleton Code Using intialization</title></info>
      		 
          <mediaobject>
            <imageobject>
              <imagedata scalefit="1" width="100%" contentdepth="100%"    fileref="guided_tour/pics/cma/initCMA.jpg" format="JPG" />
            </imageobject>
          </mediaobject>
        </figure></para>
    
    
    <para>
    	To implement the application we will create a class that inherits from the 
    	<literal>CMAgent</literal> class and implements the <literal>InitActive</literal>, <literal>RunActive</literal>, and <literal>EndActive</literal> 
    	interfaces. 
	 	<programlisting xml:lang="java"><textobject><textdata fileref="guided_tour/code_snippets/CMAgent/init_CMA_skeleton.txt"/></textobject></programlisting>
    </para>
    <para>
    	By default an active object has a never ending thread that should be stopped when the object is 
    	not needed anymore. The method <literal>terminate()</literal> serves the purpose of destroying the 
    	object. However, if an explicit call to terminate the object is not made, ProActive has its own
    	distributed garbage collection system that is able to decide when an active object can be destroyed. 
    </para>
    <para>
    	The <literal>Main</literal> is similar with the one in the previous example.
    	We will change the object created from <literal>CMAAgent</literal> to 
    	<literal>CMAAgentInitialized</literal> and also we will call the <literal>terminate() </literal> method to 
    	destroy the object.
    </para>
    
    </section>

    	<section><info><title>Proposed Work</title></info>
		
		<para>
			You  can find the skeleton code for the exercise in the Eclipse exercises workspace under the name 
			<literal>2. InitializedCMAgent</literal>.
		</para>
		<orderedlist>


			<listitem><para>Use <literal>initActivity(Body body)</literal> to print information 
			about the start location of the active object and record the start time.</para></listitem>
			<listitem><para>Use <literal>endActivity(Body body)</literal> to print information about
			 the stop location of the active object, calculate the running time, 
			 and print the number of requests served.</para></listitem>

			<listitem><para>Calculate the last request duration
			 and count the requests using <literal>org.objectweb.proactive.Service.waitForRequest()</literal> 
			and <literal>org.objectweb.proactive.Service.serveOldest()</literal> </para></listitem>
			<listitem><para>Use <literal>org.objectweb.proactive.core.util.wrapper.LongWrapper</literal> 
			to return a wrapped <literal>Long</literal> value.</para></listitem>
		</orderedlist>

	</section>
    
    <section><info><title>Solution and Full Code</title></info>
    	
    	<para>
    	We only need to extend the <literal>CMAgent</literal> class and implement the 
    	interfaces. In <literal>initActivity(Body body)</literal> we  use <literal>body.getName()</literal>
    	to get the name of the active object and <literal>body.getNodeUrl()</literal> to get the location.
    	In  <literal>endActivity(Body body)</literal> we also use <literal>body.getNodeUrl()</literal> to get the location. 
    	</para>
    	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/cma_init_full.snip"/></textobject></programlisting>


    </section>
  
  
  </section>
  <section xml:id="deployment_guide_CMA"><info><title>Application Deployment</title></info>
  	
  	<para>
  		In the previous example the applications were deployed inside
  		the same JVM. This section will focus on showing how to deploy
  		the application on different nodes using deployment
  		descriptors.
  	</para>
  	<section><info><title>Deployment Related Concepts</title></info>
  		
  		<para>
  			A first principle is to fully eliminate from the source
  			code the following elements:
  			<itemizedlist>
  				<listitem>
  					<para>machine names</para>
  				</listitem>
  				<listitem>
  					<para>creation protocols</para>
  				</listitem>
  				<listitem>
  					<para>registry lookup protocols</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			The goal is to deploy any application anywhere without
  			changing the source code. For instance, we must be able to
  			use various protocols, rsh, ssh, Globus, LSF, etc., for
  			the creation of the JVMs needed by the application. In the
  			same manner, the discovery of existing resources or the
  			registration of the ones created by the application can be
  			done with various protocols such as RMIregistry, Globus
  			etc. Therefore, we see that the creation, registration and
  			discovery of resources have to be done externally to the
  			application.
  		</para>
  		<para>
  			A second key principle is the capability to abstractly
  			describe an application, or part of it, in terms of its
  			conceptual activities. The description should indicate the
  			various parallel or distributed entities in the program.
  			For instance, an application that is designed to use three
  			interactive visualization nodes, a node to capture input
  			from a physics experiment, and a simulation engine
  			designed to run on a cluster of machines should somewhere
  			clearly advertise this information.
  		</para>
  		<para>
  			Now, one should note that the abstract description of an
  			application and the way to deploy it are not independent
  			piece of information. If for example, we have 
  			a simulation engine, it might register in a specific
  			registry protocol, and if so, the other entities of the
  			computation might have to use that lookup protocol to bind
  			to the engine. Moreover, one part of the program can just
  			lookup for the engine (assuming it is started
  			independently), or explicitly create the engine itself. To
  			summarize, in order to abstract away the underlying
  			execution platform, and to allow a source-independent
  			deployment, a framework has to provide the following
  			elements:
  			<itemizedlist>
  				<listitem>
  					<para>
  						an abstract description of the distributed
  						entities of a parallel program or component,
  					</para>
  				</listitem>
  				<listitem>
  					<para>
  						an external mapping of those entities to real
  						machines, using actual creation, registry, and
  						lookup protocols.
  					</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			To reach that goal, the programming model relies on the
  			specific notion of Virtual Nodes (VNs):
  			<itemizedlist>
  				<listitem>
  					<para>
  						a VN is identified as a name (a simple string)
  					</para>
  				</listitem>
  				<listitem>
  					<para>a VN is used in a program source</para>
  				</listitem>
  				<listitem>
  					<para>
  						a VN is defined and configured in a deployment
  						descriptor (XML)
  					</para>
  				</listitem>
  				<listitem>
  					<para>
  						a VN, after activation, is mapped to one or to
  						a set of actual ProActive Nodes
  					</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			Of course, distributed entities (Active Objects), are
  			created on Nodes, not on Virtual Nodes. There is a strong
  			need for both Nodes and Virtual Nodes. Virtual Nodes are a
  			much richer abstraction, as they provide mechanisms such
  			as set or cyclic mapping. Another key aspect is the
  			capability to describe and trigger the mapping of a single
  			VN that generates the allocation of several JVMs. This is
  			critical if we want to get at once machines from a cluster
  			of PCs managed through Globus or LSF. It is even more
  			critical in a Grid application, when trying to achieve the
  			co-allocation of machines from several clusters across
  			several continents.
  		</para>
  		<para>
  			Moreover, a Virtual Node is a concept of a distributed
  			program or component, while a Node is actually a
  			deployment concept: it is an object that lives in a JVM,
  			hosting Active Objects. There is of course a
  			correspondence between Virtual Nodes and Nodes: the
  			function created by the deployment, the mapping. This
  			mapping can be specified in an XML descriptor. By
  			definition, the following operations can be configured in
  			such a deployment descriptor:
  			<itemizedlist>
  				<listitem>
  					<para>
  						the mapping of VNs to Nodes and to JVMs
  					</para>
  				</listitem>
  				<listitem>
  					<para>the way to create or to acquire JVMs</para>
  				</listitem>
  				<listitem>
  					<para>the way to register or to lookup VNs</para>
  				</listitem>
  			</itemizedlist>

  		</para>
  	</section>

  	<section><info><title>Deployment Descriptor File</title></info>
  		
  		<para>
  			The deployment descriptor is an <literal>XML</literal> file containing
  			information on the properties listed above. We will use a
  			simple <literal>XML</literal> file to deploy the monitoring agent on a
  			remote machine. The deployment <literal>XML</literal> file is composed of several
  			parts, each with different options. For our example we
  			will use a simple version. To find out more about
  			deployment and deployment descriptors read
  			<xref linkend="XML_Descriptors"/>
  			.
  		</para>
  		<para>
  			The document uses the
  			<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www-sop.inria.fr/oasis/ProActive/schemas/deployment/3.3/deployment.xsd">
  				XML Schema
  			</link>
  			present at the Oasis website.
  		</para>
  		<para>
  			To avoid mistakes when building <literal>XML</literal> descriptors, ProActive
  			provides an <literal>XML</literal> Schema called DescriptorSchema.xsd. To
  			validate your file against this schema, the following line
  			must be put at the top of the <literal>XML</literal> document.
  		</para>

  		<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/schema_location.txt"/></textobject></programlisting>
  		<para>
  			The <literal>XML</literal> file has a section for defining variables needed
  			later in the document. In our case, we define the
  			location of the ProActive and Java installations on the
  			local and remote machine. To start the JVM and use
  			ProActive on the remote machine, we need to define the
  			location of the Java and ProActive files. This can be done
  			by specifying the paths in the infrastructure section of
  			the deployment descriptor or by setting the <literal>CLASSPATH</literal> and
  			<literal>JAVA_HOME</literal> variables as described in
  			<xref linkend="Installation"/>
  			.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/variable_definition.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			Next, we define the virtual nodes that will be used. In
  			our case we define a node that can contain several JVMs by
  			setting the <literal>multiple</literal> property.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/component_definition.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			The deployment part of the <literal>XML</literal> file specifies how the JVMs
  			are started and mapped on the Virtual Nodes It has two
  			parts one dealing with the mapping of the JVMs to the
  			Virtual Nodes and another related to how the JVMs are
  			created. In our case we map one JVM to the remote node and
  			define a process reference that will be used later in the
  			file (infrastructure section) to describe how the JVM is
  			started.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/jvms.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			Next is the infrastructure part that defines the paths to
  			the files needed, the hosts on which the JVMs are deployed
  			and which protocols are used for communication.

  			The process definition with the id
  			<literal>genericRemoteJVM</literal>
  			is necessary to tell the JVM machine how to start a node
  			on the machine that has a reference to it (
  			<literal>processReference</literal>
  			). It will use the paths provided to locate the Java and
  			ProActive files on the remote machine. Here we are using
  			<literal>rsh</literal> to start the JVM but several other protocols can be
  			used as described in
  			<xref linkend="XML_Descriptors"/>
  			.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/infrastructure.txt"/></textobject></programlisting>
  		</para>
  		</section>
  		</section>
  		<section><info><title> Remote Monitoring Agent</title></info>
  			
  			<para>
  				In this part of the tutorial we will see how to start a monitoring agent on a remote machine<commit_msg>added diagram showing the deployment process<commit_after><chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hands_on_programming_CMA"><info><title>Active Object Tutorial</title></info>
  
<para>In this chapter we present a step by step introduction to
  programming with ProActive.</para>

  <para>The program that we will develop is a remote computation and monitoring agent. As we
  progress through the example we 
  will increase the complexity of the agent by using different features of ProActive.</para>

  <itemizedlist>
    <listitem>
      <para>In part one, we will code a 'client-server' application, the server
      being an active object that acts as a monitoring agent.</para>
    </listitem>

    <listitem>
      <para>In part two, we will see how we can control the activity of an active
      object.</para>
    </listitem>
 <listitem>
      <para>In part four the exercise will explain message synchronization and
      synchronous and asynchronous method calls using a monitoring agent that makes chained calls.</para>
    </listitem>

    <listitem>
      <para>In part five we will add mobility to this active object and have the agent migrate
      to another computer and report on the status of the JVM on the machine.</para>
    </listitem>
    <listitem>
      <para>In part six we will show how to use ProActive groups to monitor several machines
      at the same time.</para>
    </listitem>
	<listitem>
		<para>In part seven will show how to expose an active object as a web service. </para>
	</listitem>

   <listitem><para>
   		The next parts are dedicate to showing how we can transform a sequential application that finds a number of primes
   		into a distributed application. In this part we will also use the ProActive Master-Worker API. 
   </para></listitem>
  </itemizedlist>
	<para>
		All the exercises in this chapter are available as an Eclipse workspace. 
		The Eclipse environment is set up to run each exercises as soon as 
		the needed code is inserted. The tasks needed for the examples to run properly are annotated with
		//TODO tags and show up under the Eclipse tasks list. 
	</para>
	
	<para> To further learn what is needed for the 
		running ProActive applications read <xref linkend="Installation"/>. 
	</para>	
	
	<section xml:id="SimpleCMA"><info><title> Simple Computation And Monitoring Agent</title></info>
		
	<para>
		Welcome to your first ProActive program! This is one of the simplest applications that can be
		written using ProActive. We will create an active object locally and get the state of 
		the JVM through it. Our application is composed of three classes with a client-server structure. 
	</para>
		<para>	
		The example illustrates the creation of an active object from the 
		<literal>CMAgent</literal> class that will be
		used by the <literal>Main</literal> class to retrieve the JVM state
		 for a machine and print it to the standard output.		
		The <literal>Main</literal> class corresponds to the client, and is
		 only a container for the <literal>main()</literal> method, while 
		the <literal>CMAgent</literal> class corresponds to the server and
		 its instance is an active object which provides a <literal>getCurrentState()</literal>
		method as a remote service.
	</para>		
	<para>
		To safely use the <literal>CMAgent</literal> class as an active object
		we have to meet three requirements.
	</para>
		<itemizedlist>
			<listitem><para><emphasis role="bold">no direct access to field variables</emphasis> - If
							<literal>public</literal> variables are used then the stub class generated from
							the original class may become decoupled from the original class. If a change is
							affected on the public field variable in the stub instance, the change will not be 
							 propagated to the the class instance from which the stub was generated. The safe
							 way to change variables is to set them as <literal>private</literal> and access
							 them through <literal>public get/set</literal> methods.   </para></listitem>
			
			<listitem>
			<para><emphasis role="bold">provide a no-argument and preferably an empty constructor</emphasis> - A 
							no-argument constructor is necessary to create the stub class needed for communication.
							A stub cannot be created if there are only constructors with arguments since the 
							stub is only meant to abstract the communication from the active objects. 
							
							If there is no constructor defined, the Java compiler
							will automatically create a no-argument constructor that initializes all instance variables
							to the default value. However, if there is an already defined constructor with arguments 
							then no default no-argument constructor will be created by the compiler. In this case
							the definition of a no-argument constructor is mandatory for stub creation. The safest way is
							to always define a no-argument constructor.
							Also, the constructor should be empty so that on stub creation no 
							initialization is done on the stub.    
						</para>
			</listitem>
			<listitem><para><emphasis role="bold">provide remote functionalities as public methods with return types that can be subclassed and are serializable</emphasis> - Since
			the stub is created through inheritance, the only methods it can use for communication are
			the inherited public methods from the superclass. The return types of the methods have to be 
			 subclassable and therefore not final. ProActive provides several wrappers for Java types
			 that are final.The example uses the <literal>StringWrapper</literal> class in order to provide a wrapper for the 
			final <literal>String</literal> class.  Since ProActive uses a proxy mechanism and
			 the <literal>String</literal> class is final, it’s not
			possible to subclass a String and to perform asynchronous calls.	
			ProActive provides several wrappers for final classes: <literal>StringWrapper, BooleanWrapper, 
			IntegerWrapper, DoubleWrapper</literal> and <literal>FloatWrapper</literal>.
			 These have to be used in
			replacement of <literal>String, Boolean, Integer, Double</literal> and <literal>Float</literal>
			in classes which will be active objects. If you don’t use wrappers, method calls will be synchronous.
			In our case the return type is <literal>State</literal> which is not final.
			</para>	
			
			
			</listitem>
		</itemizedlist>	
	
	  <section><info><title> Classes Used </title></info>
		
		<itemizedlist><info><title>ProActive</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.api.PAActiveObject</literal> - used to create an instance of an active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.core.node.NodeException</literal> - used to catch the exceptions that the creation of the Node might throw</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.ActiveObjectCreationException</literal> - used to catch the exceptions that the creation of the active object might throw </para></listitem>
		</itemizedlist>
		<itemizedlist><info><title>Other</title></info>
			
				<listitem><para><literal>java.io.Serializable</literal> - used to make the <literal>State</literal> object serializable so it can 
				be sent across the network    </para></listitem>
				<listitem><para><literal>java.lang.management.ManagementFactory</literal> - used to get various information about the machine the active object is running on </para></listitem> 
				<listitem><para><literal>java.net.InetAddress</literal> - used to get the address of the active object is running on </para></listitem>
				<listitem><para><literal>java.net.UnknownHostException</literal>  - used to catch the exceptions that might be thrown when requesting host information </para></listitem>
				<listitem><para><literal>java.util.Date</literal> -  used to get the a time for the requested state </para></listitem>  
		</itemizedlist>
		</section>
  	<section><info><title>CMA Architecture and Skeleton Code </title></info>
		
	<figure><info><title> Client-Server architecture - the <literal>Main</literal> class acts as 
	a client and uses the <literal>CMAgent</literal> class as a server</title></info> 
		  <mediaobject>
          <imageobject>
            <imagedata scalefit="1" width="100%" contentdepth="100%"   fileref="guided_tour/pics/cma/simpleCMA.jpg" format="JPG" />
          </imageobject>
        </mediaobject>
      </figure>
	<para>For our Monitoring agent we use three classes. The first two classes are regular Java objects.
	The first class is <literal>State</literal> which we use to get some information on the JVM the 
	object is located on. This object will be use as return value for the <literal>getCurrentState()</literal>
	method in the <literal>CMAgent</literal> class.
	</para>
	
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/state_full.snip"/></textobject></programlisting>
	
	<para>
	
		The Monitoring agent class is a regular Java class  
	</para>	
	 <programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/fullCMA.snip"/></textobject></programlisting>
	<para>with only one method.</para>
	
	<para>
	
	 For this simple exercise we only need to add ProActive code in the Main class
	 where we instantiate the active object. 
	  </para>
	
	<programlisting xml:lang="java"><textobject><textdata fileref="guided_tour/code_snippets/CMAgent/simple_CMA_skeleton.txt"/></textobject></programlisting>
	
	</section>
	<section><info><title>Proposed Work</title></info>
		
		<para>
			You  can find the skeleton code for the exercise in the Eclipse exercises workspace under the name 
			<literal>1. SimpleCMAgent</literal>.
		</para>
	<orderedlist>
			<listitem><para>Create an active object using the <literal>org.objectweb.proactive.api.PAActiveObject.newActive(...)</literal> 
				static method.</para></listitem>
			<listitem><para>Call the  <literal>getCurrentState()</literal> method and display the results.</para></listitem>
			<listitem><para>Since the active object has a never ending thread we need to make an explicit call in order
			to stop it. Use <literal> PAActiveObject.terminateActiveObject(...)</literal> to stop the
			active object.</para>
			</listitem>
			<listitem><para>
				Remove the <literal>Serializable</literal> from the class <literal>State</literal> and explain the results when running the example.
				</para>
			</listitem>
		</orderedlist>
	</section>
	
	<section><info><title> Solutions and Full Code </title></info>
		
	
		<para>We will now show how to create the server object. For now, we want the
		<literal> CMAgent</literal> active object 
		 to be created on the current Node (we will see later how to distribute the program). To create an instance of
		  a remotely accessible object we must use the <literal>ProActive.newActive(...)</literal> static method. We pass
		  as an argument the name of the class to be instantiated  and arguments for the constructor of the class.
		  In our case <literal>CMAgent</literal> does not need any arguments for the constructor and therefore we use <literal>null </literal>. 
		  <programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_instatiation.snip"/></textobject></programlisting>
		</para>
	<para>
		Invoking a method on a remote active object is transparent and is similar 
		to  invoking a method on
		a local object of the same type. The user does not have to deal with catching exceptions
		related to the remote communication. The only modification brought to the code by ProActive
		is during the active objects creation. All the rest of the code can remain unmodified, 
		fostering software reuse. </para>
		
		<para>
			To invoke the <literal>getCurrentState()</literal> method  we execute:
		</para>
			
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_call.snip"/></textobject></programlisting>

	<para>To stop the active object we call the <literal> PAActiveObject.terminateActiveObject(ao, false)</literal> method. The 
	<literal>false</literal> argument is used in order to call the terminate method as a regular request. If the
	argument is <literal>true</literal> the method call is served as an immediate service (executed as soon as the
	current executing request is completed regardless of how many other requests might be waiting)
	and synchronously (the caller thread blocks until it receives the results). </para>
	
		<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_terminate_call.snip"/></textobject></programlisting>
	
	<para>Passive objects in ProActive are always passed by deep copy when returned as a method results.
	If the object State does not implement <literal>Serializable</literal> ProActive will not be able to 
	to make a deep copy of the object and will throw an exception. </para>
	
	<para> The full code of the <literal>Main</literal> class is the following. </para>
	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/CMA_Main.snip"/></textobject></programlisting>
	
	</section>
	</section>

  <section xml:id="Active_Object_LifeCycle"><info><title>Active Objects Lifecycle: Using InitActive and EndActive</title></info>
    

    <para>Active objects, as their name indicates, have an activity of their
    own (an internal thread). By default the active object steps through
    the constructor, the <literal>initActivity</literal>, the <literal>runActivity</literal>,
     and when the <literal>terminate</literal> method is called on
    the <literal>Body</literal> of the active object through the <literal>endActivity</literal> method.
    It is possible to control the initialization, running, and ending phase of this
    thread by implementing three interfaces: <literal>InitActive</literal>, <literal>
    RunActive</literal>,and <literal>EndActive</literal>.These interfaces define the
    <literal>initActivity</literal>, <literal>runActivity</literal> and <literal>endActivity</literal>
    methods. One of the reasons for using <literal>initActivity</literal>
    method is the presence of the empty constructor in an active object. The <literal>initActivity</literal>
    method is automatically called on the creation of an active object in order to set up the 
    object without using the constructor. The <literal>runActivity</literal> method allows the user
    to control the active object request queue. By implementing the <literal>EndActive</literal> interface is also possible to 
    do clean up before the active object thread is stopped. </para>


    <para>The following example will help you to understand how and when you
    can initialize and clean the activity. The example will implement the <literal>InitActive</literal>, <literal>RunActive</literal>,
     and
    <literal>EndActive</literal> interfaces. However <literal>RunActive</literal> has a more complex structure than
    it is presented here. To understand how to use <literal>EndActive</literal>
    <literal>RunActive</literal> interface read <xref linkend="ActiveObjectCreation"/> </para>

	  <section><info><title> Classes Used </title></info>
		
		
		<itemizedlist><info><title>New classes used</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.Body</literal> - used to access the body of the active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.Service</literal> - used to access the queue of the active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.InitActive</literal> - used for defining the <literal>initActivity(Body body)</literal> method, which is run at active object initialization</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.EndActive</literal> - used for defining the <literal>endActivity(Body body)</literal> method, which is run at active object destruction </para></listitem>
			<listitem><para><literal>org.objectweb.proactive.RunActive</literal> - used for defining the <literal>runActivity(Body body)</literal> method, which manages the queue of requests</para></listitem>
			<listitem><para><literal> org.objectweb.proactive.core.util.wrapper.LongWrapper</literal> - used to wrap the <literal>Long</literal> return type</para></listitem>
		</itemizedlist>

		<itemizedlist><info><title>Previously used classes</title></info>
			
			<listitem><para><literal>org.objectweb.proactive.api.PAActiveObject</literal> - used to create an instance of an active object</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.core.node.NodeException</literal> - used to catch the exceptions that the creation of the Node might throw</para></listitem>
			<listitem><para><literal>org.objectweb.proactive.ActiveObjectCreationException</literal> - used to catch the exceptions that the creation of the active object might throw </para></listitem>
			<listitem><para><literal>java.io.Serializable</literal> - used to make the <literal>State</literal> object serializable so it can 
				be sent across the network  </para></listitem>
				<listitem><para><literal>java.lang.management.ManagementFactory</literal> - used to get various information about the machine the active object is running on </para></listitem> 
				<listitem><para><literal>java.net.InetAddress</literal> - used to get the address of the active object is running on </para></listitem>
				<listitem><para><literal>java.net.UnknownHostException</literal>  - used to catch the exceptions that might be thrown when requesting host information </para></listitem>
				<listitem><para><literal>java.util.Date</literal> -  used to get the a time for the requested state </para></listitem>  
		</itemizedlist>
		
	</section>

    <section><info><title>Initialized CMA Architecture and Skeleton Code</title></info>
      

      <para>The <literal>CMAgentInitialized</literal> class extends the
      <literal> CMAgent </literal>class from the previous example, and implements
      the interfaces <literal>InitActive</literal> and <literal>EndActive</literal>.
      It acts as a server for the <literal>Main</literal> class.</para>

      <para><figure><info><title> CMA Architecture and Skeleton Code Using intialization</title></info>
      		 
          <mediaobject>
            <imageobject>
              <imagedata scalefit="1" width="100%" contentdepth="100%"    fileref="guided_tour/pics/cma/initCMA.jpg" format="JPG" />
            </imageobject>
          </mediaobject>
        </figure></para>
    
    
    <para>
    	To implement the application we will create a class that inherits from the 
    	<literal>CMAgent</literal> class and implements the <literal>InitActive</literal>, <literal>RunActive</literal>, and <literal>EndActive</literal> 
    	interfaces. 
	 	<programlisting xml:lang="java"><textobject><textdata fileref="guided_tour/code_snippets/CMAgent/init_CMA_skeleton.txt"/></textobject></programlisting>
    </para>
    <para>
    	By default an active object has a never ending thread that should be stopped when the object is 
    	not needed anymore. The method <literal>terminate()</literal> serves the purpose of destroying the 
    	object. However, if an explicit call to terminate the object is not made, ProActive has its own
    	distributed garbage collection system that is able to decide when an active object can be destroyed. 
    </para>
    <para>
    	The <literal>Main</literal> is similar with the one in the previous example.
    	We will change the object created from <literal>CMAAgent</literal> to 
    	<literal>CMAAgentInitialized</literal> and also we will call the <literal>terminate() </literal> method to 
    	destroy the object.
    </para>
    
    </section>

    	<section><info><title>Proposed Work</title></info>
		
		<para>
			You  can find the skeleton code for the exercise in the Eclipse exercises workspace under the name 
			<literal>2. InitializedCMAgent</literal>.
		</para>
		<orderedlist>


			<listitem><para>Use <literal>initActivity(Body body)</literal> to print information 
			about the start location of the active object and record the start time.</para></listitem>
			<listitem><para>Use <literal>endActivity(Body body)</literal> to print information about
			 the stop location of the active object, calculate the running time, 
			 and print the number of requests served.</para></listitem>

			<listitem><para>Calculate the last request duration
			 and count the requests using <literal>org.objectweb.proactive.Service.waitForRequest()</literal> 
			and <literal>org.objectweb.proactive.Service.serveOldest()</literal> </para></listitem>
			<listitem><para>Use <literal>org.objectweb.proactive.core.util.wrapper.LongWrapper</literal> 
			to return a wrapped <literal>Long</literal> value.</para></listitem>
		</orderedlist>

	</section>
    
    <section><info><title>Solution and Full Code</title></info>
    	
    	<para>
    	We only need to extend the <literal>CMAgent</literal> class and implement the 
    	interfaces. In <literal>initActivity(Body body)</literal> we  use <literal>body.getName()</literal>
    	to get the name of the active object and <literal>body.getNodeUrl()</literal> to get the location.
    	In  <literal>endActivity(Body body)</literal> we also use <literal>body.getNodeUrl()</literal> to get the location. 
    	</para>
    	<programlisting xml:lang="java"><textobject><textdata fileref="./automatic_snippets/cma_init_full.snip"/></textobject></programlisting>


    </section>
  
  
  </section>
  <section xml:id="deployment_guide_CMA"><info><title>Application Deployment</title></info>
  	
  	<para>
  		In the previous example the applications were deployed inside
  		the same JVM. This section will focus on showing how to deploy
  		the application on different nodes using deployment
  		descriptors.
  	</para>
  	<section><info><title>Deployment Related Concepts</title></info>
  		
  		<para>
  			A first principle is to fully eliminate from the source
  			code the following elements:
  			<itemizedlist>
  				<listitem>
  					<para>machine names</para>
  				</listitem>
  				<listitem>
  					<para>creation protocols</para>
  				</listitem>
  				<listitem>
  					<para>registry lookup protocols</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			The goal is to deploy any application anywhere without
  			changing the source code. For instance, we must be able to
  			use various protocols, rsh, ssh, Globus, LSF, etc., for
  			the creation of the JVMs needed by the application. In the
  			same manner, the discovery of existing resources or the
  			registration of the ones created by the application can be
  			done with various protocols such as RMIregistry, Globus
  			etc. Therefore, we see that the creation, registration and
  			discovery of resources have to be done externally to the
  			application.
  		</para>
  		<para>
  			A second key principle is the capability to abstractly
  			describe an application, or part of it, in terms of its
  			conceptual activities. The description should indicate the
  			various parallel or distributed entities in the program.
  			For instance, an application that is designed to use three
  			interactive visualization nodes, a node to capture input
  			from a physics experiment, and a simulation engine
  			designed to run on a cluster of machines should somewhere
  			clearly advertise this information.
  		</para>
  		<para>
  			Now, one should note that the abstract description of an
  			application and the way to deploy it are not independent
  			piece of information. If for example, we have 
  			a simulation engine, it might register in a specific
  			registry protocol, and if so, the other entities of the
  			computation might have to use that lookup protocol to bind
  			to the engine. Moreover, one part of the program can just
  			lookup for the engine (assuming it is started
  			independently), or explicitly create the engine itself. To
  			summarize, in order to abstract away the underlying
  			execution platform, and to allow a source-independent
  			deployment, a framework has to provide the following
  			elements:
  			<itemizedlist>
  				<listitem>
  					<para>
  						an abstract description of the distributed
  						entities of a parallel program or component,
  					</para>
  				</listitem>
  				<listitem>
  					<para>
  						an external mapping of those entities to real
  						machines, using actual creation, registry, and
  						lookup protocols.
  					</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			To reach that goal, the programming model relies on the
  			specific notion of Virtual Nodes (VNs):
  			<itemizedlist>
  				<listitem>
  					<para>
  						a VN is identified as a name (a simple string)
  					</para>
  				</listitem>
  				<listitem>
  					<para>a VN is used in a program source</para>
  				</listitem>
  				<listitem>
  					<para>
  						a VN is defined and configured in a deployment
  						descriptor (XML)
  					</para>
  				</listitem>
  				<listitem>
  					<para>
  						a VN, after activation, is mapped to one or to
  						a set of actual ProActive Nodes
  					</para>
  				</listitem>
  			</itemizedlist>
  		</para>
  		<para>
  			Of course, distributed entities (Active Objects), are
  			created on Nodes, not on Virtual Nodes. There is a strong
  			need for both Nodes and Virtual Nodes. Virtual Nodes are a
  			much richer abstraction, as they provide mechanisms such
  			as set or cyclic mapping. Another key aspect is the
  			capability to describe and trigger the mapping of a single
  			VN that generates the allocation of several JVMs. This is
  			critical if we want to get at once machines from a cluster
  			of PCs managed through Globus or LSF. It is even more
  			critical in a Grid application, when trying to achieve the
  			co-allocation of machines from several clusters across
  			several continents.
  		</para>
  		<para>
  			Moreover, a Virtual Node is a concept of a distributed
  			program or component, while a Node is actually a
  			deployment concept: it is an object that lives in a JVM,
  			hosting Active Objects. There is of course a
  			correspondence between Virtual Nodes and Nodes: the
  			function created by the deployment, the mapping. This
  			mapping can be specified in an XML descriptor. By
  			definition, the following operations can be configured in
  			such a deployment descriptor:
  			<itemizedlist>
  				<listitem>
  					<para>
  						the mapping of VNs to Nodes and to JVMs
  					</para>
  				</listitem>
  				<listitem>
  					<para>the way to create or to acquire JVMs</para>
  				</listitem>
  				<listitem>
  					<para>the way to register or to lookup VNs</para>
  				</listitem>
  			</itemizedlist>

  		</para>
  	</section>

  	<section><info><title>Deployment Descriptor File</title></info>
  		
  		<para>
  			The deployment descriptor is an <literal>XML</literal> file containing
  			information on the properties listed above. We will use a
  			simple <literal>XML</literal> file to deploy the monitoring agent on a
  			remote machine. The deployment <literal>XML</literal> file is composed of several
  			parts, each with different options. For our example we
  			will use a simple version. To find out more about
  			deployment and deployment descriptors read
  			<xref linkend="XML_Descriptors"/>
  			.
  		</para>
  		<para>
  			The document uses the
  			<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www-sop.inria.fr/oasis/ProActive/schemas/deployment/3.3/deployment.xsd">
  				XML Schema
  			</link>
  			present at the Oasis website.
  		</para>
  		<para>
  			To avoid mistakes when building <literal>XML</literal> descriptors, ProActive
  			provides an <literal>XML</literal> Schema called DescriptorSchema.xsd. To
  			validate your file against this schema, the following line
  			must be put at the top of the <literal>XML</literal> document.
  		</para>

  		<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/schema_location.txt"/></textobject></programlisting>
  		<para>
  			The <literal>XML</literal> file has a section for defining variables needed
  			later in the document. In our case, we define the
  			location of the ProActive and Java installations on the
  			local and remote machine. To start the JVM and use
  			ProActive on the remote machine, we need to define the
  			location of the Java and ProActive files. This can be done
  			by specifying the paths in the infrastructure section of
  			the deployment descriptor or by setting the <literal>CLASSPATH</literal> and
  			<literal>JAVA_HOME</literal> variables as described in
  			<xref linkend="Installation"/>
  			.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/variable_definition.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			Next, we define the virtual nodes that will be used. In
  			our case we define a node that can contain several JVMs by
  			setting the <literal>multiple</literal> property.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/component_definition.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			The deployment part of the <literal>XML</literal> file specifies how the JVMs
  			are started and mapped on the Virtual Nodes It has two
  			parts one dealing with the mapping of the JVMs to the
  			Virtual Nodes and another related to how the JVMs are
  			created. In our case we map one JVM to the remote node and
  			define a process reference that will be used later in the
  			file (infrastructure section) to describe how the JVM is
  			started.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/jvms.txt"/></textobject></programlisting>
  		</para>
  		<para>
  			Next is the infrastructure part that defines the paths to
  			the files needed, the hosts on which the JVMs are deployed
  			and which protocols are used for communication.

  			The process definition with the id
  			<literal>genericRemoteJVM</literal>
  			is necessary to tell the JVM machine how to start a node
  			on the machine that has a reference to it (
  			<literal>processReference</literal>
  			). It will use the paths provided to locate the Java and
  			ProActive files on the remote machine. Here we are using
  			<literal>rsh</literal> to start the JVM but several other protocols can be
  			used as described in
  			<xref linkend="XML_Descriptors"/>
  			.
  			<programlisting xml:lang="xml"><textobject><textdata fileref="code_snippets/deployment_descriptor/infrastructure.txt"/></textobject></programlisting>
  			<para>The following figure ilustrates a simplified view of the deployment process. The ProActive application loads the deployment descriptor and
  			deploys on the remote machine according to the settings in the descriptor. Although the process behind the deployment is fairly complicated it is
  			made seamless by ProActive. In the application we only need to specify the deployment descriptor and tell ProActive to start the virtual nodes, nodes and 
  			active objects. The communication details are handled by ProActive according to the descriptor. </para>
  			
  				<figure><info><title> Deployment process </title></info> 
		  <mediaobject>
          <imageobject>
            <imagedata scalefit="1" width="100%" contentdepth="100%"   fileref="images/deployment_process.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
  			
  		</para>
  		</section>
  		</section>
  		<section><info><title> Remote Monitoring Agent</title></info>
  			
  			<para>
  				In this part of the tutorial we will see how to start a monitoring agent on a remote machine
{'fraction_non_alphanumeric': 0.0863393506370333, 'fraction_numerical': 0.0009010148272264551, 'mean_word_length': 3.66506894771772, 'pattern_counts': {'":': 0, '<': 1584, '<?xml version=': 0, '>': 1584, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 50}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4547859', 'n_tokens_mistral': 19175, 'n_tokens_neox': 17198, 'n_words': 6864}