-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification
6.6. J2EE and JNDI - The Application Component Environment
- Application component business logic should be coded to access information from its ENC. The component provider uses the standard deployment descriptor for the component to specify the required ENC entries. The entries are declarations of the information and resources the component requires at runtime.
- The container provides tools that allow a deployer of a component to map the ENC references made by the component developer to the deployment environment entity that satisfies the reference.
- The component deployer utilizes the container tools to ready a component for final deployment.
- The component container uses the deployment package information to build the complete component ENC at runtime
javax.naming.InitialContext
object by using the no argument constructor and then looks up the naming environment under the name java:comp/env
. The application component's environment entries are stored directly in the ENC, or in its subcontexts. Example 6.4, “ENC access sample code” illustrates the prototypical lines of code a component uses to access its ENC.
Example 6.4. ENC access sample code
// Obtain the application component's ENC Context iniCtx = new InitialContext(); Context compEnv = (Context) iniCtx.lookup("java:comp/env");
Bean1
cannot access the ENC elements of EJB Bean2
, and vice versa. Similarly, Web application Web1
cannot access the ENC elements of Web application Web2
or Bean1
or Bean2
for that matter. Also, arbitrary client code, whether it is executing inside of the application server VM or externally cannot access a component's java:comp
JNDI context. The purpose of the ENC is to provide an isolated, read-only namespace that the application component can rely on regardless of the type of environment in which the component is deployed. The ENC must be isolated from other components because each component defines its own ENC content. Components A
and B
, for example, may define the same name to refer to different objects. For example, EJB Bean1
may define an environment entry java:comp/env/red
to refer to the hexadecimal value for the RGB color for red, while Web application Web1
may bind the same name to the deployment environment language locale representation of red.
java:comp
, names under java:
, and any other name. As discussed, the java:comp
context and its subcontexts are only available to the application component associated with that particular context. Subcontexts and object bindings directly under java:
are only visible within the JBoss server virtual machine and not to remote clients. Any other context or object binding is available to remote clients, provided the context or object supports serialization. You'll see how the isolation of these naming scopes is achieved in the Section 6.2, “The JBoss Naming Service Architecture”.
java:
context is useful would be a javax.sql.DataSource
connection factory that can only be used inside of the JBoss server where the associated database pool resides. On the other hand, an EJB home interface would be bound to a globally visible name that should accessible by remote client.
6.6.1. ENC Usage Conventions
ejb-jar.xml
deployment descriptor for EJB components, and the standard web.xml
deployment descriptor for Web components. Several different types of information may be stored in and retrieved from JNDI including:
- Environment entries as declared by the
env-entry
elements - EJB references as declared by
ejb-ref
andejb-local-ref
elements. - Resource manager connection factory references as declared by the
resource-ref
elements - Resource environment references as declared by the
resource-env-ref
elements
6.6.1.1. Environment Entries
env-entry
element in the standard deployment descriptors. The env-entry
element contains the following child elements:
- An optional description element that provides a description of the entry
- An env-entry-name element giving the name of the entry relative to
java:comp/env
- An env-entry-type element giving the Java type of the entry value that must be one of:
java.lang.Byte
java.lang.Boolean
java.lang.Character
java.lang.Double
java.lang.Float
java.lang.Integer
java.lang.Long
java.lang.Short
java.lang.String
- An env-entry-value element giving the value of entry as a string
env-entry
fragment from an ejb-jar.xml
deployment descriptor is given in Example 6.5, “An example ejb-jar.xml env-entry fragment”. There is no JBoss specific deployment descriptor element because an env-entry
is a complete name and value specification. Example 6.6, “ENC env-entry access code fragment” shows a sample code fragment for accessing the maxExemptions
and taxRate
and env-entry
values declared in the deployment descriptor.
Example 6.5. An example ejb-jar.xml env-entry fragment
<!-- ... --> <session> <ejb-name>ASessionBean</ejb-name> <!-- ... --> <env-entry> <description>The maximum number of tax exemptions allowed </description> <env-entry-name>maxExemptions</env-entry-name> <env-entry-type>java.lang.Integer</env-entry-type> <env-entry-value>15</env-entry-value> </env-entry> <env-entry> <description>The tax rate </description> <env-entry-name>taxRate</env-entry-name> <env-entry-type>java.lang.Float</env-entry-type> <env-entry-value>0.23</env-entry-value> </env-entry> </session> <!-- ... -->
Example 6.6. ENC env-entry access code fragment
InitialContext iniCtx = new InitialContext(); Context envCtx = (Context) iniCtx.lookup("java:comp/env"); Integer maxExemptions = (Integer) envCtx.lookup("maxExemptions"); Float taxRate = (Float) envCtx.lookup("taxRate");
6.6.1.2. EJB References
java:comp/env/ejb
context of the application component's environment.
ejb-ref
element in the deployment descriptor. Each ejb-ref
element describes the interface requirements that the referencing application component has for the referenced enterprise bean. The ejb-ref
element contains the following child elements:
- An optional description element that provides the purpose of the reference.
- An ejb-ref-name element that specifies the name of the reference relative to the
java:comp/env
context. To place the reference under the recommendedjava:comp/env/ejb
context, use anejb/link-name
form for theejb-ref-name
value. - An ejb-ref-type element that specifies the type of the EJB. This must be either
Entity
orSession
. - A home element that gives the fully qualified class name of the EJB home interface.
- A remote element that gives the fully qualified class name of the EJB remote interface.
- An optional ejb-link element that links the reference to another enterprise bean in the same EJB JAR or in the same J2EE application unit. The
ejb-link
value is theejb-name
of the referenced bean. If there are multiple enterprise beans with the sameejb-name
, the value uses the path name specifying the location of theejb-jar
file that contains the referenced component. The path name is relative to the referencingejb-jar
file. The Application Assembler appends theejb-name
of the referenced bean to the path name separated by#
. This allows multiple beans with the same name to be uniquely identified.
ejb-ref
element. This means that the EJB reference is not accessible from other application components at runtime, and that other application components may define ejb-ref
elements with the same ejb-ref-name
without causing a name conflict. Example 6.7, “An example ejb-jar.xml ejb-ref descriptor fragment” provides an ejb-jar.xml
fragment that illustrates the use of the ejb-ref
element. A code sample that illustrates accessing the ShoppingCartHome
reference declared in Example 6.7, “An example ejb-jar.xml ejb-ref descriptor fragment” is given in Example 6.8, “ENC ejb-ref access code fragment”.
Example 6.7. An example ejb-jar.xml ejb-ref descriptor fragment
<!-- ... --> <session> <ejb-name>ShoppingCartBean</ejb-name> <!-- ...--> </session> <session> <ejb-name>ProductBeanUser</ejb-name> <!--...--> <ejb-ref> <description>This is a reference to the store products entity </description> <ejb-ref-name>ejb/ProductHome</ejb-ref-name> <ejb-ref-type>Entity</ejb-ref-type> <home>org.jboss.store.ejb.ProductHome</home> <remote> org.jboss.store.ejb.Product</remote> </ejb-ref> </session> <session> <ejb-ref> <ejb-name>ShoppingCartUser</ejb-name> <!--...--> <ejb-ref-name>ejb/ShoppingCartHome</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.jboss.store.ejb.ShoppingCartHome</home> <remote> org.jboss.store.ejb.ShoppingCart</remote> <ejb-link>ShoppingCartBean</ejb-link> </ejb-ref> </session> <entity> <description>The Product entity bean </description> <ejb-name>ProductBean</ejb-name> <!--...--> </entity> <!--...-->
Example 6.8. ENC ejb-ref access code fragment
InitialContext iniCtx = new InitialContext(); Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb"); ShoppingCartHome home = (ShoppingCartHome) ejbCtx.lookup("ShoppingCartHome");
6.6.1.3. EJB References with jboss.xml
and jboss-web.xml
jboss.xml
EJB deployment descriptor affects EJB references in two ways. First, the jndi-name
child element of the session
and entity
elements allows the user to specify the deployment JNDI name for the EJB home interface. In the absence of a jboss.xml
specification of the jndi-name
for an EJB, the home interface is bound under the ejb-jar.xml
ejb-name
value. For example, the session EJB with the ejb-name
of ShoppingCartBean
in Example 6.7, “An example ejb-jar.xml ejb-ref descriptor fragment” would have its home interface bound under the JNDI name ShoppingCartBean
in the absence of a jboss.xml
jndi-name
specification.
jboss.xml
descriptor with respect to ejb-ref
s is the setting of the destination to which a component's ENC ejb-ref
refers. The ejb-link
element cannot be used to refer to EJBs in another enterprise application. If your ejb-ref
needs to access an external EJB, you can specify the JNDI name of the deployed EJB home using the jboss.xml
ejb-ref/jndi-name
element.
jboss-web.xml
descriptor is used only to set the destination to which a Web application ENC ejb-ref
refers. The content model for the JBoss ejb-ref
is as follows:
- An ejb-ref-name element that corresponds to the ejb-ref-name element in the ejb-jar.xml or web.xml standard descriptor
- A
jndi-name
element that specifies the JNDI name of the EJB home interface in the deployment environment
jboss.xml
descriptor fragment that illustrates the following usage points:
- The
ProductBeanUser
ejb-ref
link destination is set to the deployment name ofjboss/store/ProductHome
- The deployment JNDI name of the
ProductBean
is set tojboss/store/ProductHome
Example 6.9. An example jboss.xml ejb-ref fragment
<!-- ... --> <session> <ejb-name>ProductBeanUser</ejb-name> <ejb-ref> <ejb-ref-name>ejb/ProductHome</ejb-ref-name> <jndi-name>jboss/store/ProductHome</jndi-name> </ejb-ref> </session> <entity> <ejb-name>ProductBean</ejb-name> <jndi-name>jboss/store/ProductHome</jndi-name> <!-- ... --> </entity> <!-- ... -->
6.6.1.4. EJB Local References
java:comp/env/ejb
context of the application component's environment.
ejb-local-ref
element in the deployment descriptor. Each ejb-local-ref
element describes the interface requirements that the referencing application component has for the referenced enterprise bean. The ejb-local-ref
element contains the following child elements:
- An optional description element that provides the purpose of the reference.
- An ejb-ref-name element that specifies the name of the reference relative to the
java:comp/env
context. To place the reference under the recommendedjava:comp/env/ejb
context, use anejb/link-name
form for theejb-ref-name
value. - An ejb-ref-type element that specifies the type of the EJB. This must be either
Entity
orSession
. - A local-home element that gives the fully qualified class name of the EJB local home interface.
- A local element that gives the fully qualified class name of the EJB local interface.
- An ejb-link element that links the reference to another enterprise bean in the
ejb-jar
file or in the same J2EE application unit. Theejb-link
value is theejb-name
of the referenced bean. If there are multiple enterprise beans with the sameejb-name
, the value uses the path name specifying the location of theejb-jar
file that contains the referenced component. The path name is relative to the referencingejb-jar
file. The Application Assembler appends theejb-name
of the referenced bean to the path name separated by#
. This allows multiple beans with the same name to be uniquely identified. Anejb-link
element must be specified in JBoss to match the local reference to the corresponding EJB.
ejb-local-ref
element. This means that the EJB local reference is not accessible from other application components at runtime, and that other application components may define ejb-local-ref
elements with the same ejb-ref-name
without causing a name conflict. Example 6.10, “An example ejb-jar.xml ejb-local-ref descriptor fragment” provides an ejb-jar.xml
fragment that illustrates the use of the ejb-local-ref
element. A code sample that illustrates accessing the ProbeLocalHome
reference declared in Example 6.10, “An example ejb-jar.xml ejb-local-ref descriptor fragment” is given in Example 6.11, “ENC ejb-local-ref access code fragment”.
Example 6.10. An example ejb-jar.xml ejb-local-ref descriptor fragment
<!-- ... --> <session> <ejb-name>Probe</ejb-name> <home>org.jboss.test.perf.interfaces.ProbeHome</home> <remote>org.jboss.test.perf.interfaces.Probe</remote> <local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home> <local>org.jboss.test.perf.interfaces.ProbeLocal</local> <ejb-class>org.jboss.test.perf.ejb.ProbeBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Bean</transaction-type> </session> <session> <ejb-name>PerfTestSession</ejb-name> <home>org.jboss.test.perf.interfaces.PerfTestSessionHome</home> <remote>org.jboss.test.perf.interfaces.PerfTestSession</remote> <ejb-class>org.jboss.test.perf.ejb.PerfTestSessionBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> <ejb-ref> <ejb-ref-name>ejb/ProbeHome</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <home>org.jboss.test.perf.interfaces.SessionHome</home> <remote>org.jboss.test.perf.interfaces.Session</remote> <ejb-link>Probe</ejb-link> </ejb-ref> <ejb-local-ref> <ejb-ref-name>ejb/ProbeLocalHome</ejb-ref-name> <ejb-ref-type>Session</ejb-ref-type> <local-home>org.jboss.test.perf.interfaces.ProbeLocalHome</local-home> <local>org.jboss.test.perf.interfaces.ProbeLocal</local> <ejb-link>Probe</ejb-link> </ejb-local-ref> </session> <!-- ... -->
Example 6.11. ENC ejb-local-ref access code fragment
InitialContext iniCtx = new InitialContext(); Context ejbCtx = (Context) iniCtx.lookup("java:comp/env/ejb"); ProbeLocalHome home = (ProbeLocalHome) ejbCtx.lookup("ProbeLocalHome");
6.6.1.5. Resource Manager Connection Factory References
resource-ref
elements in the standard deployment descriptors. The Deployer
binds the resource manager connection factory references to the actual resource manager connection factories that exist in the target operational environment using the jboss.xml
and jboss-web.xml
descriptors.
resource-ref
element describes a single resource manager connection factory reference. The resource-ref
element consists of the following child elements:
- An optional description element that provides the purpose of the reference.
- A res-ref-name element that specifies the name of the reference relative to the
java:comp/env
context. The resource type based naming convention for which subcontext to place theres-ref-name
into is discussed in the next paragraph. - A res-type element that specifies the fully qualified class name of the resource manager connection factory.
- A res-auth element that indicates whether the application component code performs resource signon programmatically, or whether the container signs on to the resource based on the principal mapping information supplied by the Deployer. It must be one of
Application
orContainer
. - An optional res-sharing-scope element. This currently is not supported by JBoss.
- JDBC
DataSource
references should be declared in thejava:comp/env/jdbc
subcontext. - JMS connection factories should be declared in the
java:comp/env/jms
subcontext. - JavaMail connection factories should be declared in the
java:comp/env/mail
subcontext. - URL connection factories should be declared in the
java:comp/env/url
subcontext.
web.xml
descriptor fragment that illustrates the resource-ref
element usage. Example 6.13, “ENC resource-ref access sample code fragment” provides a code fragment that an application component would use to access the DefaultMail
resource declared by the resource-ref
.
Example 6.12. A web.xml resource-ref descriptor fragment
<web> <!-- ... --> <servlet> <servlet-name>AServlet</servlet-name> <!-- ... --> </servlet> <!-- ... --> <!-- JDBC DataSources (java:comp/env/jdbc) --> <resource-ref> <description>The default DS</description> <res-ref-name>jdbc/DefaultDS</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref> <!-- JavaMail Connection Factories (java:comp/env/mail) --> <resource-ref> <description>Default Mail</description> <res-ref-name>mail/DefaultMail</res-ref-name> <res-type>javax.mail.Session</res-type> <res-auth>Container</res-auth> </resource-ref> <!-- JMS Connection Factories (java:comp/env/jms) --> <resource-ref> <description>Default QueueFactory</description> <res-ref-name>jms/QueueFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <res-auth>Container</res-auth> </resource-ref> <web>
Example 6.13. ENC resource-ref access sample code fragment
Context initCtx = new InitialContext(); javax.mail.Session s = (javax.mail.Session) initCtx.lookup("java:comp/env/mail/DefaultMail");
6.6.1.6. Resource Manager Connection Factory References with jboss.xml and jboss-web.xml
jboss.xml
EJB deployment descriptor and jboss-web.xml
Web application deployment descriptor is to provide the link from the logical name defined by the res-ref-name
element to the JNDI name of the resource factory as deployed in JBoss. This is accomplished by providing a resource-ref
element in the jboss.xml
or jboss-web.xml
descriptor. The JBoss resource-ref
element consists of the following child elements:
- A res-ref-name element that must match the
res-ref-name
of a correspondingresource-ref
element from theejb-jar.xml
orweb.xml
standard descriptors - An optional res-type element that specifies the fully qualified class name of the resource manager connection factory
- A jndi-name element that specifies the JNDI name of the resource factory as deployed in JBoss
- A res-url element that specifies the URL string in the case of a
resource-ref
of typejava.net.URL
jboss-web.xml
descriptor fragment that shows sample mappings of the resource-ref
elements given in Example 6.12, “A web.xml resource-ref descriptor fragment”.
Example 6.14. A sample jboss-web.xml resource-ref descriptor fragment
<jboss-web> <!-- ... --> <resource-ref> <res-ref-name>jdbc/DefaultDS</res-ref-name> <res-type>javax.sql.DataSource</res-type> <jndi-name>java:/DefaultDS</jndi-name> </resource-ref> <resource-ref> <res-ref-name>mail/DefaultMail</res-ref-name> <res-type>javax.mail.Session</res-type> <jndi-name>java:/Mail</jndi-name> </resource-ref> <resource-ref> <res-ref-name>jms/QueueFactory</res-ref-name> <res-type>javax.jms.QueueConnectionFactory</res-type> <jndi-name>QueueConnectionFactory</jndi-name> </resource-ref> <!-- ... --> </jboss-web>
6.6.1.7. Resource Environment References
resource-env-ref
elements in the standard deployment descriptors. The Deployer
binds the resource environment references to the actual administered objects location in the target operational environment using the jboss.xml
and jboss-web.xml
descriptors.
resource-env-ref
element describes the requirements that the referencing application component has for the referenced administered object. The resource-env-ref
element consists of the following child elements:
- An optional description element that provides the purpose of the reference.
- A resource-env-ref-name element that specifies the name of the reference relative to the
java:comp/env
context. Convention places the name in a subcontext that corresponds to the associated resource factory type. For example, a JMS queue reference namedMyQueue
should have aresource-env-ref-name
ofjms/MyQueue
. - A resource-env-ref-type element that specifies the fully qualified class name of the referenced object. For example, in the case of a JMS queue, the value would be
javax.jms.Queue
.
resource-ref-env
element declaration by a session bean. Example 6.16, “ENC resource-env-ref access code fragment” gives a code fragment that illustrates how to look up the StockInfo
queue declared by the resource-env-ref
.
Example 6.15. An example ejb-jar.xml resource-env-ref fragment
<session> <ejb-name>MyBean</ejb-name> <!-- ... --> <resource-env-ref> <description>This is a reference to a JMS queue used in the processing of Stock info </description> <resource-env-ref-name>jms/StockInfo</resource-env-ref-name> <resource-env-ref-type>javax.jms.Queue</resource-env-ref-type> </resource-env-ref> <!-- ... --> </session>
Example 6.16. ENC resource-env-ref access code fragment
InitialContext iniCtx = new InitialContext(); javax.jms.Queue q = (javax.jms.Queue) envCtx.lookup("java:comp/env/jms/StockInfo");
6.6.1.8. Resource Environment References and jboss.xml, jboss-web.xml
jboss.xml
EJB deployment descriptor and jboss-web.xml
Web application deployment descriptor is to provide the link from the logical name defined by the resource-env-ref-name
element to the JNDI name of the administered object deployed in JBoss. This is accomplished by providing a resource-env-ref
element in the jboss.xml
or jboss-web.xml
descriptor. The JBoss resource-env-ref
element consists of the following child elements:
- A
resource-env-ref-name
element that must match theresource-env-ref-name
of a correspondingresource-env-ref
element from theejb-jar.xml
orweb.xml
standard descriptors - A
jndi-name
element that specifies the JNDI name of the resource as deployed in JBoss
jboss.xml
descriptor fragment that shows a sample mapping for the StockInfo
resource-env-ref
.
Example 6.17. A sample jboss.xml resource-env-ref descriptor fragment
<session> <ejb-name>MyBean</ejb-name> <!-- ... --> <resource-env-ref> <resource-env-ref-name>jms/StockInfo</resource-env-ref-name> <jndi-name>queue/StockInfoQueue</jndi-name> </resource-env-ref> <!-- ... --> </session>