Introducing the DataSourceDefinition Annotation

One of the many cool new features in Java EE 6, is support for the DataSourceDefinition annotation.

The DataSourceDefinition annotation provides a way to define a DataSource and register it with JNDI. The annotation provided annotation elements for the commonly used DataSource properties. Additional standard and vendor specific properties may also be specified.

So let us look at an example:

@DataSourceDefinition(name = "java:global/MyApp/myDS",
className = "org.apache.derby.jdbc.ClientDataSource",
portNumber = 1527,
serverName = "localhost",
databaseName = "testDB",
user = "lance",
password = "secret",
properties = {"createDatabase=create"}) )

The data source will be registered using the value specified in the name element and can be defined in any valid Java EE name space, determining the accessibility of the data source from other components.

The properties element is used to specify less frequently used standard DataSource properties as well as vendor-specified properties using the format :

{"property1=value", "property2=value" ...}

Using the newly defined DataSource is as simple as:

  @Resource(lookup = "java:global/MyApp/myDS")
  private DataSource ds;

You can also define multiple DataSources using the DataSourceDefinitions annotation:

@DataSourceDefinitions({
  @DataSourceDefinition(name = "java:global/MyApp/myDS",
  className = "org.apache.derby.jdbc.ClientDataSource",
  portNumber = 1527,
  serverName = "localhost",
  databaseName = "testDB21",
  user = "lance",
  password = "secret",
  properties = {"createDatabase=create"}),
  @DataSourceDefinition(name = "java:global/MyApp/myDS2",
  className = "com.mysql.jdbc.jdbc2.optional.MysqlDataSource",
  portNumber = 3306,
  serverName = "localhost",
  databaseName = "dogDB",
  user = "luckyDog",
  password = "shhh",
  properties = {"pedantic=true"})
})

So let's look at a simple web application, DataSourceDefWebApp, which utilizes the DataSourceDefinition. The application is provided as a NetBeans project that was created with NetBeans 6.8.

The application when deployed, will create a DataSource for Java DB.

When you go to run the application, you will need to make sure that you have the Java DB client JDBC driver accessible to your appserver, which it will be for Glassfish V3 and the Java DB server started.

To run the application after you have deployed it, go to the following URL using your favorite browser:

http://<host>:<port>/DataSourceDefWebApp

When you first run the application, you will see the following menu. Select the menu option "Initialize the Database", to create the Java DB database and create two initial contacts.

AdminMenu.JPG

After initializing the database you can select "Add a Contact" to add a new contact to your database.

AddContact.JPG

When you click the "Add Contact", button you will be taken to the displayContacts page.

DisplayDerby.JPG ,  

The application defines the DataSource in the DataSourceDefServlet:

@DataSourceDefinition(name = "java:global/MyApp/myDS",
className = "org.apache.derby.jdbc.ClientDataSource",
portNumber = 1527,
serverName = "localhost",
databaseName = "testDB",
user = "lance",
password = "secret",
properties = {"createDatabase=create"})
@WebServlet(name = "DataSourceDefServlet", urlPatterns = {"/DataSourceDefServlet", "/displayContacts", "/addContact", "/initDB"})
public class DataSourceDefServlet extends HttpServlet {private ServletContext context;
@Resource(lookup = "java:global/MyApp/myDS")
private DataSource ds;


The DataSourceDefinition annotation is specified above the class declaration. The Resource annotation is then used specifying the JNDI name that was defined in DataSourceDefinition.

The Stateless Session bean, DemoBean, also uses the Resource annotation to access the same DataSource via:

@Resource(lookup = "java:global/MyApp/myDS")
private DataSource ds;

You can also override the settings that you have specified in the DataSourceDefinition annotation by adding the data-source element to your web.xml. For example, in order to use a MySQL database instead of Java DB, you can create a web.xml and add the following (remember to adjust the properties as necessary):

<data-source>
<description>DataSource for MySQL</description>
<name>java:global/MyApp/myDS</name>
<class-name>com.mysql.jdbc.jdbc2.optional.MysqlDataSource</class-name>
<server-name>localhost</server-name>
<port-number>3306</port-number>
<database-name>testDB</database-name>
<user>lance</user>
<password>secret</password>
<property>
<name>x</name>
<value>y</value>
</property>
<property>
<name>y</name>
<value>x</value>
</property>
<login-timeout>500</login-timeout>
<transactional>false</transactional>
<isolation-level>TRANSACTION_READ_COMMITTED</isolation-level>
<initial-pool-size>2</initial-pool-size>
<max-pool-size>5</max-pool-size>
<min-pool-size>1</min-pool-size>
<max-idle-time>500</max-idle-time>
<max-statements>100</max-statements>
</data-source>

In the top level directory of the DataSourceDefinitionWebApp, you will find a web.xml that you can move to the web/WEB-INF folder of the project. Adjust the properties for the data-source to correctly point to your MySQL database, then rebuild and deploy.

When you go to display the data, you will notice that the the output from displayContacts indicates thatthe database that is being used in MySQL

OverrideWithMysql.JPG

The DataSourceDefinition annotation is a simple yet powerful addition to Java EE 6. Enjoy!


References:


Comments:

Screenshots are not visible and the link to the zipped project is broken because the address is repeated in the link.
ps. Thanks 4 the tutorial!
ps2: Will Netbeans 6.8 use this annotation creating a new data source?

Posted by nicola on December 16, 2009 at 02:13 AM EST #

Thanks I Fixed the broken link.

Not sure what you mean that the screen shots are not visible if you can explain that would be great as I can seem them find on my pc and macbook

Netbeans 6.8 does not automatically generate this annotation.

Posted by Lance Andersen on December 22, 2009 at 06:36 AM EST #

Oh, no!

Who in the world thought this would be a good idea?

Why has this been introduced to glassfish?

IMHO it is very bad practice to define a DB (including vendor specifics) _inside_ your application.

Referencing a jdbc resource that is administered by the server gives you way more flexibility, if your server configuration changes. And it has been very easy to use as well.

Posted by Stephan Gernand on December 22, 2009 at 11:27 PM EST #

a very interesting legal news congratulations tutorial.

I wonder if the jndi name is registered in the admin console glassfih because I can not see the jndi resgisters or datasoruce in admin console

Posted by bruno on October 10, 2010 at 05:16 AM EDT #

Thanks for your article!! Unfortunately at first I had problems with the resource annotation and its parameter "lookup". Could solve it. If anyone else has this problem, here is the link to the solution:

http://java-abwaschbar.blogspot.com/2011/01/resource-annotation-and-lookup.html

Posted by Frederik Mortensen on January 29, 2011 at 11:55 PM EST #

Post a Comment:
  • HTML Syntax: NOT allowed
About

user12629431

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today
Bookmarks