code style improvements.
[utils] / test / enterprise / src / main / java / org / wamblee / test / persistence / package-info.java
1 /*
2  * Copyright 2005-2010 the original author or authors.
3  * 
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  * 
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  * 
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */ 
16 /**
17  * <p>
18  * This package provides test library for database testing in general and JPA testing
19  * specifically. As part of this it provides a means to transparently start an inmemory 
20  * database from a junit test or connect to an external database. Also, given a persistence 
21  * unit it is easy to start testing it in a junit test with only a few lines of code.
22  * </p> 
23  * 
24  * <p>
25  * The main use cases are explained below:
26  * </p> 
27  * <ul>
28  *   <li> <a href="#db-basic">Basic database testing, transparently connecting to a database</a>  
29  *   </li>
30  *   <li> <a href="#db-basic-external">Connecting to an external database</a>
31  *   </li>
32  *   <li> <a href="#db-utils">Executing code within a JDBC transaction</a>
33  *   </li>
34  *   <li> <a href="#db-unit">Using DB Unit in your tests</a>
35  *   </li>
36  *   <li> <a href="#db-jpa-basic">Basic JPA testing</a> 
37  *   </li>
38  *   <li> <a href="#db-jpa-plus-jdbc">JPA testing combined with JDBC and DBUnit</a>
39  *   </li>
40  *   <li> <a href="#db-jpa-services">Testing a service that requires a transaction</a>
41  *   </li>
42  * </ul>
43  * 
44  * <p>
45  *   See also the <a href="#design-overview">design overview</a>.  
46  * </p>
47  * 
48  * <a name="db-basic">
49  *   <h2>Basic database testing, transparently connecting to a database</h2>
50  * </a>
51  * Starting the database: 
52  * <pre>
53  *      Database db = DatabaseBuilder.getDatabase();
54  *      DataSource dataSource = db.start();
55  * </pre>
56  * <p>
57  * If nothing is specified in the user's environment, an inmemory database is started (derby).
58  * Using the datasource is just standard JDBC now.
59  * </p>
60  * <p>
61  * After a test it is good practice to stop the database:
62  * </p>
63  * <pre>
64  *      db.stop();
65  * </pre>
66  * 
67  * <a name="db-basic-external">
68  *   <h2>Connecting to an external database</h2>
69  * </a>
70  * 
71  * Connecting to an external database can be done by requiring the 'external' capability on 
72  * the database provider. 
73  * <pre>
74  *      Database db = DatabaseBuilder.getDatabase(DatabaseProvider.CAPABILITY_EXTERNAL); 
75  * </pre>
76  * This also requires a number of environment variables or system properties to be set, 
77  * see {@link ExternalDatabase}. 
78  * 
79  * <p>
80  * However, the most convenient way to set the capabilities is usually to set a system property or environment 
81  * variable see the javadocs of {@link DatabaseBuilder}. and 
82  * specifically <code>DatabaseBuilder.DB_CAPABILITIES_PROP</code>
83  * </p>
84  * 
85  * 
86  * <a name="db-utils">
87  *   <h2>Executing code within a JDBC transaction</h2>
88  * </a>
89  * <p>
90  *   To execute code withing a JDBC transaction, use the {@link DatabaseUtils} and 
91  *   use the {@link DatabaseUtils#executeInTransaction(org.wamblee.support.persistence.DatabaseUtils.JdbcUnitOfWork)}
92  *   method. 
93  * </p>
94  * <pre>
95  *       DatabaseUtils dbutils = new DatabaseUtils(dataSource);
96  *       boolean result = dbutils.executeInTransaction(
97  *           new JdbcUnitOfWork&lt;Boolean&gt;() {
98  *               &#064;Override
99  *               public Boolean execute(Connection aConnection) throws Exception {
100  *                   ResultSet res = jpaTester.getDbUtils().executeQuery(
101  *                       aConnection, GROUP_QUERY, aGroup);
102  *                   return res.next();
103  *               }
104  *           });
105  * </pre>
106  * {@link DatabaseUtils} also provides various other utility methods to work with JDBC queries. 
107  * 
108  * <a name="db-unit">
109  *   <h2>Using DB Unit in your tests</h2>
110  * </a>
111  * 
112  * <p>To work with <a href="http://dbunit.org">DBUnit</a>, 
113  * <code>DatabaseUtils#createDbTester(org.dbunit.dataset.filter.ITableFilterSimple)</code>
114  * must be used passing it in the tables to use in the form of a {@link org.dbunit.dataset.filter.ITableFilterSimple}
115  * object. </p>
116  * 
117  * <pre>
118  *      IDatabaseTester dbtester = dbutils.createDbTester(new ITableFilterSimple() {
119  *          public boolean accept(String aTableName) throws DataSetException {
120  *              return aTableName.startsWith("XYZ_");
121  *          }
122  *      });
123  * </pre>
124  * 
125  * <p>The reason for using a <code>DatabaseUtils</code> instead of DBUnit directly is that 
126  * <code>DatabseUtils</code> will keep track of connections and close them when <code>DatabaseUtils</code>
127  * is closed</p>
128  * 
129  * <a name="db-jpa-basic">
130  *   <h2>Basic JPA testing</h2>
131  * </a>
132  * <p>
133  *    First step is to create a {@link PersistenceUnitDescription} that matches the persistence unit you
134  *    want to test. 
135  * </p>
136  * <p>Second step is to make sure that all entities are listed explicitly in your
137  *    <code>persistence.xml</code>. Currently, class path scanning appears to fail when
138  *    run from junit. 
139  *    Specifying all entities explicitly is not necessarily a bad thing as it is also more efficient. 
140  * </p>
141  * 
142  * <p>
143  *    Now create a <code>JpaTester</code> in your test code: 
144  * </p>
145  * <pre>
146  *      &#064;Before
147  *      public void setUp() throws Exception {
148  * 
149  *          // First we create the JpaTester by telling us which persistence unit we
150  *          // are going to test
151  *          jpaTester = new JpaTester(new MyPersistenceUnit());
152  *          jpaTester.start();     
153  *      }
154  * </pre>
155  * 
156  * <p>
157  * Then in test code execute some JPA code within a unit of work: 
158  * </p>
159  * <pre>
160  *      jpaTester.getJpaBuilder().execute(new JpaUnitOfWork<Void>() {
161  *          public Void execute(EntityManager aEm) {
162  *              MyEntity entity = new MyEntity("a", "b");
163  *              aEm.persist(entity);
164  *              return null;
165  *          }
166  *      });
167  * </pre>
168  * 
169  * <a name="db-jpa-plus-jdbc">
170  *   <h2>JPA testing combined with JDBC and DBUnit</h2>
171  * </a>
172  * <p>The <code>JPATester</code> provides access to all required object. It is usually convenient to 
173  * get them directly from the <code>JPATester</code> after initializing it: 
174  * <pre>
175  *      builder = jpaTester.getJpaBuilder();
176  *      dbutils = jpaTester.getDbUtils();
177  *      dbtester = dbutils.createDbTester(new MyTables());
178  * </pre>
179  * 
180  * <a name="db-jpa-services">
181  *   <h2>Testing a service that requires a transaction</h2>
182  * </a>
183  * 
184  * <p>Using {@link TransactionProxyFactory} it is possible to create a proxy for a given
185  * service interface to provide the semantics of 'requires new' transaction semantics. 
186  * <pre>
187  *      TransactionProxyFactory<Service> factory = new TransactionProxyFactory<Service>(
188  *           jpaTester.getJpaBuilder(), Service.class);
189  *      Service service = new ServiceImpl(factory.getTransactionScopedEntityManager()); 
190  *      Service proxy = factory.getProxy(service);
191  *      proxy.execute(...);
192  * </pre>
193  * 
194  * <p>
195  * In the above example, the <code>Service</code> POJO requires an {@link EntityManager} in its 
196  * constructor and it is passed a transaction scoped entitymanager from the factory. This entitymanager
197  * is in fact a so-called contextual reference.
198  * Next, the proxy is obtained from the factory. Invoking any method on it will make sure a new 
199  * transaction is started and a new entity manager is created for the scope of that transaction.
200  * </p> 
201  * 
202  * <a name="design-overview">
203  *   <h2>Design overview</h2>
204  * </a>
205  * 
206  * <h3>Database transparency</h3>
207  * 
208  * <br/>
209  * <img src="doc-files/Class_Diagram__org.wamblee.support.persistence__database.jpg"
210  *   alt="database"/>
211  * </br/>
212  * <p>
213  *   {@link DatabaseProvider} uses <code>java.util.ServiceLoader</code> to find all implementations
214  *   of {@link DatabaseProvider} on the classpath. It then asks the database providers whether
215  *   they support the required capabilities (by default inmemory), and the first provider that 
216  *   supports the capabilities is used to create the database. 
217  * </p>
218  * <p>
219  *   Note that the <code>Database</code> interface is not intended to always create a database. 
220  *   It will do so for {@link DerbyDatabase} (inmemory), but with {@link ExternalDatabase}
221  *   it simply connects to an external database based on system properties or environment 
222  *   variables. 
223  * </p>
224  *  
225  * <h3>JPA tester overview</h3>
226  * 
227  * <br/>
228  * <img src="doc-files/Class_Diagram__org.wamblee.support.persistence__jpatester.jpg"
229  *   alt="database"/>
230  * </br/>
231  * 
232  * <p><code>JPATester</code> is responsible for:</p>
233  * <ul>
234  *   <li> Starting or connecting to a database, using {@link DatabaseBuilder}. 
235  *   </li>
236  *   <li>  Registering the acquired datasource in JNDI by first stubbing JNDI
237  *       using {@link org.wamblee.support.jndi.StubInitialContextFactory}. 
238  *   </li>
239  *   <li>  Creating the {@link JPABuilder} that will do the JPA heavy lifting. 
240  *   </li>
241  *   <li> Creating the {@link DatabaseUtils} for JDBC and DBUnit testing. 
242  *   </li>
243  * </ul> 
244  * 
245  * 
246  */
247 package org.wamblee.test.persistence;
248
249