docs/details-on-openejb-jar.adoc

= Details on openejb-jar
:index-group: EJB
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published


= What is an openejb-jar.xml?

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.

= When is the openejb-jar.xml used?

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

= Do I even need the deploy tool then?

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.

= Where do I put the openejb-jar.xml in my jar?

The openejb-jar.xml file just goes in the META-INF directory of your jar
next to the ejb-jar.xml file.

= Is the file format easy?

If you can understand the ejb-jar.xml, the openejb-jar.xml should be a
breeze.

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.

[source,xml]
----
<?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>
----

The _ejb-name_ attribute is the name you gave the bean in your
ejb-jar.xml. The _deployment-id_ is the name you want to use to lookup
the bean in your client's JNDI namespace. The _container-id_ is the name
of the container in your openejb.conf file that you would like the bean
to run in. There MUST be one _ejb-deployment_ element for each EJB in
your jar.

== What if my bean uses a JDBC datasource?

Then you simply add a element to your element like this

[source,xml]
----
<?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>
----

The _res-ref-name_ attribute refers to the element of the bean's
declaration in the ejb-jar.xml. The _res-id_ attribute refers to the id
of the declared in your openejb.conf that will handle the connections
and provide access to the desired resource.

= How many resource-link elements will I need?

You will need one element for every element in your ejb-jar.xml. So if
you had an ejb-jar.xml like the following

[source,xml]
----
<?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>
----

Then you would need two elements for that bean in your openejb-jar.xml
file as such.

[source,xml]
----
<?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>
----

This would require two declarations in your openejb.conf, one with the
_id_ attribute set to _"My Oracle JDBC Database"_ , and another with
it's _id_ attribute set to _"My PostgreSQL JDBC Database"_