Excalibur Datasource Management - Jdbc Datasource Example Application

The Jdbc Data Source Example Application will take you through the steps involved to get your Avalon application configured to be able to connect to a database. This is done by implementing a simple console based application which allows the user to add, remove, and view Movie Titles in a Hypersonic SQL database.

This example assumes that you are familiar with configuration files and with the Logger system.

To run the application, follow these steps.

1. Download and build the avalon project.
2. Download the avalon-excalibur project into the same parent directory as avalon and run build
3. cd into the avalon-excalibur/examples/jdbcdatasource directory and run build. This will build the example application.
4. cd into the avalon-excalibur/examples/jdbcdatasource/bin directory and execute the run script.

Once the application is running, you should see the following:

Running the JdbcDataSource Example Application

Please enter a title to be added to the database
    (RESET deletes all titles, LIST lists all titles, QUIT or EXIT to quit)
:

The application allows you to enter the commands RESET to delete all titles from the database, LIST to list all the titles in the database, or QUIT to quit the application. Any other command will be interpreted as a title and be added to the database. Not the fanciest interface in the world, but it will work for this example.

Play around with adding and deleting a few Movie Titles before we move on to how the application works. You should see something like the following as output:

Running the JdbcDataSource Example Application

Please enter a title to be added to the database
    (RESET deletes all titles, LIST lists all titles, QUIT or EXIT to quit)
: Crouching Tiger Sleeping Dragon
Adding title 'Crouching Tiger Sleeping Dragon' to the database...
Added 'Crouching Tiger Sleeping Dragon' to the database.
: The Matrix
Adding title 'The Matrix' to the database...
Added 'The Matrix' to the database.
: Akira
Adding title 'Akira' to the database...
Added 'Akira' to the database.
: list
Listing all titles currently in the database...
    'Crouching Tiger Sleeping Dragon' saved at 2002-02-04 16:45:03.63
    'The Matrix' saved at 2002-02-04 16:45:17.5
    'Akira' saved at 2002-02-04 16:45:41.714
The database contains 3 titles.
: reset
Deleting all titles currently in the database...
Deleted 3 titles from the database.
: quit


Exiting...

This example starts out by creating a component interface, HelloDBService, and its implementation class DefaultHelloDBService. HelloDBService defines the following methods:

public interface HelloDBService
    extends Component
{
    String ROLE = "org.apache.avalon.examples.jdbcdatasource.HelloDBService";
    
    /**
     * Adds a single row to the database.
     */
    void addRow( String title );
    
    /**
     * Ask the component to delete all rows in the database.
     */
    void deleteRows();
    
    /**
     * Ask the component to log all of the rows in the database to the logger
     *  with the info log level.
     */
    void logRows();
}

The implementation class, DefaultHelloDBService, must implement the following interfaces; HelloDBService, Composable, Configurable, Initializable, and Disposable. The methods of each interface have a critical role in controlling the life cycle of the component and its interaction with the JdbcDataSource.

The Composable interface defines the compose method. Its job is to store a reference to the ComponentManager which created the component.

public void compose( ComponentManager manager )
{
    m_manager = manager;
}

The Configurable interface defines the configure method. Its job is to extract the name of the Data Source which the component is configured to use.

public void configure( Configuration configuration )
    throws ConfigurationException
{
    // Obtain a reference to the configured DataSource
    m_dataSourceName = configuration.getChild( "dbpool" ).getValue();
}

The Initializable interface defines the initialize method. Its job is to actually obtain a reference to the Data Souurce whose name was obtained during the configuraton phase.

public void initialize()
    throws Exception
{
    // Get a reference to a data source
    m_dbSelector = (ComponentSelector)m_manager.lookup( DataSourceComponent.ROLE + "Selector" );
    m_dataSource = (DataSourceComponent)m_dbSelector.select( m_dataSourceName );
    
    // Initialize the database.
    initializeDatabase();
}

In this example, the data source is defined with a component selector. This has the benefit of allowing multiple Data Sources to be defined for a single application. First obtain a reference to a ComonentSelector with the role: org.apache.jakarta.excalibur.datasource.DataSourceComponentSelector. Next, using the selector, look for the DataSource which was specified in the dbpool tag when configuring the component. Finally, a user method is called to initialize the database.

The Disposable interface defines the dispose method. Its job is release the Data Source and the ComponentSelector used to obtain the Data Source as part of the clean up cycle for the component.

public void dispose()
{
    // Free up the data source
    if ( m_dbSelector != null )
    {
        if ( m_dataSource != null )
        {
            m_dbSelector.release( m_dataSource );
            m_dataSource = null;
        }

        m_manager.release( m_dbSelector );
        m_dbSelector = null;
    }
}

Please take a look at the complete source for the component at DefaultHelloDBService.java in the src/java directory of the example.

This example starts out by creating a component interface, HelloDBService, and its implementation class DefaultHelloDBService. The class is defined inside the roles.xml file with the following definition: (see conf/roles.xml)

<role name="org.apache.avalon.examples.jdbcdatasource.HelloDBService"
      shorthand="hello-db"
      default-class="org.apache.avalon.examples.jdbcdatasource.DefaultHelloDBService"/>

This is not any different than any other component definition.

When the component is configured, however, there is a new tag which must be added to the configuration to tell the component how to locate a JdbcDataSource for its database access: (see conf/components.xml)

<hello-db logger="app">
    <dbpool>test-db</dbpool>
</hello-db>