Declaring Resource Reference

Author:Vincent Harcq <vincent.harcq@hubmethods.com>

Introduction

Resources are mainly used to access SQL DataSource object for use in BMP (Bean Managed Persistence) entity beans or session beans. They can also be used to access other type of resources like JavaMail Session for example.

The EJB specification defines how to define deployment descriptor entries to define such Resources. JBoss defines an entry in jboss.xml for that purpose that can be seen as an indirection of what is done in ejb-jar.xml to the actual implementation of the resource.

ejb-jar.xml

The EJB specification facilitate the access to external "resources" through the use of deployment descriptor entries in ejb-jar.xml. The tag is <resource-ref> and takes 4 arguments <description>, <res-ref-name>, <res-type> and <res-auth>.

The res-ref-name element specifies the name of a resource manager connection factory reference.
The res-type element specifies the type of the data source. The type is specified by the Java interface (or class) expected to be implemented by the data source.
The res-auth element specifies whether the enterprise bean code signs on programmatically to the resource manager, or whether the Container will sign on to the resource manager on behalf of the bean. In the latter case, the Container uses information that is supplied by the Deployer. Valid entry are "Container" and "Application".

Example:

    <!-- JDBC DataSources (java:comp/env/jdbc) -->
    <resource-ref>
        <description>The default DS</description>
        <res-ref-name>jdbc/DefaultDS</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
    <!-- URL Connection Factories (java:comp/env/url) -->
    <resource-ref>
        <description>The default URL</description>
        <res-ref-name>url/defaultUrl</res-ref-name>
        <res-type>java.net.url</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
    <!-- JavaMail Connection Factories (java:comp/env/mail) -->
    <resource-ref>
        <description>Default Mail</description>
        <res-ref-name>mail/DefaultMail</res-ref-name>
        <res-type>javax.mail.Session</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>
    <!-- JMS Connection Factories (java:comp/env/jms) -->
    <resource-ref>
        <description>Default QueueFactory</description>
        <res-ref-name>jms/QueFactory</res-ref-name>
        <res-type>javax.jms.QueueConnectionFactory</res-type>
        <res-auth>Container</res-auth>
    </resource-ref>

jboss.xml

jboss.xml will redirect the res-ref-name entry to the implementation of the resource. This is done in <resource-ref> that takes different arguments depending on how the tag is used: <resource-name>, <res-ref-name>, <res-type> and <jndi-name>.

res-ref-name must always be present and takes the value of corresponding entry in ejb-jar.xml.
jndi-name points to the general definition of the resource in JBoss installation.
res-url is used for java.net.URL type Resource only and define the URL.
resource-name is there to introduce a new level of indirection to a Resource Manager.

A Resource Manager is defined globally for an EJB JAR inside <resource-managers> and takes different arguments : <res-name>, <res-url>, <res-jndi-name> and res-class.

res-name must always be defined and takes the value of corresponding resource-name entry of resource-ref.
res-jndi-name points to the general definition of the resource in JBoss installation.
res-url is used for java.net.URL type Resource only and define the URL.
res-class can be blank, or is the Java type of the resource.

Example:

    <enterprise-beans>
        <session>
            ...
    	    <resource-ref>
                <res-ref-name>jdbc/DefaultDS</res-ref-name>
                <resource-name>DefaultDS</jndi-name>
    	    </resource-ref>
    	    <resource-ref>
                <res-ref-name>url/defaultUrl</res-ref-name>
                <res-url>http://www.jboss.org/</res-url>
    	    </resource-ref>
    	    <resource-ref>
                <res-ref-name>url/otherUrl</res-ref-name>
	            <resource-name>SourceforgeHomePage</resource-name>
    	    </resource-ref>
    	    <resource-ref>
                <res-ref-name>mail/DefaultMail</res-ref-name>
                <resource-name>DefaultMail</jndi-name>
    	    </resource-ref>
    	    <resource-ref>
                <res-ref-name>jms/QueFactory</res-ref-name>
                <jndi-name>QueueConnectionFactory</jndi-name>
    	    </resource-ref>
    	    ...
        </session>
    </enterprise-beans>
    
    <resource-managers>
        <resource-manager res-class="">
            <res-name>DefaultDS</res-name>
            <res-jndi-name>java:/DefaultDS</res-jndi-name>
        </resource-manager>
        <resource-manager res-class="">
            <res-name>DefaultMail</res-name>
            <res-jndi-name>java:/Mail</res-jndi-name>
        </resource-manager>
        <resource-manager res-class="java.net.URL">
            <res-name>otherUrl</res-name>
            <res-url>http://sourceforge.net/</res-url>
        </resource-manager>
    </resource-managers>

Note that this example include complexity not necessary in all cases. Resource Managers does not have to be specified. The simple example for JDBC DataSource is:

    <resource-ref>
    	<res-ref-name>jdbc/DefaultDS</res-ref-name>
    	<jndi-name>java:/DefaultDS</jndi-name>
    </resource-ref>

To access the Resource from your bean, do something like:

    InitialContext ic = new InitialContext();
    DataSource ds = (DataSource) ic.lookup("java:comp/env/jdbc/DefaultDS");

    InitialContext ic = new InitialContext();
    DataSource ds = (DataSource) ic.lookup("jdbc/DefaultDS");

JDBC Datasources

For JDBC datasources, it points to the JNDI name bound to the Connection Pool. This is defined in jboss.jcml like:

  <mbean code="org.jboss.jdbc.XADataSourceLoader" name="DefaultDomain:service=XADataSource,name=DefaultDS">
    <attribute name="PoolName">DefaultDS</attribute>
    ...
  </mbean>

JavaMail Session

For JavaMail session, it points to the JNDI name bound to the JavaMail session. This is defined in jboss.jcml like:

  <mbean code="org.jboss.mail.MailService" name=":service=Mail">
    <attribute name="JNDIName">Mail</attribute>
    ...
  </mbean>

JMS Connection Factory

This is QueueConnectionFactory for JBoss 2.2 and ConnectionFactory for JBoss 2.4.

Other

You can define your own Resources as MBean, then use them from ejbs. A example to look at for more information is Castor.