TechFAQ

The enterprise bean's environment is a mechanism that allows customization of the enterprise bean's business logic during DEPLOYMENT or ASSEMBLY. The enterprise bean's environment allows the enterprise bean to be customized without the need to access or change the enterprise bean's source code.

The Container implements the enterprise bean's environment, and provides it to the enterprise bean instance through the JNDI interfaces. The enterprise bean's environment is used as follows:

Each enterprise bean defines its OWN set of environment entries. All instances of an enterprise bean within the same home share the same environment entries; the environment entries are not shared with other enterprise beans. Enterprise bean instances are NOT ALLOWED to modify the bean's environment at runtime.

Each env-entry element describes a single environment entry. The env-entry element consists of an optional description of the environment entry, the environment entry NAME relative to the java:comp/env context, the expected Java TYPE of the environment entry value (i.e., the type of the object returned from the JNDI lookup method), and an OPTIONAL environment entry VALUE.

<!--
The env-entry element contains the declaration of an enterprise
bean's environment entry. The declaration consists of an optional
description, the name of the environment entry, and an optional value.
If a value is not specified, one must be supplied during deployment.
Used in: entity, message-driven, and session
-->

<!ELEMENT env-entry (description?, env-entry-name, env-entry-type,
		env-entry-value?)>

					

An environment entry is scoped to the enterprise bean whose declaration contains the env-entry element. This means that the environment entry is INACCESSIBLE from other enterprise beans at runtime, and that other enterprise beans may define env-entry elements with the same env-entry-name without causing a name conflict.

The environment entry values may be one of the following Java types: String, Character, Integer, Boolean, Double, Byte, Short, Long, and Float.

The environment entry value must be a string that is valid for the constructor of the specified type that takes a single String parameter, or for java.lang.Character, a single character.

The ejb-ref element contains an optional description element; and the MANDATORY ejb-ref-name, ejb-ref-type (value must be either Entity or Session), home, and remote elements.

<!--
The ejb-ref element is used for the declaration of a reference to an
enterprise bean's home. The declaration consists of an optional
description; the EJB reference name used in the code of the enterprise
bean that is referencing the enterprise bean; the expected type of the
referenced enterprise bean; the expected home and remote interfaces
of the referenced enterprise bean; and optional ejb-link information,
used to specify the referenced enterprise bean.
Used in: entity, message-driven, and session
-->

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home,
		remote, ejb-link?)>

					

The ejb-local-ref element contains an optional description element; and the MANDATORY ejb-ref-name, ejb-ref-type (value must be either Entity or Session), local-home, and local elements.

<!--
The ejb-local-ref element is used for the declaration of a reference
to an enterprise bean's local home. The declaration consists of an
optional description; the EJB reference name used in the code of the
enterprise bean that is referencing the enterprise bean; the expected
type of the referenced enterprise bean; the expected local home and
local interfaces of the referenced enterprise bean; and optional
ejb-link information, used to specify the referenced enterprise bean.
Used in: entity, session, message-driven
-->

<!ELEMENT ejb-local-ref (description?, ejb-ref-name, ejb-ref-type,
		local-home, local, ejb-link?)>

					

The ejb-ref-name element specifies the EJB reference name; its value is the environment entry name used in the enterprise bean CODE.

An EJB REFERENCE is scoped to the enterprise bean whose declaration contains the ejb-ref or ejb-local-ref element. This means that the EJB reference is NOT ACCESSIBLE to other enterprise beans at runtime, and that other enterprise beans may define ejb-ref and/or ejb-local-ref elements with the same ejb-ref-name without causing a name conflict.

A RESOURCE MANAGER CONNECTION FACTORY is an object that is used to create connections to a resource manager. For example, an object that implements the javax.sql.DataSource interface is a resource manager connection factory for java.sql.Connection objects which implement connections to a database management system.

Each resource-ref element describes a single resource manager connection factory reference. The resource-ref element consists of the description element; the THREE mandatory res-ref-name, res-type, and res-auth elements; and the optional res-sharing-scope element. The res-ref-name element contains the name of the environment entry used in the enterprise bean's CODE. The name of the environment entry is relative to the java:comp/env context (e.g., the name should be jdbc/EmployeeAppDB rather than java:comp/env/jdbc/EmployeeAppDB). The res-type element contains the Java type of the resource manager connection FACTORY. The res-auth element indicates whether the enterprise BEAN CODE performs resource manager sign-on PROGRAMMATICALLY, or whether the Container signs on to the resource manager using the principal mapping information supplied by the Deployer. The Bean Provider indicates the sign-on responsibility by setting the value of the res-auth element to Application or Container. The res-sharing-scope element indicates whether connections to the resource manager obtained through the given resource manager connection factory reference can be shared (by default) or whether connections are unshareable.

A resource manager connection factory reference is scoped to the enterprise bean whose declaration contains the resource-ref element. This means that the resource manager connection factory reference is not accessible from other enterprise beans at runtime, and that other enterprise beans may define resource-ref elements with the same res-ref-name without causing a name conflict.

<!--
The resource-ref element contains a declaration of enterprise bean's
reference to an external resource. It consists of an optional description,
the resource manager connection factory reference name, the
indication of the resource manager connection factory type expected
by the enterprise bean code, the type of authentication (Application
or Container), and an optional specification of the shareability of
connections obtained from the resource (Shareable or Unshareable).
Used in: entity, message-driven, and session

Example:

<resource-ref>
	<res-ref-name>jdbc/EmployeeAppDB</res-ref-name>
	<res-type>javax.sql.DataSource</res-type>
	<res-auth>Container</res-auth>
	<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
-->

<!ELEMENT resource-ref (description?, res-ref-name, res-type,
		res-auth, res-sharing-scope?)>

					

The Bean Provider is allowed to refer to administered objects that are associated with resources (for example, JMS Destinations) by using "logical" names called RESOURCE ENVIRONMENT REFERENCES. Resource environment references are special entries in the enterprise bean's environment.

Each resource-env-ref element describes the requirements that the referencing enterprise bean has for the referenced administered object. The resource-env-ref element contains an optional description element; and the MANDATORY resource-env-ref-name and resource-env-ref-type elements.

The resource-env-ref-name element specifies the resource environment reference name; its value is the environment entry name used in the enterprise bean CODE. The name of the environment entry is relative to the java:comp/env context (e.g., the name should be jms/StockQueue rather than java:comp/env/jms/StockQueue). The resource-env-ref-type element specifies the expected type of the referenced object. For example, in the case of a JMS Destination, its value must be either javax.jms.Queue or javax.jms.Topic.

<!--
The resource-env-ref element contains a declaration of an enterprise
bean's reference to an administered object associated with a resource
in the enterprise bean's environment. It consists of an optional
description, the resource environment reference name, and an indication
of the resource environment reference type expected by the enterprise
bean code.
Used in: entity, message-driven and session

Examples:

<resource-env-ref>
	<resource-env-ref-name>jms/StockQueue</resource-env-ref-name>
	<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>

-->
<!ELEMENT resource-env-ref (description?, resource-env-ref-name,
		resource-env-ref-type)>