<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ch.installer"
         version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
  <title>Installer</title>

  <para>This guide will assist you in installing and running a demo setup of the various components of the jBPM project.  If you have any feedback on how to improve this guide, if you encounter problems, or if you want to help out, do not hesitate to contact the jBPM community as described in the "What to do if I encounter problems or have questions?" section.</para>

  <section>
    <title>Prerequisites</title>

    <para>This script assumes you have Java JDK 1.5+ (set as JAVA_HOME), and Ant 1.7+ installed.  If you don't,
    use the following links to download and install them:</para>

    <para>Java: <ulink url="http://java.sun.com/javase/downloads/index.jsp">http://java.sun.com/javase/downloads/index.jsp</ulink></para>
    <para>Ant: <ulink url="http://ant.apache.org/bindownload.cgi">http://ant.apache.org/bindownload.cgi</ulink></para>
  </section>

  <section>
    <title>Download the installer</title>

    <para>First of all, you need to <ulink url="https://sourceforge.net/projects/jbpm/files/jBPM%205/">
    download</ulink> the installer.  There are two versions, a full installer
    (which already contains a lot of the dependencies that are necessary during the installation) and
    a minimal installer (which only contains the installer and will download all dependencies).  In
    general, it is probably best to download the full installer: jBPM-{version}-installer-full.zip</para>
    
    <para>You can also find the latest snapshot release here (only minimal installer) here:</para>
    <para><ulink url="https://hudson.jboss.org/jenkins/job/jBPM/lastSuccessfulBuild/artifact/jbpm-distribution/target/">
    https://hudson.jboss.org/jenkins/job/jBPM/lastSuccessfulBuild/artifact/jbpm-distribution/target/</ulink></para>

  </section>

  <section>
    <title>Demo setup</title>

  <para>The easiest way to get started is to simply run the installation script to install the demo setup.
  Simply go into the install folder and run:</para>

  <programlisting>ant install.demo</programlisting>

    <para>This will:
      <itemizedlist>
        <listitem>Download JBoss AS</listitem>
        <listitem>Download Eclipse</listitem>
        <listitem>Install Drools Guvnor into JBoss AS</listitem>
        <listitem>Install Oryx Designer into JBoss AS</listitem>
        <listitem>Install the jBPM gwt-console into JBoss AS</listitem>
        <listitem>Install the jBPM Eclipse plugin</listitem>
        <listitem>Install the Drools Eclipse plugin</listitem>
      </itemizedlist>
    </para>

    <para>This could take a while (REALLY, not kidding, we are downloading an application server
    and Eclipse installation, even if you downloaded the full installer).  The script however always
    shows which file it is downloading (you could for example check whether it is still downloading
    by checking the whether the size of the file in question in the jbpm-installer/lib folder is still
    increasing). If you want to avoid downloading specific components (because you will not be using
    them or you already have them installed somewhere else), check below for running only specific
    parts of the demo or directing the installer to an already installed component.</para>
    
    <para>To limit the amount of data that needs to be downloaded, we have disabled the download
    of the Eclipse BIRT plugin for reporting by default. If you want to try out reporting as well
    in the jBPM console, make sure to put the jBPM.birt.download property in the build.properties
    file to true before running the installer.</para>

    <para>Once the demo setup has finished, you can start playing with the various components by
    starting the demo setup:</para>

    <programlisting>ant start.demo</programlisting>

    <para>This will:
      <itemizedlist>
        <listitem>Start the H2 database</listitem>
        <listitem>Start the JBoss AS</listitem>
        <listitem>Start Eclipse</listitem>
        <listitem>Start the Human Task Service</listitem>
      </itemizedlist>
    </para>

    <para>Once everything is started, you can start playing with the Eclipse tooling, Guvnor
    repository and jBPM console, as explained in the next three sections.</para>
    
    <para>If you do not wish to use Eclipse in the demo setup, you can use the alternative commands:</para>
    <programlisting>
    ant install.demo.noeclipse
    ant start.demo.noeclipse</programlisting>

  </section>

  <section>
    <title>10-Minute Tutorial: Using the Eclipse tooling</title>

    <para>The <ulink url="http://people.redhat.com/kverlaen/install-eclipse-jbpm.swf">following
    screencast</ulink> gives an overview of how to run a simple demo process in Eclipse. It shows you: 
      <itemizedlist>
        <listitem>How to import an existing example project into your workspace, containing
          <itemizedlist>
            <listitem>a sample BPMN2 process for requesting a performance evaluation</listitem>
            <listitem>a sample Java class to start the process</listitem>
          </itemizedlist>
        </listitem>
        <listitem>How to start the process</listitem>
      </itemizedlist>
    </para>
    
    <ulink url="http://people.redhat.com/kverlaen/install-eclipse-jbpm.swf">
      <figure>
        <mediaobject>
          <imageobject>
        <imagedata align="center" fileref="images/Chapter-Installer/ScreenCast1.png" format="PNG" role="" />
          </imageobject>
        </mediaobject>
      </figure>
    </ulink>
    
    <para>Do the following:
      <itemizedlist>
        <listitem>Once Eclipse has opened, simple import (using "File -> Import ..." and then under
        the General category, select "Existing Projects into Workspace") the existing sample project
        (in the jbpm-installer/sample/evaluation directory).  This should add the sample project,
        including a simple BPMN2 process and a Java file to start the process.</listitem>
        <listitem>You can open the BPMN2 process and the Java class by double-clicking it.</listitem>
        <listitem>We will now debug the process, so we can visualize its runtime state using the
        debug tooling. First put a breakpoint on line "ksession.startProcess" of the ProcessTest class.
        To start debugging, right-click on ProcessTest.java in the com.sample package
        (under "src/main/java") and select "Debug As - Java Application", and switch to the debug
        perspective.</listitem>
        <listitem>Open up the various debug views: Under "Window - Show View -> Other ...", select 
        the Process Instances View and Process Instance View (under Drools category) and the Human
        Task View (under Drools Task) and click OK.</listitem>
        <listitem>The program will hit the breakpoint right before starting the process.  Click on
        the "Step Over" (F6) to start the process.  In this case, it will simply
        start the process, which will result in the creation of a new user task for the user "krisv"
        in the human task service, after which the process will wait for its execution.  Go to the
        Human Task View, fill in "krisv" under UserId and click Refresh.  A new Performance Evaluation
        task should show up.</listitem>
        <listitem>To show the state of the process instance you just started graphically, click on the
        Process Instances View and then select the ksession variable in the Variables View.  This will
        show all active process instances in the selected session.  In this case, there is only one
        process instance.  Double-click it to see the state of that process instance annotated on the
        process flow chart.</listitem>
        <listitem>Now go back to the Task View, select the Performance Evaluation task and first
        start and then complete the selected task.  Now go back to the Process Instances view and double
        click the process instance again to see its new state.</listitem>
      </itemizedlist>
    </para>

    <para>You could also create a new project using the jBPM project wizard.  This sample project
    contains a simple HelloWorld BPMN2 process and an associated Java file to start the process.
    Simple select "File - New ... - Project ..." and under the "jBPM" category, select "jBPM project"
    and click "Next".  Give the project a name and click "Finish".  You should see a new project
    containing a "sample.bpmn" process and a "com.sample.ProcessTest" Java class.  You can open the
    BPMN2 process by double-clicking it.  To execute the process, right-click on ProcessTest.java
    and select "Run As - Java Application".  You should see a "Hello World" statement in the output
    console.</para>
 
  </section>

  <section>
    <title>10-Minute Tutorial: Using the jBPM Console</title>

    <para>Open up the process management console:</para>
    <para><ulink url="http://localhost:8080/jbpm-console">http://localhost:8080/jbpm-console</ulink></para>

    <para>Log in, using krisv / krisv as username / password. The <ulink url="http://people.redhat.com/kverlaen/install-gwt-console-jbpm.swf">following screencast</ulink> gives an overview of how to manage your
    process instances. It shows you: 
      <itemizedlist>
        <listitem>How to start a new process</listitem>
        <listitem>How to look up the current status of a running process instance</listitem>
        <listitem>How to look up your tasks</listitem>
        <listitem>How to complete a task</listitem>
        <listitem>How to generate reports to monitor your process execution</listitem>
      </itemizedlist>
    </para>
    
    <ulink url="http://people.redhat.com/kverlaen/install-gwt-console-jbpm.swf">
      <figure>
        <mediaobject>
          <imageobject>
        <imagedata align="center" fileref="images/Chapter-Installer/ScreenCast2.png" format="PNG" role="" />
          </imageobject>
        </mediaobject>
      </figure>
    </ulink>
    
    <para>
      <itemizedlist>
        <listitem>To manage your process instances, click on the "Processes" tab at the left an select "Process Overview".  
