Java Database Object Generator Release Notes 1.3d ------------------------------------------------- Content 1. File List 2. Config Directory 3. Log Directory 4. Target Directory 5. CRUD Generation 6. CRUD Applications 7. usrtab Example 8. Code Changes 1. File List ============ This is a minor extension release of the java database object generator. The release consists of the following files: generator_13d.zip The sources of the java database object generator. usrtab_13d.zip The sources of the administrative functions context. usrtab_13d.sql The databases schema for the administrative functions context. readme_13d.txt This file. readme_13d.zip Archive of previous readmes. For questions concerning the java database object generator please contact: Jan Burse This is a first release of Matula that shows already some OQL support. 2. Config Directory =================== CRUD stands for create, read, update and delete of table. The java database object generator is capabable of automatically generating Java, SQL and JSP code for a little CRUD application. The CRUD application is generated for a set of given tables and a set of given jobs. The tables can reside on different databases. These databases may come from different vendors and my reside on different hosts. There are config files for each database. The databases are grouped into so called database groups. The generator can work with a set of database groups. The root for this structure is the config directory. /generator.properties //deployment.properties //generator.properties //reference.properties ... /generator.properties //deployment.properties //generator.properties ... --------------------------------- Structure of the Config Directory For a database group it is possible to either directly include a database or to only include a reference to a database of an other database group. If we directly include a database in a database group we need to provide a generator.properties file and a deployment.properties file. The generator.properties file contains information for the generator. You should place an empty generator.properties file in the directory and then edit it with the generator itself. longname= comment= icon= ... the whole database view for the generator ... ---------------------------------------------------------------------- Structure of the **generator.properties** file in a database directory The deployment.properties file contains information concerning the connection to the database. We assume that we connect via JDBC to the database. Therefore the JDBC ingredients are needed. If you dont specify a driver the sun default JDBC ODBC Driver is used. If you dont specify the user name or password then the empty string is used. driver= url= user= pass= ----------------------------------------------------------------------- Structure of the **deployment.properties** file in a database directory In case you want to place a short cut to an other database you can place a file reference.properties file into a database group directory. The file should contain the name of the database group where a database with the same name is found. Multiple short cuts are resolved. The file reference.properties has the following format: application= ---------------------------------------------------------------------- Structure of the **reference.properties** file in a database directory In each database group directory you have to place a generator.properties file. This file will contain a description of the database group. Most important it will also contain the target directory of the database group. The target directory determines to which application the database group belongs. code= longname= comment= icon= ---------------------------------------------------------------------------- Structure of the **generator.properties** file in a database group directory 3. Log Directory ================ Multiple applications are supported. Each application needs a log directory. The log directory will contain the information concernig the web deployment of the applications and space for log files and property files. Because the log directory is seperated from the target directory, it is more easily possible to redeploy an application on a web server without changing the log files or property files. You simply deploy into the target directory and leave the log directory unchanged. The log directory has the following structure: /deployment.properties /running.properties /result0.html ... /deployment.properties /running.properties /result0.html ... --------------------------------- Structure of the Log Directory The running.properties file is a property file that is used by the job control subsystem. The result0.html is a result file of a running job. The deployment.properties file contains the web context information. The web context information has the following structure: filesuffix= urlsuffix= ---------------------------------------------------------------------------- Structure of the **deployment.properties** file in a context directory 4. Target Directory =================== Multiple applications are supported. Each application needs a target directory. The target directory will contain the generated code for the database, including jsps, servlets and classes. The target directory will also contain jobs, and code generated for jobs. The target needs a config file, which is only read once when the target context is started by the web server. The file is located as follows: WEB-INF/classes/config.properties ------------------------------------------ Location of the **config.properties** file The config file only contains pointers to directories. Namely a pointer to the config directory and the log directory. These pointers have to be absolute in the file system of the web server. The config file has the following content: modeldir= logdir= ------------------------------------------- Structure of the **config.properties** file The target contains generator.properties files and *.job files, which are interpreted by the CRUD generator. A generator.properties file is used for a branch node or group of jobs. A *.job file is used for a leaf node job. The generator.properties file has the following content: title= rights= config= icon= longname= comment= ------------------------------------------------------------------ Structure of the **generator.properties** file for a job group The format of .job files is the same as the one of .jsp files. The title of a .job job will be derived from the tag inside the file. The title might have the following attributes: <title rights=<the rights> config=<the config jsp> icon=<the icon>><the title> ------------------------------------------------------------------ Structure of the ***.job** file for a job The jobs will be enhanced by some job control by the CRUD Generator. The enhancement starts with the generator.properties file that resides in the root of the web context. Here is an example target directory structure: generator.properties alfa/generator.properties alfa/fido.job alfa/dodo.job beta/generator.properties beta/gaga.job ------------------------ Example target structure The target directory structure is automatically scanned to build a job tree. The job tree will have as nodes jobs and job groups. For the above example we will have the following job tree: generator.properties 1 alfa/generator.properties 1.1 alfa/fido.job 1.2 alfa/dodo.job 2 beta/generator.properties 2.1 beta/gaga.job ---------------------------------------- Job tree of the example target structure 5. CRUD Generation ================== The CRUD generation is controlled over a HTML interface. You have to deploy the java database object generator as a HTTP/JSP application. This is for example done by compiling the .java into WEB-INF/classes. The .class and the .jsp define then the application that can be packed into .war and put on a server. The CRUD generator is started via the following URL: /index.jsp You can then do the following: Databases: - Navigate the database schema. See which databases are defined in the target structure. See which tables are defined in each database, and see which columns and groups are defined in each table. See also which indexes are around and how the integrity looks like. Modify groups, grants/revokes and comments. - Generate the target code for the databases. Simply press the Generate link. When you press the generate link on the target directory level, code will be generated for all tables in all databases. When you press it further down, only code for the corresponding object and its children is generated. - Generate the documentation for the databases. Tab seperated text is generated for the columns, indexes and groups. - Generate a new schema or update a schema. In generate schema you can specifiy the database and a product. Afterwards SQL statements will be generated that are able to create a new database instance. In updatre schema you can specify an already existing database instance. Afterwards SQL statements will be generated that sync the existing database schema with the current database schema. Jobs: - Navigate the jobs tree. See which jobs are defined and what are their sub jobs. Modify titles, grants/revokes and comments. - Generate the target code for the jobs. Simply press the Generate link. The code for the object and its children is generated. When you press the generate link on the job, code will be generated for the job and all its sub jobs. - Generate the documentation for the jobs. Tab seperated text is generated for the jobs and its sub jobs. The model that you define with the generator.properties file and your given tables is essentially an entity relationship model. The generator attemps to generate a class diagramm from it. But its not possible to carry over all the foreign key sets and columns. The conditions to carry over these items into the class diagramm are as follows: MEMBER_NAME_HOMOGENOUS: Deprecated. This required is not anymore enforced as we do not generate anymore the XXXObject.java and XXXCursor.java. MEMBER_NAME_ONLY_THIS_GROUP; Deprecated. This required is not anymore enforced as we do not generate anymore the XXXObject.java and XXXCursor.java. MEMBER_FOREIGN_COLUMN_PRIMARY: Foreign key set foreign columns must all point to a key column. This way the foreign key set can result in reference field that will have the class of the foreign table as type. COLUMN_PRIMARY_INCLUDE_NULL_CONST: To allow a conversion of a reference field back to a foreign key set we have also to take care about reference fields with the value null. The null const value has to be present for those key columns that do not occure in a foreign key set. You can also specifiy rights for your tables and jobs. A right consists of a role name and a access mask. The access mask defines which use cases of the target application will be enabled for the corresponding role. The access mask is coded as a letter combination. The letters have the following meaning: C: Create table. R: Read table row. U: Update table row. D: Delete table row. X: Execute job script. V: View job results. E: Export database. I: Import database. F: Format database. T: Test database. ----------------------- The letter combinations 6. CRUD Applications ==================== The CRUD generator will write its code into the target directory of an application. It will create a new directory for each table in each database. The target directory will thus have the following additional structure after full generation:
etc..
etc.. etc.. ------------------------------------- Directories added to Target Directory In each database/table directory the CRUD generator will put new .java and .jsp files. Some of the .java files will contain SQL, other of the .java files will be servlets. Here is a list and description of the files that will be generated: /
/
Bean.java: Gives a cursor and a row to a table. /
/
List.jsp: Lists a selection of the rows of a table. /
/
New.jsp: Gives a form for a new row in a table. /
/
New.java: Creates the new row in the table. /
/
Update.jsp: Gives a form to update a row in a table. /
/
Update.java: Updates a row in the table. /
/
Remove.java: Removes a row in the table. /
/
Display.jsp: Displays a row in the table. /
/
List.java: Support for tree list. ----------------------------------------------------------------------------------- Code generated for tables Some files will be also generated for databases: export.job: A job that exports the data. import.job: A job that imports the data. format.job: A job that updates the schema. test.job: A job that checks the referential integrity. ---------------------------------------------------------------- Code generated for databases For each job in the job tree the CRUD generator will generate some further .jsp files and also some .java files. Here is a list and description of the files that will be generated: view.jsp: Allows a preview of a job and its sub jobs. exec.jsp: Executes a job and its sub jobs. Start.java: Allows to start a job and its sub jobs. --------------------------------------------------------- Code generated for jobs The CRUD application can be compiled and is then deployed in the same way as the CRUD generator is deployed. Again you do not have to compile the .jsp, as they will be dynamically compiled by the WEB server. You can use for example Tomcat 4.1.24. The CRUD application is started via the following URL: /List.jsp Your config directory has to point to a directory that contains deployment.properties for your application and for the usermodel application. This way the usermodel tables will be accessible and the roles can be checked for your tables and jobs. You can then do the following: - Navigate the database schema. See which databases are defined in the target structure. See which tables are defined in each database. List the rows of a table. - Create a new row for a table. Display a row for a table. Navigate to the rows of a foreign key set. Edit a row for a table. Or remove a row for a table. - Navigate or execute the job tree. See which sub jobs are defined and recursively navigate to them. Execute a job and recursively all its sub jobs. - Inspect the SQL log file. Inspect the object pool. Clear the database connection cache. The generated .jsp can be used to build further application. Either by navigating to them or by including them in other pages, for example to build pages that show multiple tables at once. 7. usrtab Example ================= The administrative utility functions are an example of the application of Matula 1.3. The administrative utility functions consist of the following artefacts: usrtab_13d.sql The databases schema for the administrative functions context. usrtab_13d.zip The sources of the administrative functions context. authtab: In this package you find the automatically generated Java and JSP artefacts. They were generated from the database schema and the meta information attached to the database schema. module.config: This is some support for logging of sql statements, the display of open database connections, and change of the matula root password. module.jobs: This is some support for the execution of jobs, and the viewing of the results of a job. module.remote: This is some support for login handling. Login appears always at the top a page due to header.jsp, seperator.jsp and footer.jsp in the root. There are additional beans to log in or log out. module.skin: This is some support for the preview of available skins and for the choice of a skin by the user. module.sql: This is some support for editing and viewing of sql statements, and the execution of sql statements. If you build another application, and if you need login and or database maintenance, you should copy the corresponding Java and JSP files of module.* to the other context. 8. Code Changes =============== The following changes have been incorporated: AutoIncrement ------------- Auto increment columns are now supported. Auto increment columns are automatically detected for mySQL and SQL Server. Auto increment columns are hidden in the CRUD new and update screens. CondensedDoc ------------ There is now a condensed doclet available. This doclet will create html files and png files. The html files contain the class text and the class interface, the png files contain an automatically generated class diagramm. Diagramms are now also automatically generated for database schemas. Have fun, Jan Burse, 6. Juli 2005