<?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.8.GA or higher), should download the <emphasis role="bold">jbossesb-4.8.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 examples.</listitem>
       			<listitem>RiftSaw, 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.0.Final, then you will need to drop the database schema
       		due to changes in the ODE db schema for version 1.3.4. This can be achieved using the scripts in the
       		<filename>${riftsaw}/db/sql</filename> folder, or configure the jdbc properties file in <filename>${riftsaw}/db/jdbc</filename> and running:
       		</para>
       		<para>
       		ant -D{database} drop.riftsaw.schema
       		</para>
       		<para>
       		from the <filename>${riftsaw}/db</filename> folder.
       		</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>
       			   	<warning>
       			   	<para>
       			   	If you intend to install the jbossesb, it must be deployed to the application server
       			   	before riftsaw.
       			   	</para>
       			   	</warning>
       			</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>
								<para>
								From the install folder, run:
								</para>
								<para>
								<command>ant deploy -Ddatabase=... -Dws.stack=... -Dws.version=...</command>
								</para>
								<para>
								to deploy RiftSaw to JBossAS, specifying a database and mandating the upgrade of the web service stack for JBossAS. 
								The list of available databases, and how they should be configured, is explained in the next sub-section;
								the list of options for update of the web service stack is discussed in the one following it.
								</para>
								<note>
								<para>
								  Please note that RiftSaw should not be deployed while JBoss AS is running.
								</para>
								</note>
							</listitem>
						</itemizedlist>
					</para>
				</listitem>
     		</orderedlist>
			
			<para>
			To de-install the RiftSaw distribution,
			</para>	   
     		<orderedlist>
				<listitem>
					Uninstall the RiftSaw distribution
					<para>
						<itemizedlist>
							<listitem>
								<para>
								From the install folder, run:
								</para>
								<para>
								<command>ant undeploy -Ddatabase=....</command>
								</para>
								<para>
								to remove
								RiftSaw from JBossAS. The database option should specify the same value used
								during installation of RiftSaw.
								</para>
							</listitem>
						</itemizedlist>
					</para>
				</listitem>
     		</orderedlist>
     		
     		<para>
     		 <tip>
			 When deploying riftsaw with the <emphasis>hsql</emphasis> database option, 
			 the installation script will copy the h2 library into JBoss AS server.
			 However, when riftsaw is undeployed, this library will not be removed.
			 This is because JBoss ESB and jBPM also use the h2 database, and therefore
			 removing the library may inadvertantly impact those projects.
			 If you wish to remove the h2 library, then please go to the
			 <filename>$JBossAS/server/${config}/lib</filename> folder and 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>
     			Upgrading the web service stack for JBoss AS is now required. The following command:
     			<command>ant deploy -Ddatabase=... -Dws.stack=... -Dws.version=...</command>
     			will help you download the web service stack, and then upgrade it for JBoss AS, while deploying RiftSaw.
     			<itemizedlist>
     				<listitem>
     				Available ws.stack options: 'native' or 'cxf'
     				</listitem>
     				<listitem>
     				Available ws.version options: '3.2.1.GA' or higher
     				</listitem>
     			</itemizedlist>
     			
     			</para>
     		</section>
       </section>

</chapter>
