<?xml version="1.0"?>
<faqs>
    <super id="faq">FAQ</super>
    <super id="faq_openejb-jar">openejb-jar.xml</super>
    <name>The openejb-jar.xml file</name>

    <faq>
        <question>What is an openejb-jar.xml?</question> 
        
        <answer id="general">
            <p>
This is the file created by the Deploy Tool that maps your bean's deployment descriptor (ejb-jar.xml) to actual containers and
resources declared in your OpenEJB configuration (openejb.conf). In fact, the Deploy tool really does nothing more than create this
file and put it in your jar, that's it. 
</p>
        </answer>
    </faq>

    <faq>
        <question>When is the openejb-jar.xml used?</question> 
        
        <answer id="use">
            <p>
At startup, any jar containing a openejb-jar.xml is loaded by the container system. The configuration tools will go looking in all the
directories and jars you have declared in your openejb.conf with the &lt;Deployment&gt; element. For every jar file it finds, it will look
inside for an openejb-jar.xml. If it finds one, it will attempt to load and deploy it into the container system. </p>
        </answer>
    </faq>
    <faq>
        <question>Do I even need the deploy tool then?</question> 
        
        <answer id="deploy.tool">
            <p>
        Nope. Typically you would only use the deploy tool to create your openejb-jar.xml, then just keep your openejb-jar.xml in your CVS (or other repository). 
        If you learn how to maintain this openejb-jar.xml file, you'll never need the deploy tool again! You can do all your builds and deploys
          automatically.
            </p>
        </answer>
    </faq>
    <faq>
        <question>Where do I put the openejb-jar.xml in my jar?</question> 
        
        <answer id="where">
            <p>
        The openejb-jar.xml file just goes in the META-INF directory of your jar next to the ejb-jar.xml file.  
            </p>
        </answer>
    </faq>
    <faq>
        <question>Is the file format easy?</question> 
        
        <answer id="easy">
            <p>
           If you can understand the ejb-jar.xml, the openejb-jar.xml should be a breeze. 
            </p>
           <p>
This is the openejb-jar.xml that is created by the Deploy tool
in the Hello World example. As you can see, the file 
format is extremely simple.  
</p> 
<file name="openejb-jar.xml">
<![CDATA[<?xml version="1.0"?>
<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
    <ejb-deployment  ejb-name="Hello" 
                     deployment-id="Hello" 
                     container-id="Default Stateless Container"/>
</openejb-jar>]]></file>
<p>
The <b>ejb-name</b> attribute is the name you gave the bean in your 
ejb-jar.xml.  The <b>deployment-id</b> is the name you want to use to 
lookup the bean in your client's JNDI namespace.  The 
<b>container-id</b>
is the name of the container in your openejb.conf file that you would 
like the bean to run in.  There MUST be one <b>ejb-deployment</b> 
element for each EJB in your jar.
</p>
        </answer>
    </faq>
    <faq>
        <question>What if my bean uses a JDBC datasource?</question> 
        
        <answer id="jdbc">
            <p>
                Then you simply add a &lt;resource-link&gt; element to your &lt;ejb-deployment&gt; element like this
                </p>
<file name="openejb-jar.xml">
<![CDATA[<?xml version="1.0"?>
<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
    
    <ejb-deployment  ejb-name="Hello" 
                     deployment-id="Hello" 
                     container-id="Default Stateless Container" >
         
        <resource-link res-ref-name="jdbc/basic/entityDatabase" 
                     res-id="Default JDBC Database"/>
    
    </ejb-deployment>

</openejb-jar>]]></file>
<p>
    The <b>res-ref-name</b> attribute refers to the &lt;res-ref-name&gt; element of the bean's &lt;resource-ref&gt; declaration in the ejb-jar.xml.
    The <b>res-id</b> attribute refers to the id of the &lt;Connector&gt; declared in your openejb.conf that will handle the connections and provide access to the desired resource.
</p>
        </answer>
    </faq>

<faq>
    <question>How many resource-link elements will I need?</question> 

    <answer id="resource-link">
        <p>
    You will need one &lt;resource-link&gt; element for every &lt;resource-ref&gt; element in your ejb-jar.xml.  So if you had an ejb-jar.xml like the following
        </p>
<file name="ejb-jar.xml">
<![CDATA[<?xml version="1.0"?>
<ejb-jar>
    <enterprise-beans>
        <session>
            <ejb-name>MyExampleBean</ejb-name>
            <home>com.widget.ExampleHome</home>
            <remote>com.widget.ExampleObject</remote>
            <ejb-class>com.widget.ExampleBean</ejb-class>
            <session-type>Stateless</session-type>
            <transaction-type>Container</transaction-type>
    
            <resource-ref>
                <description>
                This is a reference to a JDBC database.
                </description>
                <res-ref-name>jdbc/myFirstDatabase</res-ref-name>
                <res-type>javax.sql.DataSource</res-type>
                <res-auth>Container</res-auth>
            </resource-ref>
        
            <resource-ref>
                <description>
                This is another reference to a JDBC database.
                </description>
                <res-ref-name>jdbc/anotherDatabase</res-ref-name>
                <res-type>javax.sql.DataSource</res-type>
                <res-auth>Container</res-auth>
            </resource-ref>
        
        </session>
    </enterprise-beans>
</ejb-jar>]]></file>
<p>
    Then you would need two &lt;resource-link&gt; elements for that bean in your openejb-jar.xml file as such.
</p>
<file name="openejb-jar.xml">
<![CDATA[<?xml version="1.0"?>
<openejb-jar xmlns="http://www.openejb.org/openejb-jar/1.1">
    
    <ejb-deployment  ejb-name="MyExampleBean" 
                     deployment-id="MyExampleBean" 
                     container-id="Default Stateless Container" >
         
        <resource-link res-ref-name="jdbc/myFirstDatabase" 
                     res-id="My Oracle JDBC Database"/>

        <resource-link res-ref-name="jdbc/anotherDatabase" 
                     res-id="My PostgreSQL JDBC Database"/>
    
    </ejb-deployment>

</openejb-jar>]]></file>
<p>
    This would require two &lt;Connector&gt; declarations in your openejb.conf, one 
    with the <b>id</b> attribute set to <i>"My Oracle JDBC Database"</i>, and another
    with it's <b>id</b> attribute set to <i>"My PostgreSQL JDBC Database"</i> 
</p>
    </answer>
</faq>

</faqs>
