Please note that the Tutorial and the XML Reference are works-in-progress. We hope to have them available in the next little while.
Here is a short example to give you a flavor of what JDBL is, and how it is used. Keep in mind that the example just touches on some of the features of JDBL. We provide a more gentler and complete introduction in our JDBL Tutorial.
Our example will simply search for a bunch of persons by their name and title. We are concerned with the database aspect, so naturally we will skip the UI portion.
Let's start with the ending, and just take a look at how JDBL is used from your business logic (say a EJB):
package com.corp.project.ejb; import com.corp.project.datalayer.DB; public class PersonEJB extends SessionBean { public Person[] getPersons(String name, String title) throws Exception { return DB.call().getPersons(name, title); } //the rest of your EJB methods .... }
Simple, right? It looks like Java, in fact it is Java, it is typesafe, and quite frankly a pleasure to use since all the nice features of your favorite IDE work out of the box: completion, hover popups, etc.
Let's now go back to the beginning and see what it takes to get here. Hopefully the rest of the journey is going to be similarly pleasant.
First, we will define our model objects. Here we use the Immutable object pattern, because it is typically not supported by other mapping frameworks. The other style of writting model objects with both getters and setters is supported as well, and described in the Tutorial.
package com.corp.project.model; class Address { private final String street; private final String city; private final String country; public Address(String street, String city, String country) { this.street = street; this.city = city; this.country = country; } public String getStreet() { return street; } public String getCity() { return city; } public String getCountry() { return country; } }
Next is the Person
class:
package com.corp.project.model; class Person { private final String name; private final String title; private final Address address; public Person(String name, String title, Address address) { this.name = name; this.title = title; this.address = address; } public void getName() { return name; } public void getTitle() { return title; } public Address getAddress() { return address; } }
Now we need some tables in the database for these objects. Assume we have the following simple structure:
CREATE TABLE person ( person_id NUMBER (6, 0) NOT NULL, person_name VARCHAR (128) NOT NULL, person_title VARCHAR (40), PRIMARY KEY (person_id) ) CREATE TABLE address ( address_id NUMBER (8, 0) NOT NULL, addr_per_id NUMBER (6, 0) NOT NULL, street VARCHAR (128) NOT NULL, city VARCHAR (40) NOT NULL, country VARCHAR (30), PRIMARY KEY (address_id) CONSTRAINT fk_person FOREIGN KEY (addr_per_id) REFERENCES person(person_id) )
And last, but certainly not least, the heart and soul of our example:
<jdbl> <import>com.corp.project.model.*</import> <interface name="com.corp.project.datalayer.DB" /> <datasource> <driver>oracle.jdbc.driver.OracleDriver</driver> <url>jdbc:oracle:thin:@localhost:1521:orcl <user>jdoe</user> <passwd>test</passwd> </datasource> <statement id="getPersons"> <input>String name, String title</input> <body> SELECT * FROM person, address WHERE person_id = address.addr_per_id AND person_name LIKE $name AND person_title LIKE $title </body> <result> {*: new Person(@person_name, @person_title, new Address(@street, @city, @country))} </result> </statement> </jdbl>
As you have probably guessed already, the {*: ... }
operator iterates over
the result set, and executes the body for each of the rows, placing the result in an
array.
JDBL is meant to be simple to use and understand. If you've given the above example a few minutes thought and you still can not understand what is going on, we have failed to make it simple. If so, we would love to hear from you, to try to improve the clarity of the example or the language. Please send us your comments at jdbl-devel@lists.sourceforge.net, be them positive or negative.