= 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.
