12.5. 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:

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, that is, 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 '#' (for example, 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 is not in the same EJB-JAR file as SSA, but in another file named product_ejbs.jar, the ejb-link element could be:

<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. To resolve the reference in this case, 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);