From e65477c9fa66bb97ec4a09d41d17345f04a59980 Mon Sep 17 00:00:00 2001 From: Michael Dick Date: Thu, 22 Jul 2010 15:05:43 +0000 Subject: [PATCH] OPENJPA-1742: add documentation git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@966701 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/doc/manual/ref_guide_dbsetup.xml | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) diff --git a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml index 6c557adfa..eaf74633b 100644 --- a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml +++ b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml @@ -370,6 +370,111 @@ properties are outlined in . +
+ Setting the DataSource at runtime + + connections + override configuration + + +As mentioned above, the JTA and Non-JTA DataSources may be passed in as configuration properties +at EntityManagerFactory creation. Either the JPA standard properties ( +javax.persistence.jtaDataSource, java.persistence.nonJtaDataSource) +or their OpenJPA specific equivalents (openjpa.ConnectionFactoryName, +openjpa.ConnectionFactory2Name) may be used. One usecase for this function is to +store production connection information in configuration files but override the value when testing. + + + + Map<Object,Object> props = new HashMap<Object,Object>(); +props.put("javax.persistence.jtaDataSource", "jdbc/myDataSource"); +props.put("javax.persistence.nonJtaDataSource", "jdbc/myNonJTADataSource"); +emf = Persistence.createEntityManagerFactory("example", props); + + +
+ Using different datasources for each EntityManager + +The JPA specification allows the DataSource (ConnectionFactory) to be specified on the +EntityManagerFactory.OpenJPA extends this support and allows each EntityManager to override the +DataSource from the EntityManagerFactory. It's expected that the EntityManagerFactory will also be +configured with a valid jta / nonJta DataSource. The DataSource configured on the +EntityManagerFactory will be used to obtain a DBDictionary and (rarely) to gather some information +about the database in use (e.g. version, JDBC driver version). + + + If the EntityManagerFactory is not configured with a valid DataSource there are + a few additional caveats. + + The openjpa.DBDictionary property must be + used to ensure the correct DBDictionary is used. + OpenJPA will always attempt to obtain a datasource from JNDI + based on the configuration for the EntityManagerFactory. When a JNDI name is + specified on the EntityManager this lookup happens slightly earlier than + normal. If the lookup fails the JNDI name provided at EntityManager creation + will be set into the EntityManagerFactory's configuration and used in + subsequent attempts. + + +
+ Benefits + + In effect this option allows a single set of entity definitions to be shared + between multiple database instances or schemas within an instance. This can be + highly beneficial when there are a large number of entity definitions (e.g. > + 200), or a large number of databases / schemas in use. + +
+
+ Limitations + + + + The same database type and version must be used by each + EntityManager. OpenJPA will use the same DBDictionary for each + EntityManager and will make no attempt to alter SQL syntax + between EntityManager instances. + + + It is the application's responsibility to ensure + that the schema is identical on each database. + The application may not specify schema names for + individual entities. + + The DataSource (ConnectionFactory) name may only be + specified when the EntityManager is created. The datasource + may not be switched while an EntityManager is in use. + + + The L2 cache (DataCache) should not be used if + different DataSources are specified for each EntityManager + + SynchronizeMappings should not be used with this + feature. + Table and Sequence generators should not be used + with this feature. + It is not required, but is recommended that the + openjpa.DBDictionary property be specified when + using this feature + + +
+
+ Error handling + + If a JTA DataSource is not available when the EntityManager is created an + ArgumentException will be thrown. + The EntityManager will not fall back on the JTA DataSource defined in the + configuration. + + + The same logic applies if a Non-JTA DataSource is not available when the + EntityManager is created. OpenJPA will not fall back to the configured + non-JTA DataSource. + +
+
+