<chapter id="references">

   <title>References and Injection XML and Annotations</title>

   <sect1>
      <title>Intro</title>
      <para>
         This section covers how JBoss implements @EJB and @Resource.  Please note that XML always overrides annotations.
      </para>
   </sect1>
   <sect1>
      <title>EJB references</title>
      <para>
         Rules for the @EJB annotation
         <itemizedlist>
            <listitem>
               The @EJB annotation also has a mappedName() attribute.  The specification leaves this a vendor specific metadata, but JBoss recognizes mappedName() as the global JNDI name of the EJB you are referencing.  If you have specified a mappedName(), then all other attributes are ignored and this global JNDI name is used for binding.
            </listitem>
            <listitem>
               If you specify @EJB with no attributes defined:
               <programlisting>
                    @EJB ProcessPayment myEjbref;
               </programlisting>
               Then the following rules apply:
               <itemizedlist>
                 <listitem>The EJB jar of the referencing bean is contained in is search for another EJB with the same interface.  If there are more than one EJB that publishes same business interface, throw an exception, if there is one, use that one.</listitem>
                 <listitem>Search the EAR for EJBs that publish that interface.  If there are duplicates, throw an exception, otherwise return that one.</listitem>
                 <listitem>Search globally in JBoss for an EJB of that interface.  Again, if duplicates, throw an exception</listitem>
               </itemizedlist></listitem>
          <listitem>@EJB.beanName() corresponds to <![CDATA[<ejb-link>]]>.  If the beanName() is defined, then use the same algorithm as @EJB with no attributes defined except use the beanName() as a key in the search.  An exception to this rule is if you use the ejb-link '#' syntax.  The '#' syntax allows you to put a relative path to a jar in the EAR where the EJB you are referencing lives.  See spec for more details</listitem>
         </itemizedlist>
      </para>
      <para>
         For XML the same rules apply as annotations exception <![CDATA[<mapped-name>]]> is the ejb-jar.xml equivalent to @EJB.mappedName().
      </para>
   </sect1>
</chapter>