After a slight delay (if you are using the application for the first time, due to session initalization
etc.), the "Process" list should show all the known processes.  The jbpm-console in the demo setup 
currently loads all the process in the "src/main/resources" folder of the evaluation sample in 
"jbpm-installer/sample/evaluation".  If you click the process, it will show you all current running 
instances.  Since there are no running instances at this point, the "Instance" table will remain 
empty.</listitem>

  <listitem>You can start a new process instance by click on the "Start" button.  After confirming that you want to 
start a new execution of this process, you will see a process form where you need to fill in the 
necessary information to start the process.  In this case, you need to fill in your username "krisv",
after which you can complete the form and close the window.  A new instance should show up in the 
"Instance" table.  If you click the process instance, you can check its details below and the diagram 
and instance data by click on the "Diagram" and "Instance Data" buttons respectively.  The process 
instance that you just started is first requiring a self-evaluation of the user and is waiting until 
the user has completed this task.</listitem>

  <listitem>To see the tasks that have been assigned to you, choose the "Tasks" tab on the left and select 
"Personal Tasks" (you may need to click refresh to update your task view).  The personal tasks table 
should show a "Performance Evaluation" task for you.  You can complete this task by selecting it and 
clicking the "View" button.  This will open the task form for performance evaluations.  You can fill 
in the necessary data and then complete the form and close the window.  After completing the task, you 
could check the "Process Overview" once more to check the progress of your process instance.  You 
should be able to see that the process is now waiting for your HR manager and project manager to also 
perform an evaluation.  You could log in as "john" / "john" and "mary" / "mary" to complete these 
tasks.</listitem>

  <listitem>After starting and/or completing a few process instances and human tasks, you can generate a report of 
