<?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="examples">
  <title>Examples</title>   
       
       <section>
       		<title>Overview</title>
       		<para> 
       		This chapter provides a getting started guide to the examples. Further information on the individual
       		examples can be found in the samples folder.
       		</para>
       		
       		<para>
       		If using the Eclipse BPEL editor, bundled with
       		<ulink url="http://www.jboss.org/tools">JBoss Tools</ulink>, then you can import
       		the quickstart samples as Eclipse BPEL projects, by selecting the <emphasis>import</emphasis>
       		menu item on the left navigation panel in Eclipse, and choosing the
       		<emphasis>General->Existing Projects into Workspace</emphasis> option. Then
       		select the individual sample you wish to import, or alternatively select the
       		<filename>${RiftSaw}/samples/quickstart</filename> folder to select multiple
       		(or all) samples for import. Please see the RiftSaw User Guide for information
       		on how to deploy the BPEL samples to the server.
       		</para>
       		
       		<para>
       		Before deploying any of the examples, you need to start the JBossAS
       		server and ensure that RiftSaw has been installed. This can be
       		achieved by testing whether the
       		<ulink url="http://localhost:8080/bpel-console">BPEL Console</ulink>
       		(as discussed in the User Guide) is available. 
       		</para>
       		
       </section>
       
       <section>
       		<title>Quickstart Examples - Hello World</title>
       		
       		<para>
       		The BPEL example we are going to try out is the simple
       		'hello world' example. This is located in the
       		<filename>${RiftSaw}/samples/quickstarts/hello_world</filename>
       		folder.
       		</para>
       		
       		<para>
       		The first step is to deploy the example to the running JBossAS
       		server. This is achieved using the following command:
       		</para>
       		
       		<code>
       		ant deploy
       		</code>
       		
       		<para>
       		When the ant script indicates that it has completed successfully,
       		the next step is to invoke the BPEL process we have just deployed.
       		</para>
       		
       		<para>
       		This can be achieved using either the supplied ant script,
       		</para>
       		
       		<code>
       		ant sendhello
       		</code>

       		<para>
       		Or by using any SOAP client, such as SOAPUI (available
       		from <ulink url="http://www.soapui.org/">http://www.soapui.org/</ulink>).
       		</para>
       		
       		<para>
       		The WSDL definition is located in the <filename>bpel</filename>
       		folder, and can be used to initialise the SOAPUI client. The
       		service location is: 
       		<ulink url="http://localhost:8080/Quickstart_hello_worldWS">http://localhost:8080/Quickstart_hello_worldWS</ulink>.
       		</para>
       		
       		<para>
       		An example message can be found in the <filename>messages</filename>
       		subfolder.
       		</para>
       		
			<imageobject>
				<imagedata fileref="images/HelloWorldReqMesg.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			When the message is submitted to the BPEL process, the response received is:
			</para>
			
			<imageobject>
				<imagedata fileref="images/HelloWorldRespMesg.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			If you then wish to modify the example and deploy a new version, you will need
			to either update the 'version' property within the <filename>build.xml</filename>,
			or specify the version when performing the command, e.g.
			</para>
			
			<code>
       		ant -Dversion=2 deploy
       		</code>
			
			<para>
			and similarly when undeploying,
			</para>
			
 			<code>
       		ant -Dversion=2 undeploy
       		</code>
       		
       		<note>
       		<para>
       		When modifying a previously deployed BPEL deployment, it will be necessary to either
       		undeploy the previous version, or increment the version number. If you attempt to
       		deploy a BPEL deployment unit with the same name as an already deployed unit, then
       		the server will generate an exception.
       		</para>
       		</note>
      </section>
       
       <section>
       		<title>ESB Examples - ESB Invocation of Hello World</title>
       		
       		<para>
       		This quickstart example demonstrates how an ESB service can directly invoke
       		a BPEL process running inside RiftSaw, as long as RiftSaw and the ESB are
       		co-located in the same JVM, and the invoked BPEL process is deployed to the
       		RiftSaw instance running co-located with the JBossESB.
       		</para>
       		
       		<para>
       		If the ESB examples were deployed during the RiftSaw installation procedure,
       		the example that we are going to try will be located in the
       		<filename>${JBossESB}/samples/quickstarts/bpel_helloworld</filename>
       		folder.
       		</para>
       		
       		<para>
       		Also note that the quickstart described in the preceding section,
       		located in the <filename>${RiftSaw}/samples/quickstarts/hello_world</filename>
       		must still be deployed. If this example is not deployed, then please follow
       		the instructions in the previous section to deploy the example. 
       		</para>
       		
       		<para>
       		The next step is to deploy the ESB service that will invoke this "hello world"
       		BPEL process. This is achieved by performing the following command in the
        	<filename>${JBossESB}/samples/quickstarts/bpel_helloworld</filename>
       		folder.
       		</para>
       		
       		<code>
       		ant deploy
       		</code>
       		
       		<para>
       		Once the ESB service has been successfully deployed, then run the following command:
       		</para>
       		
       		<code>
       		ant runtest
       		</code>
       		
       		<para>
       		This command will send the text "Hello World via ESB to BPEL" to the ESB service,
       		which will invoke the BPEL
       		process, which in turn will append "World" to the text and echo it back until it
       		is received by the client application.
       		</para>
       		
       		<para>
       		For more information on the ESB to RiftSaw integration, please see the User Guide.
       		</para>
       		
       </section>
       
       <section>
       		<title>ESB Examples - Order Management</title>
       		
       		<para>
       		The ESB/BPEL example we are going to try out is the
       		'order management' example. When the ESB examples have been
       		deployed, as described in the Installation chapter, then
       		this example will be located in the
       		<filename>${JBossESB}/samples/quickstarts/webservice_esb_bpel</filename>
       		folder.
       		</para>
       		
       		<para>
       		This example is different to the previous ESB example, in that
       		it uses the BPEL process running inside RiftSaw as a Web Service.
       		There is no direct invocation of the BPEL process.
       		</para>
       		
       		<para>
       		The first step is to deploy the example to the running JBossAS
       		server. This is achieved using the following command:
       		</para>
       		
       		<code>
       		ant deploy
       		</code>
       		
       		<para>
       		When the ant script indicates that it has completed successfully,
       		the next step is to invoke the BPEL process we have just deployed.
       		This can be achieved using any SOAP client, such as SOAPUI (available
       		from <ulink url="http://www.soapui.org/">http://www.soapui.org/</ulink>).
       		</para>
       		
       		<para>
       		The WSDL definition is located in the <filename>bpel</filename>
       		folder, and can be used to initialise the SOAPUI client. The
       		service location is: 
       		<ulink url="http://localhost:8080/Webservice_esb_bpel_Retailer">http://localhost:8080/Webservice_esb_bpel_Retailer</ulink>.
       		</para>
       		
       		<para>
       		An example message can be found in the <filename>bpel/sampleData</filename>
       		subfolder.
       		</para>
       		
			<imageobject>
				<imagedata fileref="images/RetailerReqMesg.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			When the message is submitted to the BPEL process, the response received is:
			</para>
			
			<imageobject>
				<imagedata fileref="images/RetailerRespMesg.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			This is an acknowledgement that the order has been received, and is awaiting approval.
			At this point, you can access the BPEL console, to see that the BPEL process triggered
			by the request message is still active.
			</para>
			
			<para>
			The next step is to access the order manager, located at:
       		<ulink url="http://localhost:8080/order-manager">http://localhost:8080/order-manager</ulink>.
			</para>
			
			<imageobject>
				<imagedata fileref="images/RetailerReqMesg.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			Once the order has been approved, by pressing the <emphasis>Approve</emphasis> further processing
			will be triggered using ESB components, as outlined in the following diagram.
			</para>
			
			<imageobject>
				<imagedata fileref="images/process-overview.png" align="center" width="6in" />
			</imageobject>
			
			<para>
			To verify that the BPEL processes, you should return to the instances tab on the BPEL console,
			which should show that two BPEL processes have now completed, as follows.
			</para>
			
 			<imageobject>
				<imagedata fileref="images/BPELConsole-instances2.png" align="center" width="6in" />
			</imageobject>			
			
      </section>

		<section>
			<title>Importing Examples into Eclipse</title>

			<para>
			The quickstart examples, provided with the RiftSaw distribution, can be imported into
			an Eclipse environment as BPEL2.0 projects. This enables the BPEL and WSDL to be viewed using
			Eclipse based editors. Please see the JBoss Tools project for access to appropriate versions
			of these tools that work with the RiftSaw runtime engine.
			</para>

			<orderedlist>
				<listitem>
					<para>
			Select the 'Import...' menu item, associated with the popup menu on the background of the left panal (Navigator or Package depending on perspective being viewed).
					</para>
				</listitem>
				<listitem>
					<para>
			When the import dialog appears, select the <emphasis>General->ExistingProject from Workspace</emphasis> option and press the 'Next' button.
					</para>
					<imageobject>
						<imagedata fileref="images/ImportDialog.png" align="center" width="4in" />
					</imageobject>
				</listitem>
				<listitem>
					<para>
			Ensuring that the 'Select root directory' radio button is selected, press the 'Browse' button and navigate to the <filename>${RiftSaw}/samples</filename> folder, then press 'Ok'.
					</para>
					<imageobject>
						<imagedata fileref="images/ImportFileDialog.png" align="center" width="4in" />
					</imageobject>
				</listitem>
				<listitem>
					<para>
			All of the Eclipse projects contained within the <filename>samples</filename> directory structure will be listed. Press the 'Finish' button to import them all.
					</para>
					<imageobject>
						<imagedata fileref="images/ImportProjectsDialog.png" align="center" width="4in" />
					</imageobject>
					<para>
					Once imported, the Eclipse navigator will list the sample projects:
					</para>
					<imageobject>
						<imagedata fileref="images/ImportedProjects.png" align="center" width="2in" />
					</imageobject>
				</listitem>
     		</orderedlist>

			<para>
			Once imported, the BPEL and WSDL artifacts can be viewed by double-clicking
			the appropriate files.
			</para>

			<imageobject>
				<imagedata fileref="images/BPELEditor.png" align="center" width="5in" />
			</imageobject>

			<para>
			</para>
			
			<imageobject>
				<imagedata fileref="images/WSDLEditor.png" align="center" width="5in" />
			</imageobject>

		</section>
  
</chapter>
