<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 
         xmlns="http://docbook.org/ns/docbook" 
         xmlns:xlink="http://www.w3.org/1999/xlink" 
         xmlns:xi="http://www.w3.org/2001/XInclude" 
         xmlns:svg="http://www.w3.org/2000/svg" 
         xmlns:mml="http://www.w3.org/1998/Math/MathML" 
         xmlns:html="http://www.w3.org/1999/xhtml" 
         xmlns:db="http://docbook.org/ns/docbook" 
         xml:lang="en" 
         xml:id="ejb2.environment">

  <info><title>EJB2 Environment</title></info>
  
  <section xml:id="ejb2.env.Introducti"><info><title>Introduction</title></info>
    
    <para>
      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.
    </para>
    <para>
      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/".
    </para>
  </section>
  <section xml:id="ejb2.env.Entries"><info><title>Environment Entries</title></info>
    
    <para>
      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.
    </para>
    <para>
      A bean accesses its environment entries with a code similar to the following:
    </para>
    <screen>
    InitialContext ictx = new InitialContext();
    Context myenv = ictx.lookup("java:comp/env");
    Integer min = (Integer) myenv.lookup("minvalue");
    Integer max = (Integer) myenv.lookup("maxvalue");
        </screen>
    <para>
      In the standard deployment descriptor, the declaration of these variables are as follows:
    </para>
    <screen>
    &lt;env-entry&gt;
      &lt;env-entry-name&gt;minvalue&lt;/env-entry-name&gt;
      &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
      &lt;env-entry-value&gt;12&lt;/env-entry-value&gt;
    &lt;/env-entry&gt;
    &lt;env-entry&gt;
      &lt;env-entry-name&gt;maxvalue&lt;/env-entry-name&gt;
      &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
      &lt;env-entry-value&gt;120&lt;/env-entry-value&gt;
    &lt;/env-entry&gt;
        </screen>
  </section>
  <section xml:id="ejb2.env.Resource"><info><title>Resource References</title></info>
    
    <para>
      The resource references are another examples of environment entries. For such entries, using subcontexts is recommended:
    </para>
    <itemizedlist>
      <listitem><para>
        java:comp/env/jdbc
         for references to DataSources objects.
      </para></listitem>
      <listitem><para>
        java:comp/env/jms
         for references to JMS connection   factories.
      </para></listitem>
    </itemizedlist>
    <para>
      In the standard deployment descriptor, the declaration of a resource reference to a JDBC connection factory is:
    </para>
    <screen>
    &lt;resource-ref&gt;
      &lt;res-ref-name&gt;jdbc/AccountExplDs&lt;/res-ref-name&gt;
      &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
      &lt;res-auth&gt;Container&lt;/res-auth&gt;
    &lt;/resource-ref&gt;
        </screen>
    <para>
      And the bean accesses the datasource as in the following:
    </para>
    <screen>
    InitialContext ictx = new InitialContext();
    DataSource ds = ictx.lookup("java:comp/env/jdbc/AccountExplDs");
        </screen>
    <para>
      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.
    </para>
    <screen>
    &lt;jonas-resource&gt;
      &lt;res-ref-name&gt;jdbc/AccountExplDs&lt;/res-ref-name&gt;
      &lt;jndi-name&gt;jdbc_1&lt;/jndi-name&gt;
    &lt;/jonas-resource&gt;
        </screen>
  </section>
  <section xml:id="ejb2.env.ResEnv"><info><title>Resource Environment References</title></info>
    
    <para>
      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.
    </para>
    <screen>
    &lt;resource-env-ref&gt;
      &lt;resource-env-ref-name&gt;jms/stockQueue&lt;/resource-env-ref-name&gt;
      &lt;resource-env-ref-type&gt;javax.jms.Queue&lt;/resource-env-ref-type&gt;
    &lt;/resource-env-ref&gt;
        </screen>
    <para>
     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.</para> 
    <screen>
    &lt;jonas-resource-env&gt;
      &lt;resource-env-ref-name&gt;jms/stockQueue&lt;/resource-env-ref-name&gt;
      &lt;jndi-name&gt;myQueue&lt;jndi-name&gt;
    &lt;/jonas-resource-env&gt;
        </screen>
  </section>
  <section xml:id="ejb2.env.EJBRef"><info><title>EJB References</title></info>
    
    <para>
      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.
    </para>
    <para>
      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:
    </para>
    <screen>
    &lt;ejb-ref&gt;
      &lt;ejb-ref-name&gt;ejb/ses1&lt;/ejb-ref-name&gt;
      &lt;ejb-ref-type&gt;session&lt;/ejb-ref-type&gt;
      &lt;home&gt;tests.SS1Home&lt;/home&gt;
      &lt;remote&gt;tests.SS1&lt;/remote&gt;
    &lt;/ejb-ref&gt;
        </screen>
    <para>
      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:
    </para>
    <screen>
    &lt;ejb-local-ref&gt;
      &lt;ejb-ref-name&gt;ejb/locses1&lt;/ejb-ref-name&gt;
      &lt;ejb-ref-type&gt;session&lt;/ejb-ref-type&gt;
      &lt;local-home&gt;tests.LocalSS1Home&lt;/local-home&gt;
      &lt;local&gt;tests.LocalSS1&lt;/local&gt;
      &lt;ejb-link&gt;LocalBean&lt;/ejb-link&gt;
    &lt;/ejb-local-ref&gt;
        </screen>
    <para>
       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". 
    </para>
    <para>
      To summarize, local interfaces are available only for  
    <itemizedlist>
      <listitem><para>
        beans in a same ejb jar file.
      </para></listitem>
      <listitem><para>
        from servlets to beans or ejbs to ejbs but in the same ear file.
      </para></listitem>
    </itemizedlist>
    </para>
    <para>
      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:
    </para>
    <screen>
    &lt;session&gt;
      &lt;ejb-name&gt;SSA&lt;/ejb-name&gt;
      ...
      &lt;ejb-ref&gt;
        &lt;ejb-ref-name&gt;ejb/ses1&lt;/ejb-ref-name&gt;
        &lt;ejb-ref-type&gt;session&lt;/ejb-ref-type&gt;
        &lt;home&gt;tests.SS1Home&lt;/home&gt;
        &lt;remote&gt;tests.SS1&lt;/remote&gt;
        &lt;ejb-link&gt;SS1&lt;/ejb-link&gt;
      &lt;/ejb-ref&gt;
    ...
    &lt;/session&gt;
    ...
    &lt;session&gt;
      &lt;ejb-name&gt;SS1&lt;/ejb-name&gt;
      &lt;home&gt;tests.SS1Home&lt;/home&gt;
      &lt;local-home&gt;tests.LocalSS1Home&lt;/local-home&gt;
      &lt;remote&gt;tests.SS1&lt;/remote&gt;
      &lt;local&gt;tests.LocalSS1&lt;/local&gt;
      &lt;ejb-class&gt;tests.SS1Bean&lt;/ejb-class&gt;
      ...
    &lt;/session&gt;
     ...
        </screen>
    <para>
      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:
    </para>
    <screen>
        &lt;ejb-link&gt;product_ejbs.jar#SS1&lt;/ejb-link&gt;
        </screen>
    <para>
      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.
    </para>
    <screen>
    &lt;jonas-session&gt;
      &lt;ejb-name&gt;SSA&lt;/ejb-name&gt;
      &lt;jndi-name&gt;SSAHome&lt;/jndi-name&gt;
      &lt;jonas-ejb-ref&gt;
        &lt;ejb-ref-name&gt;ejb/ses1&lt;/ejb-ref-name&gt;
        &lt;jndi-name&gt;SS1Home_one&lt;/jndi-name&gt;
      &lt;/jonas-ejb-ref&gt;
    &lt;/jonas-session&gt;
    ...
    &lt;jonas-session&gt;
      &lt;ejb-name&gt;SS1&lt;/ejb-name&gt;
      &lt;jndi-name&gt;SS1Home_one&lt;/jndi-name&gt;
      &lt;jndi-local-name&gt;SS1LocalHome_one&lt;/jndi-local-name&gt;
    &lt;/jonas-session&gt;
    ...
        </screen>
    <para>
      The bean locates the home interface of the other enterprise bean using the EJB reference with the following code:
    </para>
    <screen>
    InitialContext ictx = new InitialContext();
    Context myenv = ictx.lookup("java:comp/env");
    SS1Home home = (SS1Home)javax.rmi.PortableRemoteObject.narrow(myEnv.lookup("ejb/ses1"), SS1Home.class);
        </screen>
  </section>

</section>