diff --git a/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml b/openjpa-project/src/doc/manual/ref_guide_dbsetup.xml
index 9908d0363..0572b2b8a 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.
+
+
+
+