Enterprise Bean Environment

Target Audience and Content

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 explains how an enterprise component may 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 allowing 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 in the deployment descriptor all the bean environment entries 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 like this:

    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:

    <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 example of environment entries. For such entries, it is recommended to use subcontexts:

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 like this:

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

The 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. There allow the Bean Provider to refer to administered objects that are associated with resources (for example, JMS Destinations), by using logical names. Resource environment reference 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>
    
The 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 it is recommended to use the subcontext java:comp/env/ejb.

The declaration of a EJB reference in the standard deployment descriptor looks like:

    <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 binding of the environment JNDI name of the EJB reference to the JNDI name of the associated enterprise bean home is done in the JOnAS specific deployment descriptor using the jonas-ejb-ref element.

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

The bean locates the home interface of the other enterprise bean using the EJB reference with this 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 of 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 this code:

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