docs/configuring-datasources.adoc

= Configuring DataSources in tomee.xml
:index-group: Configuration
:jbake-date: 2018-12-05
:jbake-type: page
:jbake-status: published


The __ element is used to configure a _javax.sql.DataSource_. It is also
used to configure other resources like Timers, Topics, Queues. We will
see some examples of using to configure a DataSource.

The element is designed after `@Resource` annotation and has similar
attributes.

For example, this annotation in your bean:

[source,java]
----
@Resource(name = "myDerbyDatasource", type = javax.sql.DataSource.class)
----

Would map to a Resource declared in your openejb.xml as follows:

[source,xml]
----
<Resource id="myDerbyDatasource" type="javax.sql.DataSource">
 . . . .
<Resource>
----

Note that in the xml element, the _type_ value of _javax.sql.DataSource_
can abbreviated to just _DataSource_ as follows:

[source,xml]
----
<Resource id="myDerbyDatasource" type="DataSource">
 . . . .
<Resource>
----

It is also possible to specify the path to the driver jar file using a
classpath attribute like so:

[source,xml]
----
<Resource id="myDerbyDatasource" type="DataSource" classpath="/path/to/driver.jar">
 . . . .
<Resource>
----

...Or in a http://maven.apache.org/[Maven] environment like so:

[source,xml]
----
<Resource id="myDerbyDatasource" type="DataSource" classpath="mvn:org.apache.derby:derby:10.10.1.1">
 . . . .
<Resource>  
----

See link:containers-and-resources.html[Containers and Resources] for a
complete list of supported DataSource properties.

See link:datasource-password-encryption.html[DataSource Password
Encryption] for information on specifying non-plain-text database
passwords in your openejb.xml file.

See link:common-datasource-configurations.html[Common DataSource
Configurations] for a list of the commonly used databases and their
driver configurations.

See link:datasource-configuration-by-creator.html[DataSource
Configuration by Creator] for a list of the different properties
supported for each data source creator.

You may also need data partitioning per customer or depending on any
other business criteria. That's also an available feature. See
link:dynamic-datasource.html[Dynamic Datasource] for more details.

== JNDI names for configured DataSources

=== Example 1

[source,xml]
----
<Resource id="Default JDBC Database" type="DataSource">
   . . . . .
</Resource>
----

The global jndi name would be _java:openejb/Resource/Default JDBC
Database_

=== Example 2

[source,xml]
----
<Resource id="Derby Database"  type="DataSource">
  . . . . .
</Resource>
----

The global jndi name would be _java:openejb/Resource/Derby Database_

== Obtaining a DataSource

DataSource references in your ejb should get automatically mapped to the
Resource you declare. The shortest and easiest rule is that _if your
reference name matches a Resource in your openejb.xml, that's the one
you get_.  Essentially, the rules for mapping are as follows.

[arabic]
. Name Attribute Match - `@Resource` with a name attribute matching the
resource name gets that resource injected
. Injected Name Match - variable name matching the resource name gets
that resource injected
. No Match - nothing matches a resource name, so the first resource
available gets injected

There are various ways one could obtain a DataSource now. Lets take an
example of Derby.

With a Resource declaration in your openejb.xml like this:

[source,xml]
----
<Resource id="myDerbyDatabase"  type="DataSource">
  . . . . .
</Resource>
----

There are several possible ways to refer to it, as follows.

_BY matching variable name to resource name_

[source,java]
----
@Stateless
public class FooBean {
    @Resource DataSource myDerbyDatabase;
}
----

_OR BY matching name_

[source,java]
----
@Stateless
public class FooBean {
    @Resource(name="myDerbyDatabase")
    DataSource dataSource;
}
----

_OR BY JNDI lookup_

[source,java]
----
@Resource(name="myDerbyDatabase", type=javax.sql.DataSource.class)
@Stateless
public class FooBean {

    public void setSessionContext(SessionContext sessionContext) {
        DataSource dataSource = (DataSource)
        sessionContext.lookup("myDerbyDatabase");
    }

    public void someOtherMethod() throws Exception {
        InitialContext initialContext = new InitialContext();
        DataSource dataSource = (DataSource)
        initialContext.lookup("java:comp/env/myDerbyDatabase");
    }
}
----

_OR_

[source,xml]
----
<resource-ref>
  <res-ref-name>myDerbyDatabase</res-ref-name>
  <res-type>javax.sql.DataSource</res-type>
</resource-ref>
----

_OR_

[source,xml]
----
<resource-ref>
   <res-ref-name>jdbc/myDerbyDatabase</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
</resource-ref>
----

_OR_

[source,xml]
----
<resource-ref>
   <res-ref-name>someOtherName</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <mapped-name>myDerbyDatabase</mapped-name>
</resource-ref>
----