what happened so far.  Under "Reporting", select "Report Templates".  By default, the console has two 
report templates, one for generating a generic overview for all processes and one for inspecting once 
specific process definition.  If you select the latter, make sure to enter "com.sample.evaluation" as 
the process definition id to see the activity related to the evaluation process.  Click the "Create 
Report" button to generate a realtime report of the current status.  Notice that the initialization of 
the reports might take a moment, especially the first time you use the application.</listitem>
    </itemizedlist>
  </para>
  </section>

  <section>
    <title>10-Minute Tutorial: Using Guvnor repository and Designer</title>
    
    <para>The Guvnor repository can be used as a process repository to store business processes.  It also offers
a web-based interface to manage your processes.  This includes a web-based editor for viewing and
editing processes.</para>

    <para>Open up Drools Guvnor:</para>
    <para><ulink url="http://localhost:8080/drools-guvnor">http://localhost:8080/drools-guvnor</ulink></para>

    <para>Log in, using any non-empty username / password (we disabled authentication for demo purposes). 
    The <ulink url="http://people.redhat.com/kverlaen/install-guvnor-jbpm.swf">following screencast</ulink> gives an overview of how to manage your repository. It shows you:
      <itemizedlist>
        <listitem>How to import an existing process (in this case the evaluation process) from eclipse into guvnor</listitem>
        <listitem>How to open up the evaluation process in the web editor</listitem>
        <listitem>How to build a package so it can be used for creating a session</listitem>
      </itemizedlist>
    </para>

    <ulink url="http://people.redhat.com/kverlaen/install-guvnor-jbpm.swf">
      <figure>
        <mediaobject>
          <imageobject>
        <imagedata align="center" fileref="images/Chapter-Installer/ScreenCast3.png" format="PNG" role="" />
          </imageobject>
        </mediaobject>
      </figure>
    </ulink>
    
    <para>If you want to know more, we recommend you take a look at the rest of the Drools Guvnor documentation.</para>

    <para>Once you're done playing:</para>
    <programlisting>ant stop.demo</programlisting>
    <para>and simply close all the rest.</para>

  </section>

  <section>
  
    <title>10-Minute Tutorial: Using your own database with jBPM</title>
 
    <para>At the moment, this quickstart does <emphasis>not</emphasis> work with JBoss AS 5. 
    However, an update to the quickstart (and installer) is forthcoming which will fix that 
    (and make it work with JBoss AS 5). [01/2012]
    </para> 

    <section>
      <title>Introduction</title>
  
      <para>In this quickstart, we are going to: 
        <orderedlist>
          <listitem><para>modify the persistence settings for the process engine</para></listitem>
          <listitem><para>modify the persistence settings for the task server</para></listitem>
          <listitem><para>test the startup with our new settings!</para></listitem>
        </orderedlist>
      </para>
  
      <para>You will need a local instance of a database, in this case MySQL in order 
      to complete this quickstart</para>
  
      <para>First though, let's look at the persistence setup that jBPM uses. In the demo, and 
      in general, there are three types of persistent entities used by jBPM:
        <itemizedlist> 
          <listitem>entities used for saving the the actual session, process and work item information.</listitem>
          <listitem>entities used for logging and generating Business Activity Monitoring (BAM) 
          information.</listitem>
          <listitem>entities used by the task service.</listitem>
        </itemizedlist>
      </para>
  
      <para><quote>persistent entities</quote> in this context, are java classes that represent information in the database.</para>
  
      <para>For reasons that I'll explain later on in this quickstart, the demo uses two different 
      persistent units:
        <itemizedlist>
          <listitem>one for jBPM and the logging/BAM information,</listitem>
          <listitem>and one for the task service. </listitem>
        </itemizedlist>
      With other jBPM installations, there's no reason not to use only one persistent unit if you want to. 
      </para>
  
      <para>The first persistence unit needs to use JTA, which is why we also need to define 
      a seperate datasource for that persistence unit as well.</para> 
    </section>
  
    <section>
      <title>Database setup</title>
  
      <para>In the MySQL database that I use in this quickstart, I've created two users: 
        <itemizedlist>
          <listitem>user/schema "jbpm5" with password "jbpm5" (for jBPM and the logging/BAM information)</listitem>
          <listitem>user/schema "task" with password "task" (for the task service) </listitem>
        </itemizedlist>
      </para>
  
      <para>If you end up using different names for your user/schemas, please make a note of
      where we insert "jbpm5" and "task" in the configuation files.</para>
  
      <para>If you want to try this quickstart with <emphasis>another</emphasis> database, I've 
      included a section at the end of this quickstart that describes what you may need
      to modify.</para>
  
    </section>
  
    <section>
      <title>Quickstart</title>
  
      <para>The following 4 files define the persistence settings for the jbpm-installer demo:
        <itemizedlist>
          <listitem>db/persistence.xml</listitem>
          <listitem>task-service/resources/META-INF/persistence.xml</listitem> 
          <listitem>db/jBPM-ds.xml
            <itemizedlist>
              <listitem>If you're using the JBoss AS 5 server</listitem>
            </itemizedlist></listitem>
          <listitem>standalone.xml
            <itemizedlist>
              <listitem>If you're using the JBoss AS 7 server</listitem>
            </itemizedlist></listitem>
        </itemizedlist>
      </para>
    
      <para>Do the following:<itemizedlist>
        <listitem>
          <para><filename>db/persistence.xml</filename>:</para>
          <para>This is the JPA persistence file that defines the persistence settings used by 
          jBPM for both the process engine information and the logging/BAM information. The installer 
          ant script moves this file to the expanded gwt console server war before the server 
          is started.</para>
          <para>In this file, you will have to change the name of the hibernate dialect used 
          for your database.</para>
          <para>The original line is:</para> 
          <programlisting>&lt;property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/&gt;</programlisting>
          <para>In the case of a MySql database, you need to change it to:</para> 
          <programlisting>&lt;property name="hibernate.dialect" value="org.hibernate.dialect.<emphasis role="bold">MySQL</emphasis>Dialect"/&gt;</programlisting>
          <para>For those of you who decided to use another database, a list of the available 
          hibernate dialect classes can be found <ulink 
          url="http://docs.jboss.org/hibernate/core/3.3/reference/en-US/html/session-configuration.html#configuration-optional-dialects">
          here</ulink>.</para>
        </listitem><listitem>
          <para><filename>task-service/resources/META-INF/persistence.xml</filename>:</para>
          <para>The task service (that the installer starts) uses the JPA Persistence settings 
          described in this file.</para>
          <para>The original file contains the following lines:</para>
          <programlisting>    &lt;properties&gt;
      &lt;property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/&gt;
      &lt;property name="hibernate.connection.driver_class" value="org.h2.Driver"/&gt;
      &lt;property name="hibernate.connection.url" value="jdbc:h2:tcp://localhost/runtime/task" /&gt;
      &lt;property name="hibernate.connection.username" value="sa"/&gt;
      &lt;property name="hibernate.connection.password" value="sasa"/&gt;</programlisting>
           <para>Please change these lines so that they look like this:</para> 
           <programlisting>    &lt;properties&gt;
      &lt;property name="hibernate.dialect" value="org.hibernate.dialect.<emphasis role="bold">MySQL</emphasis>Dialect"/&gt;
      &lt;property name="hibernate.connection.driver_class" value="<emphasis role="bold">com.mysql.jdbc.Driver</emphasis>"/&gt;
      &lt;property name="hibernate.connection.url" value="<emphasis role="bold">jdbc:mysql://localhost:3306/task</emphasis>" /&gt;
      &lt;property name="hibernate.connection.username" value="<emphasis role="bold">task</emphasis>"/&gt;
      &lt;property name="hibernate.connection.password" value="<emphasis role="bold">task</emphasis>"/&gt;</programlisting>
        </listitem><listitem>
          <para><filename>db/jBPM-ds.xml</filename>:</para>
          <para>This step is <emphasis>only</emphasis> neccessary if you're using JBoss AS 5.</para>
          <para>This file is the configuration for the (JTA) datasource used by the jBoss AS 
          5 instance for the process engine persistence. The installer ant script moves this 
          file to the jboss server deploy directory.</para> 
          <para>The original file contains the following lines:</para>
          <programlisting>&lt;datasources&gt;
  &lt;local-tx-datasource&gt;
    &lt;jndi-name&gt;jboss/datasources/jbpmDS&lt;/jndi-name&gt;
    &lt;connection-url&gt;jdbc:h2:tcp://localhost/runtime/jbpm-demo&lt;/connection-url&gt;
    &lt;driver-class&gt;org.h2.jdbcx.JdbcDataSource&lt;/driver-class&gt;
    &lt;user-name&gt;sa&lt;/user-name&gt;
    &lt;password&gt;&lt;/password&gt;
  &lt;/local-tx-datasource&gt;
