EJB Programmer's Guide: Enterprise Bean Environment

The target audience for this guide is the Enterprise Bean provider, i.e. the person in charge of developing the software components on the server side. It describes how an enterprise component can refer to values, resources, or other components in a way that is configurable at deployment time.

The content of this guide is the following:

1. Target Audience and Content
2. Introduction
3. Environment Entries
4. Resource References
5. Resource Environment References
6. EJB References
7. Deprecated EJBContext.getEnvironment() method

Introduction

The enterprise bean environment is a mechanism that allows customization of the enterprise bean's business logic during assembly or deployment. The environment is a way for a bean to refer to a value, to a resource, or to another component so that the code will be independent of the actual referred object. The actual value of such environment references (or variables) is set at deployment time, according to what is contained in the deployment descriptor. 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 enterprise bean environment is provided by the container (i.e. the JOnAS server) to the bean through the JNDI interface as a JNDI context. The bean code accesses the environment using JNDI with names starting with "java:comp/env/".

Environment Entries

The bean provider declares all the bean environment entries in the deployment descriptor via the env-entry element. The deployer can set or modify the values of the environment entries.

A bean accesses its environment entries with a code similar to the following:

    InitialContext ictx = new InitialContext();
    Context myenv = ictx.lookup("java:comp/env");
    Integer min = (Integer) myenv.lookup("minvalue");
    Integer max = (Integer) myenv.lookup("maxvalue");
    

In the standard deployment descriptor, the declaration of these variables are as follows:

    <env-entry>
      <env-entry-name>minvalue</env-entry-name>
      <env-entry-type>java.lang.Integer</env-entry-type>
      <env-entry-value>12</env-entry-value>
    </env-entry>
    <env-entry>
      <env-entry-name>maxvalue</env-entry-name>
      <env-entry-type>java.lang.Integer</env-entry-type>
      <env-entry-value>120</env-entry-value>
    </env-entry>
    

Resource References

The resource references are another examples of environment entries. For such entries, using subcontexts is recommended:

• java:comp/env/jdbc for references to DataSources objects.
• java:comp/env/jms for references to JMS connection factories.

In the standard deployment descriptor, the declaration of a resource reference to a JDBC connection factory is:

    <resource-ref>
      <res-ref-name>jdbc/AccountExplDs</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
    </resource-ref>
    

And the bean accesses the datasource as in the following:

    InitialContext ictx = new InitialContext();
    DataSource ds = ictx.lookup("java:comp/env/jdbc/AccountExplDs");
    

Binding of the resource references to the actual resource manager connection factories that are configured in the EJB server is done in the JOnAS-specific deployment descriptor using the jonas-resource element.

    <jonas-resource>
      <res-ref-name>jdbc/AccountExplDs</res-ref-name>
      <jndi-name>jdbc_1</jndi-name>
    </jonas-resource>
    

Resource Environment References

The resource environment references are another example of environment entries. They allow the Bean Provider to refer to administered objects that are associated with resources (for example, JMS Destinations), by using logical names. Resource environment references are defined in the standard deployment descriptor.

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

Binding of the resource environment references to administered objects in the target operational environment is done in the JOnAS-specific deployment descriptor using the jonas-resource-env element.

    <jonas-resource-env>
      <resource-env-ref-name>jms/stockQueue</resource-env-ref-name>
      <jndi-name>myQueue<jndi-name>
    </jonas-resource-env>
    

EJB References

The EJB reference is another special entry in the enterprise bean's environment. EJB references allow the Bean Provider to refer to the homes of other enterprise beans using logical names. For such entries, using the subcontext java:comp/env/ejb is recommended.

The declaration of an EJB reference used for accessing the bean through its remote home and component interfaces in the standard deployment descriptor is shown in the following example:

    <ejb-ref>
      <ejb-ref-name>ejb/ses1</ejb-ref-name>
      <ejb-ref-type>session</ejb-ref-type>
      <home>tests.SS1Home</home>
      <remote>tests.SS1</remote>
    </ejb-ref>
    

The declaration of an EJB reference used for accessing the bean through its local home and component interfaces in the standard deployment descriptor is shown in the following example:

    <ejb-local-ref>
      <ejb-ref-name>ejb/locses1</ejb-ref-name>
      <ejb-ref-type>session</ejb-ref-type>
      <local-home>tests.LocalSS1Home</local-home>
      <local>tests.LocalSS1</local>
      <ejb-link>LocalBean</ejb-link>
    </ejb-local-ref>
    

