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

- 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 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 an EJB reference used for accessing the bean through its remote home and component interfaces, 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 declaration of an EJB reference used for accessing the bean through its local home and component interfaces, in the standard deployment descriptor, looks like:

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

If the referred bean is defined in the same ejb-jar or EAR file, the optional ejb-link element of the ejb-ref or ejb-local-ref element may 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 should 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"). 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 would 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 you to use the ejb-link element. In this case, to resolve the reference, the binding of the environment JNDI name of the EJB reference to the actual JNDI name of the associated enterprise bean home is done in the JOnAS specific deployment descriptor using the jonas-ejb-ref element. In the example below it is supposed 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>

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

Currently in JOnAS it is not possible to explicitly assign a JNDI name for local home interfaces, this name is generated, and is the JNDI name of the (remote) home followed by "_L" (this means that even if there is only a local home on this bean, a jndi-name element should be defined).

## 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");
            ...
        }