| = Basics - Getting Things | |
| :index-group: Unrevised | |
| :jbake-date: 2018-12-05 | |
| :jbake-type: page | |
| :jbake-status: published | |
| = Getting Stuff from the Container | |
| Generally speaking the only way to get a | |
| Container-Managed Resource is via | |
| _dependency injection_ or _lookup_ from within a Container-Managed | |
| Component. | |
| The _unbreakable rules_. Read these over and over again when things | |
| don't work. | |
| [arabic] | |
| . java:comp/env is the spec defined namespace for lookup of any | |
| Container-Managed Resource | |
| . java:comp/env is _empty_ by default | |
| . java:comp/env is _read-only_ at runtime | |
| . java:comp/env is populated by link:declaring-references.html[Declaring | |
| References] to a Container-Managed Resource via xml or annotation | |
| . only Container-Managed Components, _not_ their libraries, can | |
| link:declaring-references.html[Declare References] via xml or annotation | |
| . only Container-Managed Components, _not_ their libraries, can get | |
| dependency injection of Container-Managed Resources | |
| . only Container-Managed Components, _and_ their libraries, may look up | |
| from java:comp/env | |
| . you _must_ use the _no-arg_ 'new InitialContext()' constructor to | |
| lookup something from java:comp/env | |
| . the annotations and xml for link:declaring-references.html[Declaring | |
| References] are _identical_ in functionality, both _always_ configure | |
| lookup with _optional_ dependency injection | |
| == Common mistakes, misunderstandings, and myths | |
| * __"I tried it via annotation, and it didn't work, so I used xml and | |
| then it did work"__ | |
| See rule 9. If one form worked and the other didn't, it means you simply | |
| made a mistake in using one versus the other. Use what works for you, | |
| but understand both annotations or xml will work for either lookup or | |
| injection if used correctly. | |
| * __"I need to use lookups, so I can't use the annotation"__ | |
| See rule 9. Annotations are not just for injection, that is just how | |
| they are typically used. Know that when you use an annotation for | |
| injection, it will _always_ create an entry in java:comp/env. As well | |
| you can use the annotation at the _class level_ and it will cause no | |
| dependency injection and only the entry creation in java:comp/env. | |
| * __"I don't want injection, so I can't use the annotation"__ | |
| See rule 9 and the above. You can use the annotation at the _class | |
| level_ and it will cause no dependency injection and only the entry | |
| creation in java:comp/env. | |
| * __"I tried to list java:comp/env but it's empty?!"__ | |
| See rule 2 and rule 4. There will be nothing in java:comp/env unless you | |
| link:declaring-references.html[Declare a Reference] to it. It does not | |
| matter if is a DataSource configured at the server level, etc. Nothing | |
| is bound into java:comp/env unless you explicitly declare a reference to | |
| it. The Java EE 5 TCK (Technology Compatibility Kit) tests for this | |
| extensively and is a rule we cannot break. Java EE 6 does finally offer | |
| some new namesaces (java:global, java:app, and java:module) which will | |
| offer some great new options for more global-style lookups. | |
| * __"I deployed the EJB but can't look it up, it's name is Foo"__ | |
| See rule 2 and the above. Just creating an EJB doesn't cause it to be | |
| added to java:comp/env. If a | |
| Container-Managed Component wants | |
| to look up the EJB they must link:declaring-references.html[Declare a Reference] | |
| to it via the `@EJB` annotation or <ejb-local-ref> or <ejb-ref> in xml. | |
| In Java EE 6, however, EJBs will be automatically bound to | |
| "java:global[/<app-name>]/<module-name>/<bean-name>[!<fully-qualified-interface-name>]" | |
| and can be looked up without declaring a reference first. | |
| * __"Which InitialContextFactory do I use for java:comp/env?"__ | |
| See rule 8. You are not allowed to use an InitialContextFactory for | |
| java:comp/env lookups. Setting an InitialContextFactory via | |
| 'java.naming.factory.initial' in either System properties, | |
| InitialContext properties, or a jndi.properties file is illegal and will | |
| cause java:comp/env lookups to fail. | |
| * __"My Client can't look up the EJB from java:comp/env"__ | |
| See rule 7. A plain, standalone, Java application cannot use | |
| java:comp/env. There is the official concept of a Java EE Application | |
| Client which can be packaged in an ear and deployed into the Container. | |
| In practice, most people find them restrictive, cumbersome, and hard to | |
| use and are therefore rarely employed in "real world" projects. Most | |
| people opt to use the non-standard, vendor-specific, approach to looking | |
| up EJBs from their plain java clients. In OpenEJB this can be done via | |
| either the RemoteInitialContextFactory (for remote clients) or the | |
| LocalInitialContextFactory (for local clients of an embedded container). | |
| The JNDI names can be configured as link:jndi-names.html[shown here] . | |
| * __"I declared the reference, but still can't look it up"__ | |
| See all of the above and reread the rules a few times. Always check the | |
| log output as well. |