Declaring an EJB reference

An EJB reference (see ejb1.1 specification, 14.3, p207) is when a bean A wants to call methods on a bean B. We are talking about intra-bean calls also called B2B calls. This is not for clients (that is covered in the beginner trails) this is for bean calls all on the server. Most of these calls are done inside the server VM.

This call will look like this:

public class ABean implements SessionBean {

   public void businessMethod(...) {
      ...
      InitialContext namingContext = new InitialContext();
      Object ref = namingContext.lookup("java:comp/env/ejb/myBean");
      BHome home = (BHome)PortableRemoteObject(ref);
      B bean = home.create(pk);
      ...
   }

}

You can also have a lookup relative to "java:comp/env" like this :

public class ABean implements SessionBean {

   public void businessMethod(...) {
      ...
      InitialContext namingContext = new InitialContext();
      Object ref = namingContext.lookup("ejb/myBean");
      BHome home = (BHome)PortableRemoteObject(ref);
      B bean = home.create(pk);
      ...
   }

}

This notation let better understand the redirection done by JBoss for the JNDI lookup. As we will see, where the bean lives is not specified in the source code but in the deployment descriptor.

To be allowed this call, the bean A must declare it in the its deployment descriptor. This is done by an <ejb-ref> tag in the bean section of the ejb-jar.xml file. 2 cases may occur:

Internal EJB reference

An EJB reference is called internal when the bean B is in the same application unit as the bean A. This means that the beans are physically packaged in the same jar. In this case, you must provide the <ejb-link> tag, and its value must match the <ejb-name> of bean B. You don't have to provide anything in the jboss.xml file. Your ejb-jar.xml file will look like this:

<ejb-jar>
  <enterprise-beans>
                                                                      
    <session>
      <ejb-name>Bean A</ejb-name>
      <home>AHome</home>
      <remote>A</remote>
      <ejb-class>ABean</ejb-class>
      <session-type>Stateful</session-type>
      <transaction-type>Container</transaction-type>
      <ejb-ref>
        <ejb-ref-name>ejb/myBean</ejb-ref-name>
        <ejb-ref-type>Entity</ejb-ref-type>
        <home>BHome</home>
        <remote>B</remote>
        <ejb-link>Bean B</ejb-link>
      </ejb-ref>
    </session>

    <entity>
      <ejb-name>Bean B</ejb-name>
      <home>BHome</home>
      <remote>B</remote>
      <ejb-class>BBean</ejb-class>
      <persistence-type>Bean</persistence-type>
      <prim-key-class>myPK</prim-key-class>
      <reentrant>True</reentrant>
    </entity>

  </enterprise-beans>
</ejb-jar>

External EJB reference

An EJB reference is called external when the bean B comes from another application unit, it may even be deployed on another server. This means that the beans live in different jars on different systems. In this case, you cannot rely on the standard <ejb-link> tag in ejb-jar.xml since there the beans are not covered in the same file. Instead, you must provide the full JNDI name of the bean B in jboss.xml. This is necessary to map the names from different ejb-jar.xml files since the 2 beans are defined in different application units. A full name is of the form:

protocol://host:1234/name/in/other/server Note that the <ejb-ref-name> tags in the 2 xml files must match.

ejb-jar.xml:

<ejb-jar>
  <enterprise-beans>
                                                                      
    <session>
      <ejb-name>Bean A</ejb-name>
      <home>AHome</home>
      <remote>A</remote>
      <ejb-class>ABean</ejb-class>
      <session-type>Stateful</session-type>
      <transaction-type>Container</transaction-type>
      <ejb-ref>
        <ejb-ref-name>ejb/myBean</ejb-ref-name>
        <ejb-ref-type>Entity</ejb-ref-type>
        <home>BHome</home>
        <remote>B</remote>
      </ejb-ref>
    </session>

  </enterprise-beans>
</ejb-jar>

jboss.xml:

<jboss>                                                               
  <enterprise-beans>
    <session>
      <ejb-name>Bean A</ejb-name>
      <ejb-ref>
        <ejb-ref-name>ejb/myBean</ejb-ref-name>
        <jndi-name>jnp://otherserver/application/beanB</jndi-name>
      </ejb-ref>
    </session>
  <enterprise-beans>
</jboss>

If bean B is deployed in another application, but on the same jboss server, the jndi-name you provide must be the name under which bean B is deployed.

IMPORTANT NOTE: this will tell jboss where to look for bean B. You also have to tell jboss what bean B is: in case of an external ejb-reference, be sure to include bean B's home and remote interface in bean A's ejb-jar.