1. Introduction

This document explains how to invoke OneWebSQL™ code generator. The guide provides an overview of the code generated by OneWebSQL™.

2. How to generate code

2.1. OneWebSQL™ for PowerDesigner

2.1.1. Maven plugin

Example configuration is shown below.

          <configuration>
            <!-- pdm model files  -->
            <model_sets>
                <fileset>
                       <directory>src/main/database</directory>
                       <includes>
                               <include>example-model.pdm</include>
                       </includes>
                </fileset>
            </model_sets>

            <!-- name of the Java™ package for generated classes -->
            <java_default_package>com.example</java_default_package>

            <!-- where to put classes; default: target/generated-sources/onewebsql -->
            <java_output_dir>target/or</java_output_dir>

            <!-- directory with dictionary files -->
            <dictionaries_dir>src/main/database/dictionary-data</dictionaries_dir>;

            <!-- whether the output should be verbose; default: false -->
            <verbose>true</verbose>

            <!-- location of license file -->
            <license_location>${user.home}/.onewebsql/onewebsql-pd2java.lic</license_location>
          </configuration>

Options that must be configured:

2.1.2. Standalone tool

Example usage

# use OWSQL_INSTALL environment variable for easier classpath creation
OWSQL_INSTALL=/path/to/onewebsql-pd2java-1.0.3

# add all lib/*.jar libraries from OneWebSQL installation directory
CP="$OWSQL_INSTALL/lib/onewebsql-pd2java-1.0.3.jar:..."

java -classpath "$CP" \
    com.onewebsql.pd2java.PD2Java \
    -model_sets src/main/database/example-model.pdm \
    -java_default_package com.example \
    -java_output_dir target/or  \
    -dictionaries_dir src/main/database/dictionary-data  \
    -classpath "$OWSQL_INSTALL/lib/onewebsql-runtime-1.0.3.jar" \
    -verbose \
    -license_location ${HOME}/.onewebsql/onewebsql-pd2java.lic

Options that must be configured:

2.2. OneWebSQL™ for ERwin

2.2.1. Maven plugin

Example configuration is shown below.

          <configuration>
            <!-- model files  -->
            <model_sets>
                <fileset>
                       <directory>src/main/database</directory>
                       <includes>
                               <include>example-model.xml</include>
                       </includes>
                </fileset>
            </model_sets>

            <!-- name of the Java™ package for generated classes -->
            <java_default_package>com.example</java_default_package>

            <!-- where to put classes; default: target/generated-sources/onewebsql -->
            <java_output_dir>target/or</java_output_dir>

            <!-- directory with dictionary files -->
            <dictionaries_dir>src/main/database/dictionary-data</dictionaries_dir>;

            <!-- whether the output should be verbose; default: false -->
            <verbose>true</verbose>

            <!-- location of license file -->
            <license_location>${user.home}/.onewebsql/onewebsql-erwin2java.lic</license_location>
          </configuration>

Options that must be configured:

2.2.2. Standalone tool

Example usage

# use OWSQL_INSTALL environment variable for easier classpath creation
OWSQL_INSTALL=/path/to/onewebsql-erwin2java-1.0.3

# add all lib/*.jar libraries from OneWebSQL installation directory
CP="$OWSQL_INSTALL/lib/onewebsql-erwin2java-1.0.3.jar:..."

java -classpath "$CP" \
    com.onewebsql.erwin2java.Erwin2Java \
    -model_sets src/main/database/example-model.xml \
    -java_default_package com.example \
    -java_output_dir target/or  \
    -dictionaries_dir src/main/database/dictionary-data  \
    -classpath "$OWSQL_INSTALL/lib/onewebsql-runtime-1.0.3.jar" \
    -verbose \
    -license_location ${HOME}/.onewebsql/onewebsql-erwin2java.lic

Options that must be configured:

2.3. OneWebSQL™ for Oracle Data Modeler

2.3.1. Maven plugin

Example configuration is shown below.

          <configuration>
            <!-- model files  -->
            <model_sets>
                <fileset>
                       <directory>src/main/database</directory>
                       <includes>
                               <include>example-model.dmd</include>
                       </includes>
                </fileset>
            </model_sets>

            <!-- name of the Java™ package for generated classes -->
            <java_default_package>com.example</java_default_package>

            <!-- where to put classes; default: target/generated-sources/onewebsql -->
            <java_output_dir>target/or</java_output_dir>

            <!-- directory with dictionary files -->
            <dictionaries_dir>src/main/database/dictionary-data</dictionaries_dir>;

            <!-- whether the output should be verbose; default: false -->
            <verbose>true</verbose>

            <!-- location of license file -->
            <license_location>${user.home}/.onewebsql/onewebsql-oracle2java.lic</license_location>
          </configuration>

