Cogent - Tools for the automatic generation of object-relational bridges.

  Author - Michael A. Ericson (maerics@cs.unm.edu)
    Date - October 2003
     Ver - 0.20a


===============================================================================

OVERVIEW

  Cogent (COde GENerating Tools) is a set of Java classes and command-line
  utilities that automate the task of creating source-code files that
  represent entries in a database and automatically (de)serialize them.
  Cogent can connect to any JDBC enabled database and create source-code
  files that are generated by populating source-code templates (skeletons).
  The resulting code provides a simple object-oriented API to that database.

  This release comes with source-code templates for the Java, Perl, and Ruby
  programming languages but code for any language can be generated by
  creating the appropriate template files.


-------------------------------------------------------------------------------

QUICK START

  1) Make sure your database is running and accepting connections on it's
     assigned port.  Also, ensure that the JDBC connector for this database
     exists in your "CLASSPATH" environment variable.

  2) Edit the properties file "cogent.props" with information about your
     database and the language of source code you want to generate.

  3) Execute "db2src" in the directory that contains this README with:
  
     Windows
       C:\cogent>bin\db2src MY_DATABASE_NAME

     UNIX
       $ ./bin/db2src MY_DATABASE_NAME

  4) Copy the generated files in the "./output" directory to your source tree.


-------------------------------------------------------------------------------

COMMAND-LINE TOOLS

  Cogent consists of three executable programs: db2src, db2xml and xml2src,
  each of which exist in the "bin" directory directly under the install dir.
  
  Db2src (database-to-source) connects to a database and uses the meta-data to
  generate source-code files all in one step.
  
  Db2xml and xml2src work together to achieve the same goal but by using an
  intermediate XML file that describes the database.  By modifying this XML
  file you can customize identifiers that will be used in the source code
  to create a friendlier API.  This is useful because, often, table and column
  names in databases are not meant to be human readable.  By modifying the
  intermediate XML file you can convert cryptic names into something more
  meaningful to a programmer.


-------------------------------------------------------------------------------

SUPPLIED TEMPLATES

  This distribution comes with source-code templates for the Java, Perl, and
  Ruby programming languages.  These templates were all designed to work under
  a generic web-application model, meaning they assume they will be supplied
  with a connection to a database at runtime (e.g. a servlet container handing
  them a connection to a data source) rather than creating their own
  connection at an arbitrary time (e.g. on class loading or instantiation).
  This approach allows for much flexibility in that the classes are not tied
  to any particular data source - the particulars of connection management
  are left to the application itself - as it should be.