This is the end user manual for DaoGen. This manual tries to explain how to use DaoGen application to produce correct high quality code. This is not a manual for SQL programming in general, neither is this a manual for Java, PHP or any other programming language that DaoGen might support. The DaoGen Faq has some answers for frequently asked questions. You are also welcome to DaoGen discussion forums.
1. Basic Consept
DaoGen is a source code generator which produces database handling code and associated value objects. It works without any software installations.
DaoGen will ask you to define the basic code generation options which include database table name, resulting class name, target language (which programming language you want the generated sources for) and number of persistent and non-persistent attributes.
It is important that you supply the right information on each field, since the resulting generated code will be heavily affected by your selections. Malformed information in any of the input fields will make generated code malfunction or not compilable.
After the basic generation options are selected, DaoGen will ask you to provide detailed information on each column in your table. You will have to select a column datatype, the name of column and optinally the names of the variables that these columns are mapped to. Also the preferred ordering for methods returning multiple value objects must be selected.
The final step is the actual code generation. This is done by DaoGen and you will only need to copy-paste the resulting code in your own project. Some tips (like preferred filenames) will be supplied along with the generated code.
2. Naming Tables, Classes, Columns, and Variables
DaoGen does not limit the naming of any tables, classes or columns beyond the limitations of generated programming languages. Thus, it is not allowed to put spaces or dots in the names of the classes, columns or variables. SQL allows the table names to be specified in special format "database.table", where dot will separate the database and the table. No spaces are allowed in the table names either. If you are naming your tables with dot separator, make sure that you provide a valid class name in basic generation options, even if it is othervise not required. If no class name is provided, DaoGen will use the table name you specified as the name of the generated class. This will cause compilation problems, since dots are not allowed in class names.
When you are naming the columns for your database, make sure you write the names strictly the same way they were defined in your SQL CREATE TABLE command. If you have not prepared the database before, you can use whatever naming style you like. However, if you want your generated program-code to obey some naming conventions - other than what your database is using - you should provide the names of the variables that the columns are mapped to. For example, your table has a column named "some_column" and you want the generated Java code to obey the Java naming standard, you should provide the variable name "someColumn" for this column. If you do not provide variable names, the column names will be used as variable names.
3. Persistent and Non-Persistent Attributes
The primary function in DaoGen is the database handling and associated methods and attributes. However DaoGen does support special attributes in valueObjects that are not mapped to any column in the corresponding database table. The values in these attributes will exists only in the runtime memory, and DaoGen does not implement any storage methods for these attributes. In most cases, these attributes are not needed, but for your convenience, DaoGen does have a support for generating the source for them too, should you wish to do so.
To create non-persistent attributes, put the number of the needed attributes in basic generation options "non-persistent variables" field, and name them just like you named the column-variables in the database table. The result will not be seen in generated SQL, but you will find the implementation code in valueObject.
4. Extending the Functionality
The idea of DaoGen is not to produce code for all possible use-cases in DAO programming. If you have a large project and lot's of tables, you will find yourself in a situation where the basic DaoGen API does not provide enough methods for your specific needs. However, this is not a problem.
Since DaoGen produces source code, you can easily modify it to do whatever you want. However, there are at least two ways to do it, and one way is better than the other. Extend the provided API instead of changing it, if you want to do it right. That is, if you need a method which returns 100 first rows in some order, do not modify the "loadAll" method to return the required rows. Instead, just copy the code from loadAll method into a new file, which extends the generated Dao class. The new class could be named like "MyTableDaoExt" and the new method could be called "loadHundredFirst", for example. This way, you can re-generate your Dao classes later and still have your extending functionality. Most Java programmers know that this can be done, but this works well with PHP language too.
The purpose of this kind of extending is that in most cases, many parts of a program will need to do operations in your tables. If you change the proved API so that even the basic functionality does not behave constantly across all tables, your program will be a mess. Also, think about a situation where someone else is extending the program you created (and which uses DaoGen in data access). If you chanced the method loadAll to return only 100 rows in one table, this person, who needs to load *all* rows, will find himself debugging his own code forever without understanding to look inside DaoGen objects that you modified.
5. Using generated XML meta-data
The latest enhancement to DaoGen is the support for importing the DaoGen own meta-data back to generator. All generator versions starting from 2.2.0 will generate an additional XML meta-data file for you. This XML file contains all the information that is needed to re-produce your generated code at any time. This is useful, for example if you want to re-generate your DAO classes with newer DaoGen version, or if you want to make a small modification to generator options without having to re-type all information back to DaoGen. It is strongly recommended to save the generated XML files for later usage.