docs/configuring-persistenceunits-in-tests.adoc

= Configuring PersistenceUnits in Tests
:index-group: Testing Techniques
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published

= Overriding the
persistence.xml

The most common situation in EJB related testing by far is the need to
alter your persistence.xml for a test environment.

== Overriding the jta-data-source and non-jta-data-source

OpenEJB will automatically use the DataSources you have setup in your
test environment, we're pretty good at guessing the right DataSources
you intend even if the names don't match exactly -- or in some cases at
all. If there is only one DataSource configured, it's very easy for us
to guess the DataSource to use.

This allows you to keep your persistence.xml configured for your
production environment and helps eliminate the need for a "test"
persistence.xml (though we do have that functionality). A log line will
be printed saying if we had to adjust the DataSources of your
persistence.xml.

== Overriding the persistence-unit properties

You can override any property in your test setup via either system
properties or the initial context properties. The format is:

`<unit-name>.<property>=<value>`

So for example with the following persistence.xml:

[source,xml]
----
<persistence>
  <persistence-unit name="movie-unit">
    <provider>org.hibernate.ejb.HibernatePersistence</provider>
    <jta-data-source>movieDatabase</jta-data-source>
    <non-jta-data-source>movieDatabaseUnmanaged</non-jta-data-source>
    <properties>
      <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      <property name="hibernate.max_fetch_depth" value="3"/>
    </properties>
  </persistence-unit>
</persistence>
----

You can override and add persistence unit properties in your test case.
There are currently no facilities for removing them (if you have a need
for that let us know -- it hasn't really come up so far).

[source,java]
----
Properties p = new Properties();
p.put(Context.INITIAL_CONTEXT_FACTORY,"org.apache.openejb.client.LocalInitialContextFactory");

p.put("movie-unit.hibernate.hbm2ddl.auto", "update");
p.put("movie-unit.hibernate.dialect", "org.hibernate.dialect.HSQLDialect");

context = new InitialContext(p);
----

The overriding order is as follows: 1 = highest, 4 = lowest.

[arabic]
. InitialContext properties
. jndi.properties from the classpath
. System properties
. persistence.xml properties

By default there are no overrides in 1-3, so #4 is the only source of
information.

In the above example there would be exactly three properties for the
"movie-unit" persistence unit:

* hibernate.hbm2ddl.auto = update
* hibernate.max_fetch_depth = 3
* hibernate.dialect = org.hibernate.dialect.HSQLDialect

These properties would be passed by OpenEJB directly to the persistence
provider (in this case Hibernate). With one exception OpenEJB does not
understand or modify these properties. Details on that one exception
below.

== Common mistakes

Note that you *must* use the *unit name* as the prefix. This will not
work:

[source,java]
----
    Properties p = new Properties();
    p.put(Context.INITIAL_CONTEXT_FACTORY,"org.apache.openejb.client.LocalInitialContextFactory");

    p.put("hibernate.hbm2ddl.auto", "update");
    p.put("hibernate.dialect", "org.hibernate.dialect.HSQLDialect");

    context = new InitialContext(p);
----

Currently, only properties that start with the unit name are search and
applied.

== No need to specify a "transaction lookup" property

All vendors have such a property for getting a reference to the
container's TransactionManager and nothing works if this is not set
correctly to the OpenEJB specific class. To make the lives of users
easier, OpenEJB will take the liberty of setting it for you.

Here are the persistence provider classes we understand and the defaults
we will set for you:

=== Provider org.hibernate.ejb.HibernatePersistence

When using this provider, the
_hibernate.transaction.manager_lookup_class_ will be automatically set
by OpenEJB to _org.apache.openejb.hibernate.TransactionManagerLookup_.
If the property is already set in the persistence unit it will be
overwritten if it starts with the standard "org.hibernate.transaction."
prefix.

Custom lookup implementations will never be overwritten automatically.

=== Provider oracle.toplink.essentials.PersistenceProvider

Or _oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider_.

When using this provider, the _toplink.target-server_ will be
automatically set by OpenEJB to
_org.apache.openejb.toplink.JTATransactionController_. If the property
is already set in the persistence unit it will be overwritten if it
starts with the standard "oracle.toplink.transaction." prefix.

Custom transaction controller implementations will never be overwritten
automatically.

=== Provider org.eclipse.persistence.jpa.PersistenceProvider

Or _org.eclipse.persistence.jpa.osgi.PersistenceProvider_.

When using this provider, the _eclipselink.target-server_ will be
automatically set by OpenEJB to
_org.apache.openejb.eclipselink.JTATransactionController_. If the
property is already set in the persistence unit it will be overwritten
if it starts with the standard "org.eclipse.persistence.transaction."
prefix.

Custom transaction controller implementations will never be overwritten
automatically.

=== Provider org.apache.openjpa.persistence.PersistenceProviderImpl

OpenJPA is capable of discovering the correct method for locating the
TransactionManager without the need for users to specify the specific
strategy. Therefore no specific "magic" is required.