&lt;/datasources&gt;</programlisting>
          <para>Please change these to the following:</para>
          <programlisting>&lt;datasources&gt;
  &lt;local-tx-datasource&gt;
    &lt;jndi-name&gt;jboss/datasources/jbpmDS&lt;/jndi-name&gt;
    &lt;connection-url&gt;<emphasis role="bold">jdbc:mysql://localhost:3306/jbpm5</emphasis>&lt;/connection-url&gt;
    &lt;driver-class&gt;<emphasis role="bold">com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</emphasis>&lt;/driver-class&gt;
    &lt;user-name&gt;<emphasis role="bold">jbpm5</emphasis>&lt;/user-name&gt;
    &lt;password&gt;<emphasis role="bold">jbpm5</emphasis>&lt;/password&gt;
  &lt;/local-tx-datasource&gt;
&lt;/datasources&gt;</programlisting>
        </listitem><listitem>
          <para><filename>standalone.xml</filename>:</para>
          <para>This step is <emphasis>only</emphasis> neccessary if you're using AS 7.</para>
          <para>This file is the configuration for the standalone JBoss AS 7 server. When the 
          installer starts the demo (using jBoss AS 7), it moves this file to the <code>standalone/configuration</code> 
          directory in the jboss server directory</para>
          <para>We need to change the datasource configuration in <code>standalone.xml</code> 
          so that the (JTA) datasource for the jBPM process engine and logging/BAM points to 
          our MySQL database</para>
          <para>The original file contains the following lines:</para>
          <programlisting>        &lt;subsystem xmlns="urn:jboss:domain:datasources:1.0"&gt;
            &lt;datasources&gt;
                &lt;datasource jndi-name="java:jboss/datasources/jbpmDS" enabled="true" use-java-context="true" pool-name="H2DS"&gt;
                    &lt;connection-url&gt;jdbc:h2:tcp://localhost/runtime/jbpm-demo&lt;/connection-url&gt;
                    &lt;driver&gt;h2&lt;/driver&gt;
                    &lt;pool&gt;&lt;/pool&gt;
                    &lt;security&gt;
                       &lt;user-name&gt;sa&lt;/user-name&gt;
                       &lt;password&gt;&lt;/password&gt;
                    &lt;/security&gt;
                &lt;/datasource&gt;
                &lt;drivers&gt;
                    &lt;driver name="h2" module="com.h2database.h2"&gt;
                        &lt;xa-datasource-class&gt;org.h2.jdbcx.JdbcDataSource&lt;/xa-datasource-class&gt;
                    &lt;/driver&gt;
                &lt;/drivers&gt;
            &lt;/datasources&gt;
        &lt;/subsystem&gt;</programlisting>
          <para>Change the lines to the following:</para>
          <programlisting>        &lt;subsystem xmlns="urn:jboss:domain:datasources:1.0"&gt;
            &lt;datasources&gt;
                &lt;datasource jndi-name="java:jboss/datasources/jbpmDS" pool-name="H2DS" enabled="true" use-java-context="true"&gt;
                    &lt;connection-url&gt;<emphasis role="bold">jdbc:mysql://localhost:3306/jbpm5</emphasis>&lt;/connection-url&gt;
                    &lt;driver&gt;<emphasis role="bold">mysql</emphasis>&lt;/driver&gt;
                    &lt;pool&gt;&lt;/pool&gt;
                    &lt;security&gt;
                       &lt;user-name&gt;<emphasis role="bold">jbpm5</emphasis>&lt;/user-name&gt;
                       &lt;password&gt;<emphasis role="bold">jbpm5</emphasis>&lt;/password&gt;
                    &lt;/security&gt;
                &lt;/datasource&gt;
                &lt;drivers&gt;
                    &lt;driver name="<emphasis role="bold">mysql</emphasis>" module="<emphasis role="bold">com.mysql</emphasis>"&gt;
                        &lt;xa-datasource-class&gt;<emphasis role="bold">com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</emphasis>&lt;/xa-datasource-class&gt;
                    &lt;/driver&gt;
                &lt;/drivers&gt;
            &lt;/datasources&gt;
        &lt;/subsystem&gt;</programlisting>
        </listitem><listitem>
          <para><filename>Start the demo</filename></para>
          <para>We've modified all the neccessary files at this point, all that's left to do is run the demo.</para>
          <para>Of course, this would be a good time to start your database up as well!</para>
          <para>If you haven't installed the demo yet, do that first:
            <programlisting>ant install.demo.db</programlisting>
            If you have already installed and <emphasis>run</emphasis> the demo, it can't hurt to reinstall the demo: 
            <programlisting>ant clean.demo; ant install.demo.db</programlisting>
            After you've done that, you can finally start the demo using the following command: 
            <programlisting>ant start.demo.db</programlisting>
          </para>
          <para>If you're done with the demo, you can stop it using this command: 
            <programlisting>ant stop.demo.db</programlisting>
            The <code>stop.demo</code> ant task will also work, although it might throw some exceptions.
          </para>
        </listitem><listitem>
          <para><filename>Problems?</filename></para>
          <para>If you this isn't working for you, please try the following:
            <itemizedlist>
              <listitem>Please double check the files you've modified: I <emphasis>wrote</emphasis> this, but still made mistakes when changing files!</listitem>
              <listitem>Please make sure that you don't secretly have another instance of jboss AS running.</listitem>
              <listitem>If neither of those work (and you're using MySQL), please do then let us know.</listitem>
            </itemizedlist>
          </para>
        </listitem>
      </itemizedlist></para>
    </section>
  
    <section>
      <title>Using a different database</title>
      
      <para>If you decide to use a different database with this demo, you need to remember 
      the following when going through the steps above:
        <itemizedlist>
          <listitem>Change the JDBC URLs, usernames and passwords, and Hibernate dialect lines 
          to match your database information in the configuration files mentioned above.</listitem>
          <listitem>You will need to download the correct driver jar for your database 
          and add it to the <code>db/drivers</code> directory. If you're using JBoss AS 5, 
          the installer ant script will make sure that your downloaded driver is installed 
          in the server. If you're using JBoss AS 7, see the next step.</listitem>
          <listitem>In order make sure your driver will be correctly installed in 
          the JBoss AS 7 server, you can do one of two things. Both ways are explained 
          <ulink url="https://community.jboss.org/wiki/DataSourceConfigurationinAS7">here</ulink>.
            <itemizedlist>
              <listitem><ulink url="https://community.jboss.org/wiki/DataSourceConfigurationinAS7#Installing_a_JDBC_driver_as_a_deployment">
              Modify and install</ulink> the downloaded jar as a <emphasis>deployment</emphasis>. 
              In this case you will have to copy the jar yourself to the <code>standalone/deployments</code> 
              directory.
              </listitem><listitem>Otherwise, you can 
              <ulink url="https://community.jboss.org/wiki/DataSourceConfigurationinAS7#Installing_a_JDBC_driver_as_a_module">
              install</ulink> the driver jar as a <emphasis>module</emphasis>, which is what 
              the install script does. 
              </listitem>
            </itemizedlist>
          While the former (deployment) is possibly easier, the latter (module) is slightly more 
          straightforward -- and the installer can help you. If you choose to do the latter, 
          please do the following:
            <itemizedlist>
              <listitem>Change the <code>db.driver.jar.name</code> property in <code>build.xml</code> 
              to the name of the downloaded jdbc driver jar you placed in <code>db/drivers</code>.
              For example: 
              <programlisting>  &lt;property name="db.driver.jar.name" value="<emphasis role="bold">postgresql-8.4-701.jdbc3.jar</emphasis>" /&gt;</programlisting>
              </listitem><listitem>Change the <code>&lt;driver&gt;</code> information in
              the <code>&lt;datasource&gt;</code> section of <code>standalone.xml</code> so 
              that it refers to the name of your driver module (see next step). For example:
              <programlisting>&lt;driver&gt;<emphasis role="bold">postgresql</emphasis>&lt;/driver&gt;</programlisting>
              </listitem><listitem>Further on in <code>standalone.xml</code> is the 
              <code>&lt;drivers&gt;</code> section of the 
              <code>&lt;datasources&gt;</code> (note the plural: driver<emphasis>s</emphasis>, 
              datasource<emphasis>s</emphasis>). We need to do the following with this file:
              <itemizedlist>
                <listitem>Change the name of the driver to match the name in the last step,</listitem> 
                <listitem>Give an appropriate name to the module,</listitem>
                <listitem>And fill in the correct name of the XA datasource class to use.</listitem>
              </itemizedlist>
              For example:
              <programlisting>    &lt;drivers&gt;
        &lt;driver name="<emphasis role="bold">postgresql</emphasis>" module="<emphasis role="bold">org.postgresql</emphasis>"&gt;
            &lt;xa-datasource-class&gt;<emphasis role="bold">org.postgresql.xa.PGXADataSource</emphasis>&lt;/xa-datasource-class&gt;
        &lt;/driver&gt;
    &lt;/drivers&gt;</programlisting>
              </listitem><listitem>Change the <code>db.driver.module.prefix</code> property 
              in <code>build.xml</code> to the same <quote>value</quote> you used for the module name 
              in <code>standalone.xml</code>. In the example above, I used 
              <quote><code>org.postgresql</code></quote> which means that I should then use
              <code>org/postgresql</code> for the <code>db.driver.module.prefix</code> property. For example: 
              <programlisting>  &lt;property name="db.driver.module.prefix" value="<emphasis role="bold">org/postgresql</emphasis>" /&gt;</programlisting>
              </listitem><listitem>Lastly, you'll have to modify the <code>db/driver_jar_module.xml</code>
              file. We need to
              <itemizedlist>
                <listitem>Change the name of the <emphasis>module</emphasis> to match the 
                          <code>db.driver.module.prefix</code> property above</listitem>
                <listitem>Change the name of the module resource to the name of the JDBC driver 
                          jar that you downloaded.</listitem>
              </itemizedlist>
              The top of the original file looks like this: 
              <programlisting>&lt;module xmlns="urn:jboss:module:1.0" name="com.mysql"&gt;
   &lt;resources&gt;
     &lt;resource-root path="mysql-connector-java.jar"/&gt;
   &lt;/resources&gt;</programlisting>
              Change those lines to look like this, for example: 
              <programlisting>&lt;module xmlns="urn:jboss:module:1.0" name="<emphasis role="bold">org.postgresql</emphasis>"&gt;
   &lt;resources&gt;
     &lt;resource-root path="<emphasis role="bold">postgresql-8.4-701.jdbc3.jar</emphasis>"/&gt;
   &lt;/resources&gt;</programlisting>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </para>
    </section>
  
  </section>

  <section>
    <title>What to do if I encounter problems or have questions?</title>

    <para>You can always contact the jBPM community for assistance.</para>
    <para>Email: jbpm-dev@lists.jboss.org</para>
    <para>IRC: #jbpm at irc.codehaus.org</para>
    <para><ulink url="http://community.jboss.org/en/jbpm?view=discussions">jBPM User Forum</ulink></para>
  
  </section>
   
  <section>
  
    <title>Frequently asked questions</title>
    
    <para>Some common issues are explained below.</para>

    <para>Q: What if the installer complains it cannot download component X?</para>
    <para>A: Are you connected to the internet? Do you have a firewall turned on? Do you require a proxy?  It might be possible that one of the locations we're downloading the components from is temporarly offline.  Try downloading the components manually (possibly from alternate locations) and put them in the jbpm-installer/lib folder.</para>

    <para>Q: What if the installer complains it cannot extract / unzip a certain jar/war/zip?</para>
    <para>A: If your download failed while downloading a component, it is possible that the installer is trying to use an incomplete file.  Try deleting the component in question from the jbpm-installer/lib folder and reinstall, so it will be downloaded again.</para>

    <para>Q: What if I have been changing my installation (and it no longer works) and I want to start over again with a clean installation?</para>
    <para>A: You can use ant clean.demo to remove all the installed components, so you end up with a fresh installation again.</para>

    <para>Q: I sometimes see exceptions when trying to stop or restart certain services, what should I do?</para>
    <para>A: If you see errors during shutdown, are you sure the services were still running?  If you see exceptions during restart, are you sure the service you started earlier was successfully shutdown?  Maybe try killing the services manually if necessary.</para>

    <para>Q: Something seems to be going wrong when running Eclipse but I have no idea what.  What can I do?</para>
    <para>A: Always check the consoles for output like error messages or stack traces.  You can also check the Eclipse Error Log for exceptions.  Try adding an audit logger to your session to figure out what's happening at runtime, or try debugging your application.</para>

    <para>Q: Something seems to be going wrong when running the a web-based application like the jbpm-console, Guvnor and the Designer.  What can I do?</para>
    <para>A: You can check the server log for possible exceptions in the jbpm-installer/jboss-4.2.3.GA/server/default/log directory.</para>

    <para>For all other questions, try contacting the jBPM community as described above.</para>
  
  </section>

</chapter>
