| Title: Application discovery via the classpath |
| This document details the various ways to get OpenEJB to detect |
| applications you would like deployed while in an embedded mode. |
| |
| <a name="Applicationdiscoveryviatheclasspath-Emptyejb-jar.xmlapproach(recommended)"></a> |
| # Empty ejb-jar.xml approach (recommended) |
| |
| Simplify the issue of searching for annotated applications by adding an |
| ejb-jar.xml like this to your app: |
| |
| <ejb-jar/> |
| |
| |
| OpenEJB will find the app in the classpath and deploy it along with any |
| annotated beans it may contain. |
| |
| The ejb-jar.xml can contain more than just "<ejb-jar/>" as usual. |
| |
| This is the recommended approach for people using OpenEJB for unit testing |
| as it allows OpenEJB to find your application in the classpath without the |
| need for you to specify any path information which tends to complicate |
| builds. |
| |
| # Including/Excluding paths (advanced) |
| |
| If you do not like the idea of having the ejb-jar.xml in your app or an |
| openejb.xml, we can search the classpath for annotated beans (@Stateless, |
| @Stateful, @MessageDriven) and load them automatically just as if they |
| contained an ejb-jar.xml. |
| |
| This form of searching, however, is very expensive as it involves iterating |
| over every path in the classpath and reading in each class definition |
| contained thereunder and checking it for annotations. |
| |
| This approach can only be made faster by helping us trim down or pinpoint |
| the paths we should search via the *openejb.deployments.classpath.include* |
| property which can be specified as a _system property_ or a property passed |
| into the _InitialContext_. |
| |
| The value of this property is a regular expression and therefore can be |
| absolute or relative. For example the path |
| "/Users/dblevins/work/swizzle/swizzle-stream/target/classes" which contains |
| the class files of an application you wish to test could be included in any |
| of the following values to the "openejb.deployments.classpath.include" |
| property: |
| |
| * "file:///Users/dblevins/work/swizzle/swizzle-stream/target/classes/" _(an absolute path)_ |
| * "file:///Users/dblevins/work/swizzle/.*" _(relative)_ |
| * ".\*swizzle-stream.\*" _(very relative)_ |
| * ".\*(swizzle-stream|swizzle-jira|acme-rocket-app).\*" _(including several paths)_ |
| * ".\*(swizzle-stream^|swizzle-jira^|acme-rocket-app).\*" _(including several paths with Win specific escapes)_ |
| |
| Note the filtering is done on URLs in the classpath, so forward slashes |
| should always be used even on OSs using backslash ("\"). |
| |
| There are also the *openejb.deployments.classpath.exclude* and *openejb.exclude-include.order* |
| properties if you wish to work in the opposite direction or change the processing order. |
| The default values for the properties are as follows: |
| |
| openejb.exclude-include.order=include-exclude //Defines the processing order |
| openejb.deployments.classpath.include="" //Include nothing |
| openejb.deployments.classpath.exclude=".*" //Exclude everything |
| |
| The exclude and the include are applied separately and the results of each |
| are combined together to create the list of paths OpenEJB will scrape for |
| annotations. |
| |
| *Note:* by default these settings will only affect which jars OpenEJB will |
| scan for annotated components when no descriptor is found. If you would |
| like to use these settings to also filter out jars that do contain |
| descriptors, set the *openejb.deployments.classpath.filter.descriptors* |
| property to _true_. The default is _false_. |
| |
| # Troubleshooting |
| |
| If the include/exclude is not being processed as you expect first try |
| reversing the order to *openejb.exclude-include.order*=exclude-include |
| There are a number internal filters that may result in an unexpected exclusion. |
| |
| If you're having trouble determining if the META-INF/ejb-jar.xml file for |
| your ejb module is in the classpath, a little debug code like this in your |
| test setup will help you see what OpenEJB sees (which may be nothing): |
| |
| |
| Enumeration<URL> ejbJars = |
| this.getClass().getClassLoader().getResources("META-INF/ejb-jar.xml"); |
| while (ejbJars.hasMoreElements()) { |
| URL url = ejbJars.nextElement(); |
| System.out.println("app = " + url); |
| } |
| |