You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@avalon.apache.org by le...@apache.org on 2002/02/07 08:16:33 UTC
cvs commit: jakarta-avalon-excalibur/src/xdocs examples-jdbcdatasource.xml book.xml excalibur.uris
leif 02/02/06 23:16:33
Modified: src/xdocs book.xml excalibur.uris
Added: src/xdocs examples-jdbcdatasource.xml
Log:
Add new jdbcdatasource example.
Revision Changes Path
1.6 +4 -0 jakarta-avalon-excalibur/src/xdocs/book.xml
Index: book.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/xdocs/book.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- book.xml 3 Jan 2002 13:37:26 -0000 1.5
+++ book.xml 7 Feb 2002 07:16:33 -0000 1.6
@@ -38,6 +38,10 @@
<menu-item label="Thread Pool Management" href="thread.html"/>
<menu-item label="Source Resolving" href="source.html"/>
</menu>
+
+ <menu label="Example Applications">
+ <menu-item label="JDBC Data Source" href="examples-jdbcdatasource.html"/>
+ </menu>
</book>
1.5 +2 -0 jakarta-avalon-excalibur/src/xdocs/excalibur.uris
Index: excalibur.uris
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/src/xdocs/excalibur.uris,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- excalibur.uris 11 Sep 2001 15:15:16 -0000 1.4
+++ excalibur.uris 7 Feb 2002 07:16:33 -0000 1.5
@@ -25,3 +25,5 @@
images/header.gif
images/jakarta-logo.gif
images/cache.png
+examples-jdbcdatasource.html
+
1.1 jakarta-avalon-excalibur/src/xdocs/examples-jdbcdatasource.xml
Index: examples-jdbcdatasource.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document SYSTEM "dtd/document-v10.dtd">
<document>
<header>
<title>Jdbc Data Source Example Application</title>
<subtitle>Introduction</subtitle>
<authors>
<person name="Leif Mortenson" email="leif@silveregg.co.jp"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<para>
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.
</para>
<para>
This example assumes that you are familiar with configuration files and with the
Logger system.
</para>
</section>
<section>
<title>Running the Example Application</title>
<para>
To run the application, follow these steps.
<list>
<li>Download and build the <code>jakarta-avalon project</code>.</li>
<li>Download the <code>jakarta-avalon-excalibur</code> project into the same
parent directory as <code>jakarta-avalon</code> and run <code>build</code>
</li>
<li>cd into the <code>jakarta-avalon-excalibur/examples/jdbcdatasource</code>
directory and run build. This will build the example application.
</li>
<li>cd into the <code>jakarta-avalon-excalibur/examples/jdbcdatasource/bin</code>
directory and execute the <code>run</code> script.</li>
</list>
</para>
<para>
Once the application is running, you should see the following:
<programlisting format="linespecific"><![CDATA[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)
:]]></programlisting>
</para>
<para>
The application allows you to enter the commands <code>RESET</code> to delete all
titles from the database, <code>LIST</code> to list all the titles in the database,
or <code>QUIT</code> 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.
</para>
<para>
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:
<programlisting format="linespecific"><![CDATA[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...]]></programlisting>
</para>
</section>
<section>
<title>So How Does It All Work?</title>
<para>
This example starts out by creating a component interface,
<code>HelloDBService</code>, and its implementation class
<code>DefaultHelloDBService</code>. <code>HelloDBService</code> defines the
following methods:
<programlisting format="linespecific"><![CDATA[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();
}]]></programlisting>
</para>
<para>
The implementation class, <code>DefaultHelloDBService</code>, must implement the
following interfaces; <code>HelloDBService</code>, <code>Composable</code>,
<code>Configurable</code>, <code>Initializable</code>, and <code>Disposable</code>.
The methods of each interface have a critical role in controlling the life cycle of
the component and its interaction with the JdbcDataSource.
</para>
<para>
The <code>Composable</code> interface defines the <code>compose</code> method. Its
job is to store a reference to the ComponentManager which created the component.
<programlisting format="linespecific"><![CDATA[public void compose( ComponentManager manager )
{
m_manager = manager;
}]]></programlisting>
</para>
<para>
The <code>Configurable</code> interface defines the <code>configure</code> method.
Its job is to extract the name of the Data Source which the component is configured
to use.
<programlisting format="linespecific"><![CDATA[public void configure( Configuration configuration )
throws ConfigurationException
{
// Obtain a reference to the configured DataSource
m_dataSourceName = configuration.getChild( "dbpool" ).getValue();
}]]></programlisting>
</para>
<para>
The <code>Initializable</code> interface defines the <code>initialize</code> method.
Its job is to actually obtain a reference to the Data Souurce whose name was
obtained during the configuraton phase.
<programlisting format="linespecific"><![CDATA[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();
}]]></programlisting>
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:
<code>org.apache.jakarta.excalibur.datasource.DataSourceComponentSelector</code>.
Next, using the selector, look for the DataSource which was specified in the
<code>dbpool</code> tag when configuring the component. Finally, a user method is
called to initialize the database.
</para>
<para>
The <code>Disposable</code> interface defines the <code>dispose</code> 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.
<programlisting format="linespecific"><![CDATA[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;
}
}]]></programlisting>
</para>
<para>
Please take a look at the complete source for the component at
<code>DefaultHelloDBService.java</code> in the <code>src/java</code> directory of
the example.
</para>
<para>
This example starts out by creating a component interface,
<code>HelloDBService</code>, and its implementation class
<code>DefaultHelloDBService</code>. The class is defined inside the roles.xml file
with the following definition: (see <code>conf/roles.xml</code>)
<programlisting format="linespecific"><![CDATA[<role name="org.apache.avalon.examples.jdbcdatasource.HelloDBService"
shorthand="hello-db"
default-class="org.apache.avalon.examples.jdbcdatasource.DefaultHelloDBService"/>]]></programlisting>
This is not any different than any other component definition.
</para>
<para>
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 <code>conf/components.xml</code>)
<programlisting format="linespecific"><![CDATA[<hello-db logger="app">
<dbpool>test-db</dbpool>
</hello-db>]]></programlisting>
</para>
</section>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/02/07 07:16:33 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>