JavaEE Environment Naming Context (ENC)

Updated 3 Aug 2017

Background

A JavaEE component / deployment has a JNDI namespace / context that is only visible to the particular component itself.

Use cases

The Environment Naming Context (ENC) can be used for:

Abstracting an application from the datasource's JNDI name. The application can be written to always lookup a JNDI name in java:comp/env/jdbc/ context and then it is linked to the global JNDI address via a deployment descriptor. This allows you to change the JNDI name that the application is using with out recompiling the code. This is also useful when the application is run in different application servers. This is done using resource-ref which can also be used for other objects bound in JNDI.
Abstracting an application from an EJB's JNDI name similar to a datasource, by using ejb-ref
Providing configuration to an application through the use of env-entry, which can be changed without recompiling the code.

Environment Entries

Resource References

JavaEE 6

JavaEE 6 expanded the specification to define the lookup-name in a resource-ref, thus eliminating the need to use the container specific configuration file jboss-web.xml for example in previous versions of JBoss EAP

The web.xml below shows an example of a web application sub-deployment in an ear that also includes an ejb sub-deployment. It shows defining an ejb or ejb-local ref which allows the web application code to always lookup java:comp/env/ejb/remote/Hello or java:comp/env/ejb/local/Hello which will look up the Session EJB in the ejb deployment with the remote interface com.jboss.examples.ejb3.HelloRemote or the com.jboss.examples.ejb3.HelloLocal

<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">
   <ejb-ref>
      <ejb-ref-name>ejb/remote/Hello</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <remote>com.jboss.examples.ejb3.HelloRemote</remote>
   </ejb-ref>

   <ejb-local-ref>
      <ejb-ref-name>ejb/local/Hello</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <local>com.jboss.examples.ejb3.HelloLocal</local>
   </ejb-local-ref>
</web-app>

web.xml has:

<?xml version="1.0"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">
  <resource-ref>
    <description>SQL server</description>
    <res-ref-name>myDatasource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
    <lookup-name>java:jboss/datasources/ExampleDS</lookup-name>
  </resource-ref>

   <ejb-ref>
      <ejb-ref-name>MyEJB</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <home>org.jboss.as.test.ejb.SessionHome</home>
      <remote>org.jboss.as.test.ejb.SessionRemote</remote>
      <lookup-name>java:global/ejb3-servlet-ejbs/MyEJB!org.jboss.as.test.ejb.SessionHome</lookup-name>
   </ejb-ref>
   
   <ejb-local-ref>
      <ejb-ref-name>MyEJBLocal</ejb-ref-name>
      <ejb-ref-type>Session</ejb-ref-type>
      <local-home>org.jboss.as.test.ejb.SessionLocalHome</local-home>
      <local>org.jboss.as.test.ejb.SessionLocal</local>
      <lookup-name>java:global/ejb3-servlet-ejbs/MyEJB!org.jboss.as.test.ejb.SessionLocalHome</lookup-name>
   </ejb-local-ref>

</web-app>

ejb-jar.xml example:

<?xml version="1.1" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
         version="3.1">
    <enterprise-beans>
        <session>
            <ejb-name>ExampleEjb</ejb-name>
            <session-type>Stateless</session-type>
            <ejb-ref>
                <ejb-ref-name>home</ejb-ref-name>
                <lookup-name>corbaname:iiop:${node1}:3628#IIOPBasicBean</lookup-name>
            </ejb-ref>
            <resource-ref>
               <description>SQL server</description>
              <res-ref-name>myDatasource</res-ref-name>
              <res-type>javax.sql.DataSource</res-type>
              <res-auth>Container</res-auth>
              <lookup-name>java:jboss/datasources/ExampleDS</lookup-name>
            </resource-ref>
        </session>
    </enterprise-beans>
</ejb-jar>

application.xml example:

<!-- this becomes java:app/env/ExampleDS => java:jboss/datasources/ExampleDS --> 
  <resource-ref>
    <res-ref-name>ExampleDS</res-ref-name> 
    <lookup-name>java:jboss/datasources/ExampleDS</lookup-name>
  </resource-ref>

JBoss EAP 6.x Notes

JBoss EAP 6 looks at deployment descriptors for resource-refs and ejb-refs and will create a lifecycle dependency on the give resource-ref / ejb-ref to ensure that it has been started before starting your service.

JavaEE 5 / 4

web.xml has:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" 
         xmlns="http://java.sun.com/xml/ns/javaee" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">  
  <resource-ref>
    <description>SQL server</description>
    <res-ref-name>myDatasource</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
    <res-auth>Container</res-auth>
  </resource-ref>
</web-app>

jboss-web.xml has:

<jboss-web xmlns="http://www.jboss.com/xml/ns/javaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-web_5_1.xsd"
           version="5.1">
    <resource-ref>
        <res-ref-name>myDatasource</res-ref-name>
        <jndi-name>java:/myDatasource</jndi-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
        <res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>

   <ejb-ref>
      <ejb-ref-name>MyEJB</ejb-ref-name>
      <jndi-name>java:global/ejb3-servlet-ejbs/MyEJB!org.jboss.as.test.ejb.SessionHome</jndi-name>
   </ejb-ref>
   
   <ejb-local-ref>
      <ejb-ref-name>MyEJBLocal</ejb-ref-name>
      <jndi-name>java:global/ejb3-servlet-ejbs/MyEJB!org.jboss.as.test.ejb.SessionLocalHome</jndi-name>
   </ejb-local-ref>

</jboss-web>

EJB References

Accessing a components Environment Naming Context

Via InitialContext lookup

import javax.naming.Context;
import javax.naming.InitialContext;

Context ctx = new InitialContext();
Context envCtx = ctx.lookup("java:comp/env");
Object object = envCtx.lookup("myEntry");

Via @Resource injection

import javax.annotation.Resource;

@Resource
private String myEntry;

[1] Content from docs.oracle.com is not included.http://docs.oracle.com/cd/E19798-01/821-1841/girdr/index.html

Product(s)

Red Hat JBoss Enterprise Application Platform

Category

Learn more

Components

jbossas

Tags

Article Type

General