From 19a8abda820542a368263df5600f0e90eb556179 Mon Sep 17 00:00:00 2001 From: Richard Zowalla Date: Sat, 21 Nov 2026 09:52:33 +0100 Subject: [PATCH] Document @Resource injection pitfall for resources declared in an EAR Inside an EAR, the resources of the EAR's META-INF/resources.xml are registered under ids prefixed with the application name. A plain @Resource relying on the field name does not match the prefixed id, so TomEE falls back to the first resource of the requested type, logging it at DEBUG only. With several resources of the same type every field silently receives the same instance. Documents the behavior and the two ways to name the resource explicitly (lookup = "openejb:Resource/" or name = "/"), and mentions where the EAR-level resources.xml goes. (cherry picked from commit d78d706fabfebade4e8eef6b73c47eebfc938ac5) --- docs/admin/configuration/application.adoc | 5 ++ docs/application-resources.adoc | 57 ++++++++++++++++++++++- 2 files changed, 61 insertions(+), 1 deletion(-) diff --git a/docs/admin/configuration/application.adoc b/docs/admin/configuration/application.adoc index 4f3edb0f45a..7357fdc6a5b 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