<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
jBPM 5 database testing
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/marco.rietveld">Marco Rietveld</a> in <i>jBPM</i> - <a href="http://community.jboss.org/docs/DOC-17071">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p><strong>Note: the actual implementation of this has not yet been merged into the trunk of jBPM!</strong> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In order to allow testing to be done on other databases (instead of H2), the following has been done: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>- Overview of modifications</p><p>- Explanation </p><p>- How to test on other databases</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3>Overview of modifications</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The jbpm pom.xml (artifact jbpm) now contains: </p><ol><ul><li style="text-align: start;">Properties to be used to connect to the database of choice</li><li style="text-align: start;">A database profile that can be used in order to inject a dependency for the jdbc driver jar for the database</li><li style="text-align: start;">An example profile, which has been commented out, which shows how do test without using a settings file</li></ul><li style="text-align: start;">A <span style="font-family: courier new,courier;"><span style="font-size: 8pt;">org.jbpm.persistence.util.PersistenceUtil</span> <span style="font-family: arial,helvetica,sans-serif;">class has been added to the jbpm-persistence-jpa module. <br/></span></span></li><li style="text-align: start;"><span style="font-family: arial,helvetica,sans-serif;">The jbpm-persistence-jpa module now also has a test-jar goal: the test-jar produced contains the </span><span style="font-family: courier new,courier;"><span style="font-size: 8pt;">PersistenceUtil </span><span style="font-family: arial,helvetica,sans-serif;">class mentioned above. <br/></span></span></li><li style="text-align: start;"><span style="font-family: arial,helvetica,sans-serif;">In the modules in which persistence is used during testing, the following modifications have been made: <br/></span><ul><li style="text-align: start;"><span style="font-family: arial,helvetica,sans-serif;">A <span style="font-family: courier new,courier; font-size: 8pt;">datasource.properties</span> file has been added to the <span style="font-family: courier new,courier; font-size: 8pt;">src/test/resources</span> directory. </span></li><li style="text-align: start;"><span style="font-family: arial,helvetica,sans-serif;">The </span><span style="font-size: 8pt; font-family: courier new,courier;">pom.xml</span><span style="font-family: arial,helvetica,sans-serif;"> of the module has been modified so that filtering has been turned on for the </span><span style="font-family: arial,helvetica,sans-serif;"><span style="font-family: courier new,courier; font-size: 8pt;">src/test/resources</span> directory. <br/></span></li><li style="text-align: start;"><span style="font-family: arial,helvetica,sans-serif;">The <span style="font-size: 8pt; font-family: courier new,courier;">persistence.xml</span></span><span style="font-family: courier new,courier; font-size: 8pt;"> </span>file in <span style="font-family: arial,helvetica,sans-serif;"><span style="font-family: courier new,courier; font-size: 8pt;">src/test/resources/META-INF</span> has been modified so that the<span style="font-family: courier new,courier; font-size: 8pt;"> hibernate.connection.*</span> properties use variables.</span></li></ul></li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>How all of these modifications fit together is explained in the following section. </p><h3>Explanation</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>We essentially use maven to inject the values we want into the persistence configuration. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Unfortunately, because XA datasource configuration is not uniform across different database vendors, there is also a utility class (<span style="font-size: 8pt; font-family: courier new,courier;">org.jbpm.persistence.util.PersistenceUtil</span>) which contains database specific XA datasource configuration and which we use to initiate and configure the XA datasource when testing. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>An explanation follows the diagram below: </p><p><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-17071-3-16762/og.jpg"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-17071-3-16762/450-303/og.jpg </span></a></p><h5>A. Pom.xml and maven settings: </h5><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="text-decoration: underline;">Properties</span></p><p><span style="text-decoration: underline;"><br/></span></p><p>The jbpm project root pom (jbpm artifact) contains a number of maven.* properties: a number of these settings are empty, and those that aren't are set to the h2 defaults. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>However, we can create a local <span style="font-family: courier new,courier; font-size: 8pt;">settings.xml </span>file and run the following: </p><p> <span style="font-family: courier new,courier; font-size: 8pt;">mvn clean test -ssettings-db.xml -Pdatabase</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>(The <span style="font-family: courier new,courier; font-size: 8pt;">-Pdatabase</span> is explained below)</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>By filling a local <span style="font-family: courier new,courier; font-size: 8pt;">settings.xml</span> file with the jdbc values that we want for, for example, our local PostgreSQL database, we can then use those values later on when running our tests. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Otherwise, we can also directly modify the <span style="font-family: courier new,courier; font-size: 8pt;">pom.xml </span>itself and fill the values in there. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="text-decoration: underline;">Using a profile to inject a dependency</span></p><p><span style="text-decoration: underline;"><br/></span></p><p>The <span style="font-family: courier new,courier; font-size: 8pt;">-Pdatabase</span> option in the mvn command above tells maven to use the profile that has an id of "database". </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In the project root pom, we have also defined a "database" profile  that uses a dependency. By setting the<span style="font-family: courier new,courier; font-size: 8pt;"> maven.jdbc.driver.jar </span>property (in either the <span style="font-family: courier new,courier; font-size: 8pt;">pom.xml </span>or the <span style="font-family: courier new,courier; font-size: 8pt;">settings.xml</span> file that you use) to the path of the appropriate jdbc driver class jar, we can then ensure that the database specific driver classes are available to our tests. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>[Depending on demand, we could also add properties to the pom.xml so that the groupId, artifactId, and version of the driver class jar (instead of a system path) are defined and used]</p><h5>B. Filtering and the datasource.properties and hibernate.xml files: </h5><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In the <span style="font-family: courier new,courier; font-size: 8pt;">pom.xml </span>of the module in which the testing is done (for example, jbpm-persistence-jpa or jbpm-bam), the following has also been added to the <span style="font-family: courier new,courier; font-size: 8pt;"><build> </span>section of the module pom: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier; font-size: 8pt;"><build></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">...</span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">  <testResources></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">    <testResource></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">      <directory>src/test/resources</directory></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">      <filtering>true</filtering></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">    </testResource></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">  </testResources></span></p><p><span style="font-family: courier new,courier; font-size: 8pt;">...</span></p><p><span style="font-family: courier new,courier; font-size: 8pt;"></build></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>When maven runs the <span style="font-family: courier new,courier; font-size: 8pt;">process-test-resources</span> goal, it <em>filters</em> all files in and under the <span style="font-family: courier new,courier; font-size: 8pt;">src/main/resources</span> directory. Any properties that have been defined in the (effective) <span style="font-family: courier new,courier; font-size: 8pt;">pom.xml </span>being processed by maven, will be <span style="text-decoration: underline;">replaced</span> with the values that have been assigned to them. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In this case, the following two files in <span style="font-family: courier new,courier; font-size: 8pt;">src/main/resources </span>that are filtered for us: </p><ul><li style="text-align: start;">datasource.properties</li><li style="text-align: start;">META-INF/hibernate.xml</li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="text-align: start;">In the <span style="font-family: courier new,courier;"><span style="font-size: 8pt;">PersistenceUtil</span> </span>class, we read in the <span style="font-family: courier new,courier; font-size: 8pt;">datasource.properties </span>file. The <span style="font-family: courier new,courier; font-size: 8pt;">test-compile</span> and <span style="font-family: courier new,courier; font-size: 8pt;">process-test-resources </span>goals ensure that the filtered version of this file -- where all maven variables have been replaced with their assigned values -- is placed in the same class path as the rest of the test classes and jars (target/, namely). </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="text-align: start;"><span style="font-family: courier new,courier; font-size: 8pt;">hibernate.xml </span>is used by Hibernate when we instantiate an EntityManager. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h5>C. Using the PersistenceUtil in unit tests: </h5><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Lastly, when we write any unit tests that use persistence, instead of configuring the datasource and entityManager ourselves, we use the static methods made available to us from the PersistenceUtil class. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In our test class, we can use something like the following code: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre>import static org.jbpm.persistence.util.PersistenceUtil.*;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
...
import org.junit.After;
import org.junit.Before;
import bitronix.tm.TransactionManagerServices;
import bitronix.tm.resource.jdbc.PoolingDataSource;
public class MyPersistenceTest {
    private PoolingDataSource ds1;
    private EntityManagerFactory emf;
   
    @Before
    public void setUp() throws Exception {
        ds1 = setupPoolingDataSource();
        ds1.init();
       
        emf = Persistence.createEntityManagerFactory( PERSISTENCE_UNIT_NAME );
    }
   
    @After
    public void tearDown() throws Exception {
        emf.close();
        ds1.close();
    }
</pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier; font-size: 8pt;">setupPoolingDataSource() </span>is a static method from the <span style="font-size: 8pt; font-family: courier new,courier;">PersistenceUtil</span> Class. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Todo: </p><p>- datasource configuration logic in PU class</p><p>- what the setupPoolingDataSource method does</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>[Still under progress.. ]</p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-17071">going to Community</a></p>
<p style="margin: 0;">Create a new document in jBPM at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2034">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>