Documentation

Guides

Please note that the Tutorial and the XML Reference are works-in-progress. We hope to have them available in the next little while.

Quick Example

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.