Options that must be configured:

2.3.2. Standalone tool

Example usage

# use OWSQL_INSTALL environment variable for easier classpath creation
OWSQL_INSTALL=/path/to/onewebsql-oracle2java-1.0.3

# add all lib/*.jar libraries from OneWebSQL installation directory
CP="$OWSQL_INSTALL/lib/onewebsql-oracle2java-1.0.3.jar:..."

java -jar onewebsql-oracle2java-1.0.3.jar \
    com.onewebsql.oracle2java.Oracle2Java \
    -java_default_package com.example \
    -java_output_dir target/or  \
    -dictionaries_dir src/main/database/dictionary-data  \
    -classpath "$OWSQL_INSTALL/lib/onewebsql-runtime-1.0.3.jar" \
    -verbose \
    -license_location ${HOME}/.onewebsql/onewebsql-oracle2java.lic

Options that must be configured:

3. What is generated

For every table or view, OneWebSQL™ generates a set of three or four Java files:

For a non-dictionary table book, OneWebSQL™ generates three Java files: a bean Book, an interface BookDAO, and its implementation BookDAOImpl.

For a dictionary table edition, OneWebSQL™ generates a bean Edition, an interface EditionDAO, and its implementation EditionDAOImpl. It also generates an additional interface EditionDICT with constants representing dictionary rows.

3.1. Java bean

For every table or view, OneWebSQL™ generates a Java bean representing a row in the table or view.

The generated bean contains:

The name of the generated field and method follows camelCase convention if the name of table in the database/model is lowercase with underscore _ separating words. The type of the field is the Java counterpart to database type.

OneWebSQL™ generates two constructors:

See the constructors of the bean Book.

Notice that the Book bean does not have fields and methods corresponding to LOB fields description and cover_image.

3.1.1. Java bean is serializable

Every generated Java bean is serializable and satisfies all requirements of java.io.Serializable interface. In particular, if the table changes, then the serialVersionUID value of the generated bean changes, too.

3.1.2. Hide column value in toString() method

By default, the toString() method prints values of all fields. The printing of some columns can be switched off by setting the dontGenerateToString property for the column. For details on how to set the dontGenerateToString property, see Database Modeling Guide.

3.2. DAO interface

For every table or view, OneWebSQL™ generates DAO interface. For example, for the table author it generates interface AuthorDAO.

The DAO interface defines methods for accessing data in the corresponding table in the database. It contains methods for:

Access methods for LOB fields are shown in the interface BookDAO.

There is a separate set of methods for BLOB field cover_image and for CLOB field description. The BLOB methods take java.io.InputStream or java.io.OutputStream as arguments. The CLOB methods take java.io.Reader or java.io.Writer.

3.2.1. Primary keys

If the table has a primary key, then the following methods are generated:

Order of primary key columns
For a multicolumn key, the order of columns in parameter lists is the same as in the database model file.

Do not change the order of primary key columns in the model
Be careful not to change the order of primary key columns in the model by accident, especially if you have multiple columns of the same type in the key. This is an incompatible change the compiler may not notice: the order of method parameters changes but the signature of the method stays the same.

The methods generated for LOB columns description and cover_image in the table book are shown below.

Warning
If the table has no primary key, then the LOB access methods are NOT generated.

3.2.2. Alternative keys

For every alternative key, there is a method returning an object by the alternative key. For example, if the key has one column isbn, then method getByIsbn() is generated. Similarly, if the alternative key has multiple columns book_id,author_id, then method getByBookIdAuthorId() is generated. The order of columns is the same as in the model file.

Order of key columns
For a multicolumn key, the order of columns the name of the method and in the parameter list and is the same as in the database model file.

Do not change the order of key columns in the model
Be careful not to change the order of key columns by accident, especially if you have multiple columns of the same type in the key. This is an incompatible change the compiler may not notice: the order of method parameters changes but the signature of the method stays the same.

3.2.3. Foreign keys

