| Title: Alternate Descriptors |
| As of OpenEJB 3.1.1, you have the ability to specify an alternate set of |
| deployment descriptors to use for a given environment. This is focused |
| mostly on testing where it is often desirable to use a slightly different |
| configuration for a set of tests or even a specific test. |
| |
| # When nothing else does the trick |
| |
| Note that this approach was added as a catch-all for when one of the |
| simpler overriding techniques will not work. For the common case of |
| needing to tweak your persistence.xml, see the [Configuring PersistenceUnits in Tests](configuring-persistenceunits-in-tests.html) |
| page for a simpler approach. |
| |
| For many reasons it is very inconvenient to have to maintain two sets of |
| descriptors, one for production and one for testing. We aggressively add |
| features based on user feedback and questions. If you are looking for a |
| way to solve a problem without duplicating entire descriptors, please let |
| us know. You should never have to go the long way to do something simple. |
| |
| <a name="AlternateDescriptors-openejb.altdd.prefix"></a> |
| # openejb.altdd.prefix |
| |
| To use this functionality, just set the new "openejb.altdd.prefix" system |
| property or `InitialContext` property to something like "_test_", then any |
| descriptors in your META-INF/ directory that start with "_test._" will |
| override the regular descriptor. So for example with an app like this: |
| |
| - META-INF/ejb-jar.xml |
| - META-INF/*test*.ejb-jar.xml |
| - META-INF/persistence.xml |
| - META-INF/*test*.env-entry.properties |
| |
| Just initialize your test case like so: |
| |
| |
| Properties properties = new Properties(); |
| properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, |
| "org.apache.openejb.client.LocalInitialContextFactory"); |
| properties.setProperty("openejb.altdd.prefix", "test"); |
| |
| InitialContext initialContext = new InitialContext(properties); |
| |
| |
| The logical result will be the prefixed file replacing the non-prefixed |
| file as the active descriptor: |
| |
| - META-INF/ejb-jar.xml -> *test*.ejb-jar.xml |
| - META-INF/persistence.xml |
| - META-INF/env-entry.properties -> *test*.env-entry.properties |
| |
| This will work in any environment in which OpenEJB works (embedded, |
| standalone, tomcat, geronimo, etc.). |
| |
| Note that there does *not* have to be an equivalent non-prefixed version of |
| the file. In the example above, only a "test.env-entry.properties" file |
| exists and there is no equivalent plain "env-entry.properties" file. This |
| prefixing works for any deployment descriptor in the META-INF/ directory or |
| WEB-INF/ directory. The prefix does not have to be "test" and could be |
| anything you choose. You can also have as many prefixed files as you need |
| and could even go as far as to have one prefix per individual test. |
| |
| <a name="AlternateDescriptors-Morethanoneprefix"></a> |
| # More than one prefix |
| |
| It is possible to have several prefixes, specified in order of preference, |
| so that it is possible to avoid duplicating descriptors that are used in |
| more than one "profile". For example, the "foo" test case uses the same |
| "env-entries.properties" file as the "bar" test case, but both have their |
| own ejb-jar.xml files: |
| |
| - META-INF/ejb-jar.xml |
| - META-INF/test.ejb-jar.xml |
| - META-INF/footest.ejb-jar.xml |
| - META-INF/bartest.ejb-jar.xml |
| - META-INF/persistence.xml |
| - META-INF/test.env-entry.properties |
| |
| The "foo" test case could set the _openejb.altdd.prefix_ as follows: |
| |
| |
| //... |
| properties.setProperty("openejb.altdd.prefix", "footest, test"); |
| |
| InitialContext initialContext = new InitialContext(properties); |
| |
| |
| Resulting the following logical view of the app: |
| |
| - META-INF/ejb-jar.xml -> *footest*.ejb-jar.xml |
| - META-INF/persistence.xml |
| - META-INF/env-entry.properties -> test.env-entry.properties |
| |
| And the "bar" test case could set the _openejb.altdd.prefix_ as follows: |
| |
| |
| //... |
| properties.setProperty("openejb.altdd.prefix", "footest, test"); |
| |
| InitialContext initialContext = new InitialContext(properties); |
| |
| |
| Resulting the following logical view of the app: |
| |
| - META-INF/ejb-jar.xml -> *bartest*.ejb-jar.xml |
| - META-INF/persistence.xml |
| - META-INF/env-entry.properties -> test.env-entry.properties |
| |
| In both scenarios the same env-entry.properties file |
| (test.env-entry.properties) is shared. |
| |
| Note that there is a "test.ejb-jar.xml" file that is present, however in |
| both cases it is not used as the order of preference in the list is "left |
| to right" meaning most preferred first. |
| |