<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="deploy">
  <title>Deploying BPEL Processes</title>   
       
       <section>
       		<title>Overview</title>

       		<para>
       		This section outlines the mechanisms that can be used to deploy a BPEL process to
       		RiftSaw BPEL engine running within a JBoss AS server.
       		</para>
       		
       </section>
  
       <section>
       		<title>Direct deployment to JBossAS server</title>

       		<para>
       		The direct deployment approach is demonstrated using an <emphasis>Ant</emphasis> script 
       		in each of the quickstart examples. For example,
       		</para>
       		
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
	<!-- Import the base Ant build script... -->
	<property file="../../../install/deployment.properties" />
	
	<property name="version" value="1" />
	
	<property name="server.dir" value="${org.jboss.as.home}/server/${org.jboss.as.config}"/>
	<property name="conf.dir" value="${server.dir}/conf"/>
	<property name="deploy.dir" value="${server.dir}/deploy"/>
	<property name="server.lib.dir" value="${server.dir}/lib"/>

	<property name="sample.jar.name" value="${ant.project.name}-${version}.jar" />
	
	<target name="deploy">
		<echo>Deploy ${ant.project.name}</echo>
		<jar basedir="bpel" destfile="${deploy.dir}/${sample.jar.name}" />
	</target> 
 
	<target name="undeploy">
		<echo>Undeploy ${ant.project.name}</echo>
		<delete file="${deploy.dir}/${sample.jar.name}" />
	</target>  
 				 ]]></programlisting>
			</informalexample>

			<para>
			This excerpt from the <emphasis>Ant</emphasis> build file for the <emphasis>hello_world</emphasis>
			quickstart example shows that deploying a RiftSaw BPEL process using <emphasis>Ant</emphasis>
			is very straightforward. The main points of interest are:
			</para>

       		<itemizedlist>
       			<listitem>
       			It is necessary to identify the location of the JBoss AS server in which
       			the BPEL process will be deployed. This is achieved in this example by
       			referring to the <filename>deployment.properties</filename> file that
       			has been configured in the RiftSaw distribution (install folder).
       			</listitem>
       			<listitem>
       			If a versioned approach is being used, so that multiple versions of the
       			same BPEL process may be deployed at one time, then the name of the
       			archive (jar) containing the BPEL process (and associated artifacts)
       			has a version number suffix. This would need to be manually incremented
       			for each distinct version of the BPEL process being deployed.
       			      			       		
	       		<warning>
	       		<para>
	       		Currently the version must be specified as a single integer value. Non-numeric values, such
	       		as versions expressed in a major.minor.incremental (maven style), will result in an
	       		exception when deployed to the server.
	       		</para>
	       		</warning>
       			
       			</listitem>
      			<listitem>
       			The next step is to define the <emphasis>deploy</emphasis> target, which
       			will create the BPEL process archive, using the contents of the bpel
       			sub-folder in this case, and store it within the JBoss AS
       			server's <filename>deploy</filename> folder.
       			</listitem>
       			<listitem>
       			The final step is to define the <emphasis>undeploy</emphasis> target,
       			which simply removes the BPEL process archive from the JBoss AS
       			server's <filename>deploy</filename> folder.
       			</listitem>
       		</itemizedlist>
			       		
		</section>
		
       <section>
       		<title>Eclipse based Deployment</title>

			<para>
			This section will explain how to deploy an Eclipse BPEL project to the RiftSaw BPEL engine running
			in a JBossAS server.
			</para>
			
			<para>
			The first step is to create or import the Eclipse BPEL project. In this case we are going to
			import an existing project from the <filename>${RiftSaw}/samples/quickstart/hello_world</filename>
			folder. This can be achieved by selecting the <emphasis>Import ...</emphasis> menu item associated
			with the lefthand navigator panel in Eclipse, and then select the
			<emphasis>General->Existing Projects into Workspace</emphasis> entry and press the
			<emphasis>Next</emphasis> button.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseImportExistingProjectsIntoWorkspace.png" align="center" width="4in" />
			</imageobject>
			
			<para>
			Then press the <emphasis>Browse</emphasis> button and navigate to the
			<filename>hello_world</filename> quickstart folder. Once located, press the <emphasis>Finish</emphasis>
			button.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseImportHelloWorld.png" align="center" width="4in" />
			</imageobject>
			
			<para>
			Once the project has been imported, you can inspect the contents, such as the BPEL process
			and WSDL description.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseHelloWorldProject.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			The next step is to create a server configuration for the JBoss AS environment in which the
			RiftSaw BPEL engine has previously been installed. From the Eclipse <emphasis>Java EE</emphasis>
			perspective, the <emphasis>Server</emphasis> tab should be visible in the lower region of the
			Eclipse window. If this view is not present, then go to the
			<emphasis>Window->Show Views->Servers</emphasis> menu item to open the view explicitly.
			</para>
			
			<para>
			In the <emphasis>Servers</emphasis> view, right click and select the <emphasis>New->Server</emphasis>
			menu item.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseNewServer.png" align="center" width="4in" />
			</imageobject>
			
			<para>
			Select the appropriate JBoss AS version, and then press <emphasis>Finish</emphasis>.
			</para>
			
			<para>
			Before being able to deploy an example, we should start the new server. This can be achieved
			by right clicking on the server in the <emphasis>Servers</emphasis> tab, and selecting the
			<emphasis>Start</emphasis> menu item. The output from the server will be displayed in the
			<emphasis>Console</emphasis> tab.
			</para>
			
			<para>
			Once the server has been started, right click on the server entry again, and select the
			<emphasis>Add and Remove ...</emphasis> menu item.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseAddRemoveProject.png" align="center" width="4in" />
			</imageobject>
			
			<para>
			Select the <emphasis>Quickstart_bpel_hello_world</emphasis> project, press the
			<emphasis>Add</emphasis> button and the press the <emphasis>Finish</emphasis>
			button. This will cause the project to be deployed to the server.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseHelloWorldDeployed.png" align="center" width="3in" />
			</imageobject>
			
			<para>
			Once the project has been deployed, it will show up as an entry below the server in the
			<emphasis>Servers</emphasis> tab.
			</para>
			
			<para>
			The final step is to test the deployed BPEL process. In this example, we can do this
			using the <emphasis>ant</emphasis> script provided with the quickstart sample. Right
			click on the <filename>build.xml</filename> file in the root folder of the project,
			and select the <emphasis>Run As->Ant Build ...</emphasis> menu item. NOTE: It is important
			to select the menu item with the <emphasis>"..."</emphasis>, as this provides a dialog
			window to enable you to select which <emphasis>ant target</emphasis> you wish to perform.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseSendHello.png" align="center" width="5in" />
			</imageobject>
			
			<para>
			Deselect the <emphasis>deploy</emphasis> target, and select the <emphasis>sendhello</emphasis>
			target, before pressing the <emphasis>Run</emphasis> button. This was send a test 'hello'
			message to the server, and then display the response in the <emphasis>Console</emphasis>
			tab.
			</para>
       		
			<imageobject>
				<imagedata fileref="images/EclipseHelloWorldResponse.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			If you now want to update the BPEL process, select the <emphasis>assignHelloMesg</emphasis>
			node in the diagram, and select the <emphasis>Properties</emphasis> view. On the left of the
			view is a vertical list of tabs. Select the <emphasis>Details</emphasis> tab. Then select the
			"Expression to Variable" from the list, and update the <emphasis>concat</emphasis> function's
			second parameter - for example to add 'UPDATED' to the text.
			</para>
			
			<imageobject>
				<imagedata fileref="images/EclipseHelloWorldUpdated.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			Once the update has been saved, go to the <emphasis>Server View</emphasis> and select the
			<emphasis>Full Publish</emphasis> option from the menu associated with the
			<emphasis>Quickstart_bpel_hello_world</emphasis> project. This will cause the project to be
			re-deployed to the RiftSaw server.
			</para>
			
			<para>
			The final step is to then re-run the 'sendhello' target within the <filename>build.xml</filename>
			file, to send a new request, and view the response. The response should now be modified
			according to the changes you made in the BPEL process.
			</para>
			
			<imageobject>
				<imagedata fileref="images/EclipseHelloWorldResponseUpdated.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			If you expand the deployed project node, in the <emphasis>Server View</emphasis>, you will see that
			both of the deployed versions are shown. The older version is retained as there may still be
			BPEL process instances using that version of the process. If you right-click on each of the child nodes, you will
			see that it is also possible to undeploy the specific versions. However, if you explicitly undeploy
			a version, then any remaining active process instances for that version will be terminated.
			</para>
			
			<para>
			You can then use the menu associated with the project, contained in the <emphasis>Server View</emphasis>, to undeploy
			the project (using the <emphasis>Add and Remove ...</emphasis> menu item) and finally use
			the menu associated with the server itself to <emphasis>Stop</emphasis> the server.
			</para>
       </section>
       
       <section>
       		<title>Changing Endpoint Configuration Properties</title>

       		<para>
       		Apache ODE provides the means to customise certain properties, associated with a
       		BPEL endpoint, by specifying the properties in a file with an extension of
       		<filename>.endpoint</filename>.
       		</para>
       		
       		<para>
       		For information on the properties that can be specified in this file,
       		please see the Apache ODE documentation, located at:
       		<ulink url="http://ode.apache.org/endpoint-configuration.html" >http://ode.apache.org/endpoint-configuration.html</ulink>.
       		</para>

			<note>
			<para>
			RiftSaw currently only supports the following properties:
			<emphasis>mex.timeout</emphasis>
			</para>
			</note>    		
       		
       		<para>
       		This section explains how to deploy these <filename>.endpoint</filename>
       		files as part of a RiftSaw deployment.
       		</para>
       		
       		<para>
       		Apache ODE supports two locations for finding these <filename>.endpoint</filename>
       		files. A 'global' configuration folder, which by default is
       		<filename>ode/WEB-INF/conf</filename>, and a process deployment specific
       		location, which is <filename>ode/WEB-INF/processes/$your_process</filename>.
       		Properties associated with the 'global' configuration override any property
       		values provided in the process specific location.
       		</para>
       		
       		<para>
       		RiftSaw currently does not support a 'global' configuration location, so it
       		will only obtain the configuration files from the deployed BPEL bundle. More
       		specifically, from the root location within the BPEL deployment unit, along
       		side the BPEL deployment descriptor.
       		</para>
       		
       		<para>
       		So, for example, if you place a file called <filename>test.endpoint</filename>
       		in the <filename>${RiftSaw}/samples/quickstart/hello_world/bpelContent</filename>
       		folder, with the following content:
       		</para>
       		
			<informalexample>
  				<programlisting>
	# 3 minutes
	mex.timeout=180000
  				</programlisting>
  			</informalexample>
  			
  			<para>
  			then once deployed, the helloworld example could wait up to a maximum of 3 minutes to respond.
  			To test this out, edit the <filename>hello_world.bpel</filename> and insert
  			a <emphasis>wait</emphasis> activity before the response - similar to the
  			following:
  			</para>
  			
			<informalexample>
  				<programlisting role="XML" ><![CDATA[
	<wait>
		<for>'PT150S'</for>
	</wait>
 				 ]]></programlisting>
			</informalexample>

			<para>
			This will wait 2 minutes 30 seconds before responding, which is 30 seconds
			more than the default timeout, but still within the new timeout period
			specified within the <filename>test.endpoint</filename> file. If you then
			wish to try forcing the timeout to occur, simply increase the wait
			duration to 3 minutes 30 seconds, and resubmit the test message using the
			<emphasis>ant sendhello</emphasis> command. 
			</para>
			 			
 	   </section>
</chapter>
