<?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="installation">
  <title>Installation</title>   
       
       <section>
       		<title> Overview </title>
       		<para> 
       		This chapter provides details of the pre-requisites for using the RiftSaw BPEL project, and how
       		to install the engine into a JBossAS environment.
       		</para>
       		
       		<para>
       		The examples distributed with RiftSaw are split into two categories, quickstarts that are pure BPEL
       		that can run directly in the JBossAS server, and ESB based examples that require JBossESB. If you only
       		want to use the pure BPEL examples, then JBossESB will not be required.
       		</para>
       </section>
       
       <section>
       		<title>Prerequisites</title>
       		<orderedlist>
       			<listitem>JBossAS (version 5.1.0.GA or higher) <emphasis role="bold">jdk6</emphasis> version, available from 
       			<ulink url="http://www.jboss.org/jbossas">http://www.jboss.org/jbossas</ulink>, and please upgrade the web
       			service stack to version 3.2.2.GA, as described in the following 'Upgrade web service for JBoss AS' section.</listitem>
       			<listitem>JBossESB (version 4.7.GA or higher), should download the <emphasis role="bold">jbossesb-4.7.GA.zip</emphasis>,
       			available from <ulink url="http://www.jboss.org/jbossesb">http://www.jboss.org/jbossesb</ulink>.
       			This is only required to run the ESB/BPEL example.</listitem>
       			<listitem>RiftSaw (version 2.0 or higher), available from
       			<ulink url="http://www.jboss.org/riftsaw">http://www.jboss.org/riftsaw</ulink></listitem>
       			<listitem>
       				Ant, available from <ulink url="http://ant.apache.org/">http://ant.apache.org</ulink>
       			</listitem>
       		</orderedlist>
       </section>
       
       <section>
       		<title>Installation Instructions</title>
       		
       		<note>
       		<para>
       		If you have previously installed RiftSaw-2.0-M1, then you will need to undeploy this version using the
       		<emphasis>ant undeploy</emphasis> command from the <filename>install</filename> folder of the M1
       		distribution. This is due to database schema changes.
       		</para>
       		</note>
       		
       		<orderedlist>
       			<listitem> 
       				Install JBossAS
	       			<para>
	       			Unpack the JBossAS installation into the required location.
	       			</para>
       			</listitem>
       			
       			<listitem>
       			   	Install JBossESB
       			   	<para>
       			   	This is only required if you want to run the ESB/BPEL examples.
       			   	</para>
       			   	<para>
       			   	Unpack the JBossESB installation into a location alongside the JBossAS installation. 
       			   	Then follow the instructions in the JBossESB installation (install/readme.txt), to deploy 
       			   	JBossESB into the JBossAS environment.
       			   	</para>
       			</listitem>
				   
				<listitem>
					Install the RiftSaw distribution
					<para>
					Unpack the RiftSaw distribution into a location alongside the JBossAS installation.
					</para>
					<para>
						<itemizedlist>
							<listitem>
								Edit the <emphasis role="bold">install/deployment.properties</emphasis> file to update
								the JBossAS and JBossESB location settings.
							</listitem>
							<listitem>
								From the install folder, run: <command>ant deploy -Ddatabase=....</command> to deploy
								RiftSaw to JBossAS. The list of available databases, and how they should be configured,
								is explained in the following sub-section.
							</listitem>
							<listitem>
								If JBossESB has been installed, then run: <command>ant deploy-esb-examples</command> to
								install the BPEL/ESB examples into the JBossESB samples/quickstart folder.
							</listitem>
						</itemizedlist>
					</para>
				</listitem>
     		</orderedlist>
			
			<para>
			To de-install the RiftSaw distribution,
			</para>	   
     		<orderedlist>
				<listitem>
					Uninstall the RiftSaw distribution
					<para>
						<itemizedlist>
							<listitem>
								From the install folder, run: <command>ant undeploy -Ddatabase=....</command> to remove
								RiftSaw from JBossAS. The database option should specify the same value used
								during installation of RiftSaw.
							</listitem>
							<listitem>
								If JBossESB has been installed, then run: <command>ant undeploy-esb-examples</command> to
								remove the BPEL/ESB examples from the JBossESB samples/quickstart folder.
							</listitem>
						</itemizedlist>
					</para>
				</listitem>
     		</orderedlist>
     		
     		<para>
     		 <tip>
			 In the Hsql database environment, if you install the RiftSaw, we will copy the h2 library into JBoss AS server.
			 But when you undeploy the RiftSaw, we won't delete it. The reason for doing this is because the JBoss ESB or jBPM will use the h2 database also,
			 if we remove the h2 database in the undeployment process, we might cause JBoss ESB or jBPM start failed.
			 So if you want to remove the h2 database, please go to the $JBossAS/server/${config} (like default)/lib, and then remove it manually.
     		 </tip>
     		</para>
     		
     		<section>
     			<title>Available databases and how to configure them</title>
     			
     			<para>
     			The following "in-memory" databases are available. If just evaluating the capabilities
     			of RiftSaw, it is recommended that one of these options is used to reduce the
     			time taken to get RiftSaw up and running.
     			</para>
     			
     			<orderedlist>
    				<listitem>hsql</listitem>
     			</orderedlist>
     			
     			<para>
     			Other databases available, that require further configuration details, include:
     			</para>

     			<orderedlist>
     				<listitem>mysql</listitem>
    				<listitem>postgres</listitem>
    				<listitem>oracle</listitem>
    				<listitem>sqlserver</listitem>
     			</orderedlist>
     			
     			<para>
     			The configuration properties for these database options can be found in the
     			<filename>${RiftSaw}/db/jdbc</filename> folder. These properties need to be
     			specified before executing the <command>ant deploy -Ddatabase=...</command>
				command.
     			</para>
     		</section>
     		
     		<section>
     			<title>Upgrade web service for JBoss AS</title>
     			<para>
     			If you want to upgrade the web service stack for JBoss AS, in the ${RiftSaw}/install folder, just run command as following:
     			<command>ant deploy -Ddatabase=... -Dws.stack=... -Dws.version=...</command>
     			It will help you download the web service stack, and then upgrade it for JBoss AS.
     			<itemizedlist>
     				<listitem>
     				Available ws.stack options are: 'native', 'cxf', 'metro'.
     				</listitem>
     				<listitem>
     				Available ws.version options are: '3.2.1.GA', '3.2.2.GA'
     				</listitem>
     			</itemizedlist>
     			
     			</para>
     		</section>
       </section>

</chapter>
