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.

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!]

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.

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
	

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.

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.

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.

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!