diff --git a/docs/admin/configuration/application.adoc b/docs/admin/configuration/application.adoc index 0e9fad28cda..4b0ea7cae80 100644 --- a/docs/admin/configuration/application.adoc +++ b/docs/admin/configuration/application.adoc @@ -98,3 +98,8 @@ Typically, if your application is named `myapp` and your resource id is `myresou as `myresource`, it will get registered as `myapp/myresource`. If you get any ambiguity in resource name matching try to fully qualified your resource prefixing it with the application name. + +Inside an EAR, a plain `@Resource` whose name is just the resource id (or the field name) does not match the prefixed +id. TomEE then injects the first resource of the requested type instead, without an error. If an EAR declares several +resources of the same type, name them explicitly, for instance with `@Resource(lookup = "openejb:Resource/myresource")`. +See link:../../application-resources.html#ear-resource-injection[Injecting resources declared in an EAR]. diff --git a/docs/application-resources.adoc b/docs/application-resources.adoc index 21f04e59036..e0b0629c9ca 100644 --- a/docs/application-resources.adoc +++ b/docs/application-resources.adoc @@ -211,7 +211,9 @@ accessed via properties.getProperty("username"); Resources can also be defined within an application, and optionally use classes from the application's classpath. To define resources in a .war file, include a `WEB-INF/resources.xml`. For an ejb-jar module, use -`META-INF/resources.xml`. +`META-INF/resources.xml`. For an .ear file, use the `META-INF/resources.xml` +of the EAR itself; read <> +before injecting those. The format of `resources.xml` uses the same `` tag as `tomee.xml`. One key difference is the root element of the XML is @@ -235,6 +237,59 @@ application, alongside your application code, rather than requiring a Application resources are bound in JNDI under openejb:Resource/appname/resource id. +[[ear-resource-injection]] +=== Injecting resources declared in an EAR + +Inside an EAR, TomEE registers each resource of the EAR's +`META-INF/resources.xml` under its id prefixed with the application name, +for example `myapp/stopWords` for `` in +`myapp.ear`. A plain `@Resource` without a matching name relies on the +field name instead: + +[source,java] +---- +@Stateless +public class TextService { + + @Resource // looked up as "stopWords", but the resource is registered as "myapp/stopWords" + private WordFilter stopWords; + + @Resource // looked up as "medicalWords", registered as "myapp/medicalWords" + private WordFilter medicalWords; +} +---- + +The field name does not match the prefixed id. TomEE then falls back to +the *first resource of the requested type* and only logs this at `DEBUG` +level. As long as the application defines a single resource of that type, +the result is still right. With several resources of the same type, every +field silently receives the same instance: in the example above both +`stopWords` and `medicalWords` get whichever `WordFilter` resource is +listed first. Deployment succeeds, and the application simply works with +the wrong configuration. + +This happens whether the EAR is deployed at startup (for example from +`apps/`) or at runtime, and setting `Lazy` does not change it. The same +code works where resources are registered without that prefix, such as +resources from `tomee.xml` or tests using the ApplicationComposer, so the +problem often only shows up once an application is packaged as an EAR. + +To get the intended resource, name it explicitly, using either of these: + +[source,java] +---- +// works inside and outside an EAR +@Resource(lookup = "openejb:Resource/stopWords") +private WordFilter stopWords; + +// the id as registered; ties the code to the application name "myapp" +@Resource(name = "myapp/stopWords") +private WordFilter stopWords; +---- + +The `lookup` form is usually the better choice, since it does not depend +on the name of the EAR. + == Additional resource properties Resources are typically discovered, created, and bound to JNDI very