For every foreign key, there is a set of methods returning objects associated with the foreign key. For an association between tables book and author in BookDAO, generated methods include getBookList(Author) and two methods returning sorted lists getBookList(Author,AExp) and getBookList(Author,AExp,boolean). In AuthorDAO, method getAuthor(Book) returns an author associated with a given book.

3.2.3.1. Self-references

Sometimes the table references itself, as in this somewhat artificial example.

Every author has at most one mother who is also an author. Every mother has one or many child authors. OneWebSQL™ generates a method getMother(Author), returning the mother of the given author. It also generates a method getChildList(Author) and methods returning sorted lists getChildList(Author,AExp) and getChildList(Author,AExp,boolean).

3.2.3.2. Multiple references between two tables

If there is more than one relationship between two tables, names must be given to the roles in additional relationships. The roles in the first relationship may remain nameless. OneWebSQL™ generates a set of methods using the given role names.

If names are given to roles in all relationships, OneWebSQL™ will use role names while generating DAO methods.

3.2.4. Getting value of the primary key from a sequence

If the table's primary key is an integer, then insert methods in DAO can autofill its value. The value is read from a sequence. The method getNextId() returns the next value of the sequence.

By default, the name of the sequence is <table_name>_seq. To change the name of the sequence, set the sequence property for the table. For details see how to set it in your modeling tool, see Power Designer Modeling Guide, ERwin Modeling Guide, or Oracle Data Modeler Guide.

3.3. DAO implementation

The DAO implementation object implements the DAO interface. The name of DAO implementation for a table book is BookDAOImpl. DAO implementation has four constructors:

    public BookDAOImpl(javax.sql.DataSource ds, com.onewebsql.query.DBAdapter dbAdapter) ;
    public BookDAOImpl(javax.sql.DataSource ds, com.onewebsql.query.DBAdapter dbAdapter, com.onewebsql.dao.DaoSchema schema) ;
    public BookDAOImpl(javax.sql.DataSource ds, com.onewebsql.query.DBAdapter dbAdapter, com.onewebsql.dao.DaoMonitor daoMonitor) ;
    public BookDAOImpl(javax.sql.DataSource ds, com.onewebsql.query.DBAdapter dbAdapter, com.onewebsql.dao.DaoSchema schema, com.onewebsql.dao.DaoMonitor daoMonitor) ;

For details about constructors see DAO Guide.

3.4. Dictionaries

For every dictionary table, OneWebSQL™ generates a special dictionary interface. The name of the interface is <TableName>DICT.

The interface has constant field for every row in dictionary table.

public interface EditionDICT {
    public static final Edition PAPERBACK = new Edition(new Integer(1), "paperback", "Paperback");
    public static final Edition HARDCOVER = new Edition(new Integer(2), "hardcover", "Hardcover");
    ...
}

3.4.1. Configure a dictionary

This section describes how to mark the table edition as a dictionary.

The table edition has

Tip
A table without a column code may be a dictionary. However, it is recommended that the column be added to the table and made an alternative key. Then the corresponding DAO will have the method getByCode().

Prepare a special CSV file with table data.

  1. Create directory for dictionary data.
  2. In the directory create file edition.csv. The name of the file has to be in the form <table-name>.csv, where <table-name> is the name of the table in the database.
  3. In the first line list names of columns in the table (as they are named in the model).
    id;name;code
    
    The order of columns doesn't matter. The column names should be separated with semicolon ;. Add extra column code if your table does not have one.
  4. In the following lines list values of the columns. Make sure the order of values is the same as the order of columns in the first line.
    1;Paperback;paperback
    2;Hardcover;hardcover
    
    The value in column code is used as the identifier for the constant generated for this row.

  5. In the generation tool specify dictionaries_dir parameter.
  6. Generate classes.
  7. A dictionary interface is generated.

public interface EditionDICT {
    public static final Edition PAPERBACK = new Edition(new Integer(1), "paperback", "Paperback");
    public static final Edition HARDCOVER = new Edition(new Integer(2), "hardcover", "Hardcover");
    ...
}

3.5. Set Java package

In OneWebSQL™, set the default package for classes by configuring the java_default_package property. The java_default_package property can be changed for a table or view. Then all classes generated for the table (bean, DAO interface, DAO implementation, dictionary interface) are put into this package. See Power Designer Modeling Guide, ERwin Modeling Guide, or Oracle Data Modeler Guide.