Datasource, ConnectionFactory, MDB and JPA Naming

Visibility of gbeans

The java:comp/env context entries are implemented as references to a gbean wrapping whatever functionality is looked up. Generally you don't specify the entire gbean name but just enough to uniquely identify it. To make this unambiguous in the presence of other unrelated applications the search for the gbean you specify is conducted only in the current application and the ancestors of the application. If a match is found in the application (ear) that has the JNDI reference, no ancestors are searched. Otherwise there must be a unique match in the ancestors. Normally you specify the "name" component of the target gbean. You can also specify the plugin id (groupId/artifactId/version/type) and the Java EE module name if the target is in an ear.

Following these rules, if the connector is deployed in the ear, no action is needed to make it visible to ejb and war modules in the ear.

If the connector is not deployed in the Java EE application with the reference, then you must make the connector plugin visible to the application using it by making it an ancestor of the application, typically by including a dependency on it in the geronimo plan. The easiest way to do this is to use maven to build a geronimo plugin: Assembling a server using Maven.

The naming space xmlns:nam="http://geronimo.apache.org/xml/ns/naming-1.2" defines following tags used to reference other resources in a deployment plan.

The name to use

Connection Factory

For connection factories such as DataSource and JMS ConnectionFactory the connector plan has a name element like this:

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-interface>javax.sql.DataSource</connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>SampleTxDatasource</name>

If you use this in your resource-ref or annotation based equivalent, and make the connector visible to your app, geronimo will find the gbean and wire it up for you. If you want to use a different name, you need to provide a mapping in the geronimo plan similar to this:

<resource-ref>
    <ref-name>jdbc/InventoryDS</ref-name>
    <resource-link>SampleTxDatasource</resource-link>
</resource-ref>

JPA

Persistence.xml needs to find jta and non-jta datasources in these elements:

<persistence xmlns="http://java.sun.com/xml/ns/persistence"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"
             xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
    <persistence-unit name="BankPU">
        <description>Entity Beans for Bank</description>
        <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider>
        <jta-data-source>SampleTxDatasource</jta-data-source>
        <non-jta-data-source>SampleNoTxDatasource</non-jta-data-source>

These are the names from the connector plan just like for connection factories. Note that there is no mapping possible. Also note that you should NEVER provide the same datasource for jta and non-jta. You may not need a separate non-jta-datasource if your app does not want openjpa to create tables, update the schema, or provide ids for your entities. Theoretically it should never be necessary to provide a non-jta-datasource but so far it appears that it is needed for the above requirements, at least for derby.

Although many other servers use jndi to define the meaning of the jta-data-source and non-jta-data-source geronimo does not. These are not jndi names in any way but must match the name specified in the connector plan.

Admin Object

For admin objecs such as jms destinations the situation is very similar, the connector plan has a name element like this:

    <adminobject>
        <adminobject-interface>javax.jms.Queue</adminobject-interface>
        <adminobject-class>org.apache.activemq.command.ActiveMQQueue</adminobject-class>
        <adminobject-instance>
            <message-destination-name>OrderQueue</message-destination-name>
            <config-property-setting name="PhysicalName">OrderQueue</config-property-setting>
        </adminobject-instance>
    </adminobject>

and again if used directly no mapping is needed and otherwise mapping looks like this:

<resource-env-ref>
    <ref-name>jms/MyRenamedQueue</ref-name>
    <admin-object-link>OrderQueue</admin-object-link>
</resource-env-ref>

MDB

While the spec descriptor or annotations provide a lot of info about where an mdb gets fed messages from, including the Destination, one important bit is left out... the resource adapter. You supply this in the geronimo plan for the ejb module like this:

<message-driven>
   <ejb-name>OrderRecvMDB</ejb-name>
   <resource-adapter>
      <resource-link>jms-resources</resource-link>
   </resource-adapter>
</message-driven>

The link uses the resource adapter name from the connector plan such as this:

<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.2">
...
            <resourceadapter>
                <resourceadapter-instance>
                    <resourceadapter-name>jms-resources</resourceadapter-name>

Other situations

These are the simplest situations and will cover most uses. If you need to further distinguish between identically named resources in different plugins consult the geronimo-naming-1.2 schema.