Introduction
Target Audience
Using Perseus
Components
Resources
To Do
Community Participation
Introduction
Perseus is a code generator. Given an XML document containing
SQL statments and associated input and output parameters,
one Java class is created for each
statement.
2001/11/14
Version 0.6.0.6 is now
available for download.
Target Audience
Developers who are transitioning from another language to
Java, who already know SQL but are not yet up to speed in
JDBC. Perseus eliminates the need for the
developer to write JDBC code.
Developers who like to write complex SQL code are often
frustrated by SQL frameworks which tend to produce simpler
SQL. Perseus doesn't get between the developer and SQL.
Small-scale projects that access a database often end up with
a codebase that is up to half JDBC code (based on my personal
experience). Perseus isolates the JDBC code in
machine-generated classes.
Some projects should not use Perseus.
Perseus does not (currently) permit more than one
database driver to be in use at any given time.
Performance-sensitive projects and those that use transactions
will probably will not want to use Perseus, as the current
version opens a new Connection for each statement. [Hopefully
this will be fixed soon!]
Using Perseus
As the programmer writes an application, each
time a new SQL statement is needed, she adds an entry to
the Perseus SQL
statement description file.
A name is assigned to the statement, which will be the
Java class name of a class generated by Perseus. To run the SQL
statement in the
application code,
the programmer creates an instance of the Perseus class.
The arguments to the constructor are the input parameters to
the SQL statement. For SELECT
statements, the generated class' next() method acts as an
iterator (with the same semantics as the ResultSet.next()
method), and each row is returned as a simple
object with an accessor for each SELECTed parameter from the SQL
statement. (This requires that each instance be immutable,
and that an instance be used only once.)
The generated code acquires JDBC connections from the
singleton object
PerseusConnectionFactory.
This connection factory is designed to work with JDBC2
DataSource objects, but a DriverDataSource adapter is provided
to use if only JDBC1 drivers are available.
Once the connection factory is configured (at runtime),
Perseus-generated SQL classes may be used.
Connection management is handled transparently. If
the SQL statement is not a SELECT, the connection is freed
immediately; if the statement is a SELECT, the connection is
freed as soon either as the result set is exhausted, the
close() method called, or the instance garbage collected.
Components
Perseus consists of a number of components:
Code Generator (codegen) --
The SQL statements to use are specified in an XML
document conforming to the
sqlstmt XML schema.
That document is the input to the
codegen
processor. The processor generates the source code for
the classes that execute the statements enumerated in the
XML document. For example:
java -jar perseus-codegen.jar -d /home/src sqlstmt_document.xml
A directory will be created in /home/src
(if necessary) which
contains the source classes for the statements defined in
sqlstmt_document.xml. If no -d
argument is specified, the source directory is created in
the current directory. There are no other options.
Connection management classes --
There are two connection management classes:
PerseusConnectionFactory and
PerseusDriverDataSource. The
PerseusDriverDataSource class may throw
PerseusDataSourceException.
Ant Taskdef --
An
Ant 1.4
taskdef is part of the distribution.
It is used in the testing directory; see the buildfiles in
the numbered directories for examples.
Resources
For more in-depth information about Perseus, there are
examples,
a document describing the
anatomy of Perseus SQL classes,
and
schema
definitions.
The Perseus project is hosted by
SourceForge.
In fact, Perseus probably wouldn't exist without SourceForge.
It's a fantastic service.
The SourceForge page for the Perseus project is located
here.
To Do
There are several aspects of Perseus that need serious attention:
All statements are currently processed through
PreparedStatement, but due to the current connection handling
scheme, prepared statements cannot be cached.
All Perseus classes must use the same DataSource, meaning that
any project that needs to access two different databases cannot
use Perseus.
The programmer has no access to, and no control of, the Connection
object used by a Perseus SQL class, so it is not possible to
execute a sequence of SQL statements with the same connection,
or to control the transaction state of a connection.
The Ant taskdef always rebuilds all of the source code, as it
currently doesn't look at the file timestamps.
Community Participation
I created Perseus for fun. I expect to use it
at some point, but haven't yet. When I do there are likely to
be lots of improvements and changes, but until then I'm not
likely to do much except get the doc and examples together so
I can release a decent binary distribution.
What you see here, along with the /To Do/ items
above, is pretty much my vision for Perseus. I'd love to hear
bigger, better, or different ideas for where Perseus should go.
Even better would be to see folks make Perseus into what they
need it to be. Jump in!
|