DbGen Manual v1.0
Warning: this manual is outdated
Introduction / Installation
Notes / Concepts and Windows
Common Tasks / Technical Support
What is DbGen?
DbGen is a Java code generator that helps database programmer to gain easier access to their data sources. It automates many tedious tasks that a database programmer need to do to access any relational database.
The programmer no longer need to write any SQL code. Instead, he/she just calls the database access methods of the Java objects.
What platforms does DbGen support?
DbGen is written in Java itself which means that it can run on all Java-supported platforms. Currently, we support Microsoft Windows 95/NT and Sun Solaris on SPARC/x86 platforms.
Furthermore, all generated source codes will run on any Java platform.
What are the benefits of using a code generator?
Using a code generator, it is very easy to adapt to changes of database tables. With a single click in DbGen, you just generate a new Java object based on your new table definitions.
What can be archived with DbGen?
It is a time saver. It has been reported that DbGen helps cutting a database programmer's time for at least 50%. More time can be saved when a database project is larger in size where more tables are involved.
It manages table definitions. DbGen can be used to manage all of your table definitions. It even generates SQL CREATE scripts so that you can create the tables more easily.
It generates high performance database-aware objects. DbGen actively monitors the SQL statements being used in executing queries or updates. Its internal cache greatly speed up your database access.
It generates human-readable source codes. DbGen generates source codes that are sufficiently indented and commented. You can run Javadoc on the generated source codes to get your own manual pages for the Java objects.
It does re-engineering. DbGen can import table definitions directly from the database so that you can start rewriting your application immediately with 50% of the work done automatically.
It generates pure and bug-free Java beans. DbGen generates pure Java source codes based on existing standards. The generated codes are expected to be bug-free.
It is an extendable system[1]. DbGen can be extended to fit into any software engineering projects that require special code to be inserted into generated source codes.
Notes: [1] Documentation on how to extend the DbGen source code generation engine is available to source code licensees only.
1. Add dbgen.jar and support.jar to your CLASSPATH environment variable.
2. Add the dbgen installation path (e.g. c:\dbgen-1.0) into your PATH environment variable.
3. Run "dbgen" (or "dbgen your-own-project-file.dat")
Main Window
Workbench
A Workbench contains any number of Projects. The Workbench window shows a list of projects which can be individually expanded into a list of table names. This window is used to select a project or table to work with.
Project
A Project contains any number of table definitions. It also maintains some project-wide settings such as the project name and the package name.
Table Definition
General Tab
Fields Tab
A Table Definition contains everything DbGen needs to know in order to generate any source code for the table. The window contains the following three tabs:
1. General Tab
- Table Name (used in your database)
- Class Name (used in the generated source code)
- Package Name (optional parameter to override project setting)
2. Fields Tab
It shows a list of fields inside this database table.
3. Relations Tab(work in progress)
This space is reserved for a future version of DbGen.
Import Tables (Re-Engineering)
DbGen can import tables directly from your database.
First, select the project where you want to place your imported table definitions. Second, click on Table on the menu bar then Import Tables. A wizard will come up to assist you importing the table definitions.
1. Connect Data Source.
DbGen uses JDBC to get access to your database. Make sure you have your JDBC driver set up to do so. If you use ODBC, then you should be able to use the standard JDBC-ODBC bridge driver . 2. Select Catalog and Tables.
Once you have connected to your data sources, you will be asked to select the Catalog (some database such as Sybase calls this "Database") and a list of table names will be shown. Select the tables you want to import. Tips: You can hold the Control key while clicking on the table names to select multiple tables. Also, you can select a consecutive number of tables by holding the Shift key while clicking on table name.
3. Import Progress Window
Once you clicked on Finish button in the previous window, you will see DbGen begin importing tables and showing you the progress.
If DbGen finds any problem importing the tables, it will save the error messages and reports it back to you at the end of the import.
Common Problems: DbGen may report that it cannot find the primary keys for your tables if either your driver does not support the getPrimaryKeys() method in JDBC or you did not specify the primary key for the tables (example: when you use CREATE INDEX instead of specifying primary keys in your CREATE SQL statement.) In this case, you will need to check the primary manually.
Generate Source Codes
When you click on the Generate Source Codes button, a wizard will come up to further assist you in generating source codes for this project.
1. Select Tables
Select all the tables which you want to generate source codes. You may click on the Select All Tables button to get everything selected automatically. Common Problems: If you don't see any table name in this window, you probably have some problems with the table definitions. DbGen shows only the tables that is ready to be generated, which means: 1. It has a valid table name, 2. It has a valid class name, 3. It has a valid package name, 4. It has at least one primary key.
2. Select Output Directory
Select the output directory where you want to save the generated source codes. DbGen can put the source codes into the right sub-directories as defined by the package name (the default), or it can put all source codes into a single directory. 3. Select Source Code Options and Target Database
DbGen can generate three kinds of source files:
- Data Class - The database-aware Java class for this table.
- Test Class - A simple testing Java program for this table.
- SQL CREATE Script - A CREATE TABLE script for this table.
You also need to select your target database. This is required when you use the SQL CREATE script (because it is database-dependent) and when you use some non-standard compliant database such as mSQL. 4. Provide JDBC Settings for Test classes.
If you generate Test classes from table definitions, you should provide your own JDBC settings right here. Then the generated code will work right out of the box. When you are done, you can click on the Test Connection button to double check your settings.
How do I use DbGen anyway?
First, you create a project. Then, create table definitions for this project. Finally, just click on the Generate Source Codes button.
How do I add or delete a project?
To add a project, just click on the Add Project button in the Tool Bar. Then you should modify the project name in the Project window.
To delete a project, first select the project in the Workbench window, then click on the Delete Project button in the Tool Bar. You will be asked to confirm the deletion.
How do I add or delete a table?
To add a table, first select the project in the Workbench window. Then click on the Add Table button in the Tool Bar.
To delete a table, first select the table in the Workbench window. Then click on the Delete Table button in the Tool Bar. You will be asked to confirm the deletion.
How do I set my package name?
You can set your package names in two ways:
1. Set the package name parameter in the Project window.
2. Set the package name parameter in the Table Definitions window.
If you set a package name for a project, then this package name will be automatically use for its tables. However, if a package name is set in a table definition, then this package name will override the project setting.
How do I compile the generated source code?
In the DbGen distribution, there is a file named "support.jar". This file is needed when you compile any generated source code. You should have added the JAR file when you install DbGen. If not, please add it to your CLASSPATH before compilation.
How do I run an application based on DbGen?
You just need to bundle the "support.jar" file with your application. There is no run-time royalty on distribution of this file.
Always check our home page at http://dbgen.sourceforge.net/ for the updated documentation on DbGen. Also see the SourceForge project web page at http://sourceforge.net/projects/dbgen/