Local interfaces are available in the same JVM as the bean providing this interface. The use of these interfaces also implies that the classloader of the component performing a lookup (bean or servlet component) is a child of the EJB classloader providing the local interface.
Local interfaces, then, are not available to outside WARs or outside EJB-JARs even if they run in the same JVM. This is due to the fact that classes of the local interfaces are not visible on the client side. Putting them under the WEB-INF/lib folder of a WAR would not change anything as the two classes would be loaded by different classloaders, which will throw a "ClassCastException".

To summarize, local interfaces are available only for

• beans in a same ejb jar file.
• from servlets to beans or ejbs to ejbs but in the same ear file.

If the referred bean is defined in the same ejb-jar or EAR file, the optional ejb-link element of the ejb-ref element can be used to specify the actual referred bean. The value of the ejb-link element is the name of the target enterprise bean, i.e. the name defined in the ejb-name element of the target enterprise bean. If the target enterprise bean is in the same EAR file, but in a different ejb-jar file, the name of the ejb-link element may be the name of the target bean, prefixed by the name of the containing ejb-jar file followed by '#' (e.g. "My_EJBs.jar#bean1"); prefixing by the name of the ejb-jar file is necessary only if some ejb-name conflicts occur, otherwise the name of the target bean is enough. In the following example, the ejb-link element has been added to the ejb-ref (in the referring bean SSA) and a part of the description of the target bean (SS1) is shown:

    <session>
      <ejb-name>SSA</ejb-name>
      ...
      <ejb-ref>
        <ejb-ref-name>ejb/ses1</ejb-ref-name>
        <ejb-ref-type>session</ejb-ref-type>
        <home>tests.SS1Home</home>
        <remote>tests.SS1</remote>
        <ejb-link>SS1</ejb-link>
      </ejb-ref>
    ...
    </session>
    ...
    <session>
      <ejb-name>SS1</ejb-name>
      <home>tests.SS1Home</home>
      <local-home>tests.LocalSS1Home</local-home>
      <remote>tests.SS1</remote>
      <local>tests.LocalSS1</local>
      <ejb-class>tests.SS1Bean</ejb-class>
      ...
    </session>
     ...
    

If the bean SS1 was not in the same ejb-jar file as SSA, but in another file named product_ejbs.jar, the ejb-link element could have been:

        <ejb-link>product_ejbs.jar#SS1</ejb-link>
    

If the referring component and the referred bean are in separate files and not in the same EAR, the current JOnAS implementation does not allow use of the ejb-link element. In this case, to resolve the reference, the jonas-ejb-ref element in the JOnAS-specific deployment descriptor would be used to bind the environment JNDI name of the EJB reference to the actual JNDI name of the associated enterprise bean home. In the following example, it is assumed that the JNDI name of the SS1 bean home is SS1Home_one.

    <jonas-session>
      <ejb-name>SSA</ejb-name>
      <jndi-name>SSAHome</jndi-name>
      <jonas-ejb-ref>
        <ejb-ref-name>ejb/ses1</ejb-ref-name>
        <jndi-name>SS1Home_one</jndi-name>
      </jonas-ejb-ref>
    </jonas-session>
    ...
    <jonas-session>
      <ejb-name>SS1</ejb-name>
      <jndi-name>SS1Home_one</jndi-name>
      <jndi-local-name>SS1LocalHome_one</jndi-local-name>
    </jonas-session>
    ...
    

The bean locates the home interface of the other enterprise bean using the EJB reference with the following code:

    InitialContext ictx = new InitialContext();
    Context myenv = ictx.lookup("java:comp/env");
    SS1Home home = (SS1Home)javax.rmi.PortableRemoteObject.narrow(myEnv.lookup("ejb/ses1"),
                    SS1Home.class);
    

Deprecated EJBContext.getEnvironment() method

JOnAS provides support for EJB 1.0-style definition of environment properties. EJB1.0 environment must be declared in the ejb10-properties sub-context. For example:

    <env-entry>
      <env-entry-name>ejb10-properties/foo</env-entry-name>
      <env-entry-type>java.lang.String</env-entry-type>
      <env-entry-value>foo value</env-entry-value>
    </env-entry>
    

The bean can retrieve its environment with the following code:

    SessionContext ctx;
    Properties prop;
    public void setSessionContext(SessionContext sc) {
        ctx = sc;
        prop = ctx.getEnvironment();
    }
    public mymethod() {
        String foo = prop.getProperty("foo");
        ...
    }