<!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><ul><li style="text-align: start;"><a class="jive-link-anchor-small" href="#overview">Overview of modifications</a></li><li style="text-align: start;"><a class="jive-link-anchor-small" href="#explanations">Explanation</a><ul><li style="text-align: start;"><a class="jive-link-anchor-small" href="#pomAndSettings">The pom.xml  and maven settings</a></li><li style="text-align: start;"><a class="jive-link-anchor-small" href="#filtering">Filtering and the datasource.properties and persistence.xml files</a></li><li style="text-align: start;"><a class="jive-link-anchor-small" href="#persistenceUtil">Using PersistenceUtil in unit tests</a></li></ul></li><li style="text-align: start;"><a class="jive-link-anchor-small" href="#summary">Summary</a></li><li style="text-align: start;"><a class="jive-link-anchor-small" href="#appendix">Appendix</a></li></ul><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3 id="overview">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 id="explanations">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><h5><a href="http://community.jboss.org/servlet/JiveServlet/showImage/102-17071-5-16768/Untitl33ed.jpg"><span> http://community.jboss.org/servlet/JiveServlet/downloadImage/102-17071-5-16768/450-284/Untitl33ed.jpg </span></a></h5><h5 id="pomAndSettings">A. The 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 id="filtering">B. Filtering and the datasource.properties and persistence.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/persistence.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/JPA when we instantiate an EntityManager. </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h5 id="persistenceUtil">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.*;<br/><br/>import javax.persistence.EntityManagerFactory;<br/>import javax.persistence.Persistence;<br/>...<br/>import org.junit.After;<br/>import org.junit.Before;<br/><br/>import bitronix.tm.TransactionManagerServices;<br/>import bitronix.tm.resource.jdbc.PoolingDataSource;<br/><br/>public class MyPersistenceTest {<br/><br/>    private PoolingDataSource ds1;<br/>    private EntityManagerFactory emf;<br/>    <br/>    @Before<br/>    public void setUp() throws Exception {<br/>        ds1 = setupPoolingDataSource();<br/>        ds1.init();<br/>        <br/>        emf = Persistence.createEntityManagerFactory( PERSISTENCE_UNIT_NAME );<br/>    }<br/>    <br/>    @After<br/>    public void tearDown() throws Exception {<br/>        emf.close();<br/>        ds1.close();<br/>    }<br/></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>This method does the following: </p><ol><li style="text-align: start;">It retrieves the properties stored in datasource.properties</li><li style="text-align: start;">It initializes a PoolingDataSource object. </li><li style="text-align: start;">Depending on the driver class that's been specified, other properties are injected into the PoolingDataSource instance. <ul><li style="text-align: start;">Depending on the database specific PoolingDataSource implementations, different properties are necessary to initiate the XA datasoruce. </li></ul></li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3 id="summary">Summary</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>In order to run the unit tests on a different database, you can do one of two things: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>If you want to run all of the tests with a specific database, the easiest way to do this is the following: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ol><li style="text-align: start;">Download the appropriate jdbc driver class jar for your database. </li><li style="text-align: start;">Fill a settings file with the appropriate values (including the path to your jdbc driver class jar)</li><li style="text-align: start;">Run <span style="font-family: courier new,courier; font-size: 8pt;">mvn -Pdatabase -ssettings.xml clean test</span> !</li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="text-align: start;">Otherwise, if you are developing or debugging unit tests and running them with a specific database, do the following: </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><ol><li style="text-align: start;">Ensue that the appropriate jdbc driver classes are available by doing one of the following: <ul><li style="text-align: start;">Download the appropriate jdbc driver class jar for your database and use the path to that jar. </li><li style="text-align: start;">Modify the dependency in the database profile that it points to the correct jdbc driver jar. </li></ul></li><li style="text-align: start;">Modify the properties in the jBPM project root pom so that they contain the correct values for your database. </li><li style="text-align: start;">Run <span style="font-family: courier new,courier; font-size: 8pt;">mvn -Pdatabase clean test-compile</span></li><li style="text-align: start;">Debug/run your unit tests. </li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h3 id="appendix">Appendix</h3><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The following is an example of a maven settings.xml file that you could use to test on a local PostgreSQL database. </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>