Configuration and setup of the generator

This version of the manual is outdated. For the latest version, follow this link: http://www.jooq.org/doc/3.0/manual.

The jOOQ User Manual. Multiple Pages : Meta model code generation : Configuration and setup of the generator

previous : next

# The deliverables

There are three binaries available with jOOQ, to be downloaded from SourceForge or from Maven central:

• jOOQ.jar
  The main library that you will include in your application to run jOOQ
• jOOQ-meta.jar
  The utility that you will include in your build to navigate your database schema for code generation. This can be used as a schema crawler as well.
• jOOQ-codegen.jar
  The utility that you will include in your build to generate your database schema

# Dependencies

All of jOOQ's dependencies are "optional", i.e. you can run jOOQ without any of those libraries. For instance, jOOQ maintains an "optional" dependency on log4j and slf4j. This means, that jOOQ tries to find log4j (and /log4j.xml) or slf4j on the classpath. If they are not present, then java.util.logging.Logger is used instead.

Other optional dependencies are the JPA API, and the Oracle JDBC driver, which is needed for Oracle's advanced data types, only

# Configure jOOQ's code generator

You need to tell jOOQ some things about your database connection. Here's an example of how to do it for an Oracle database

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configuration>
  <!-- Configure the database connection here -->
  <jdbc>
    <driver>oracle.jdbc.OracleDriver</driver>
    <url>jdbc:oracle:thin:@[your jdbc connection parameters]</url>
    <user>[your database user]</user>
    <password>[your database password]</password>
    <!-- You can also pass user/password and other JDBC properties in the optional properties tag: -->
    <properties>
      <property><key>user</key><value>[db-user]</value></property>
      <property><key>password</key><value>[db-password]</value></property>
    </properties>
  </jdbc>

  <generator>
    <database>
      <!-- The database dialect from jooq-meta. Available dialects are
           named org.util.[database].[database]Database. Known values are:

           org.jooq.util.ase.ASEDatabase (to be used with Sybase ASE)
           org.jooq.util.cubrid.CUBRIDDatabase
           org.jooq.util.db2.DB2Database
           org.jooq.util.derby.DerbyDatabase
           org.jooq.util.h2.H2Database
           org.jooq.util.hsqldb.HSQLDBDatabase
           org.jooq.util.ingres.IngresDatabase
           org.jooq.util.mysql.MySQLDatabase
           org.jooq.util.oracle.OracleDatabase
           org.jooq.util.postgres.PostgresDatabase
           org.jooq.util.sqlite.SQLiteDatabaes
           org.jooq.util.sqlserver.SQLServerDatabase
           org.jooq.util.sybase.SybaseDatabase (to be used with Sybase SQL Anywhere)

           You can also provide your own org.jooq.util.Database implementation
           here, if your database is currently not supported -->
      <name>org.jooq.util.oracle.OracleDatabase</name>

      <!-- All elements that are generated from your schema (several Java
           regular expressions, separated by comma) Watch out for
           case-sensitivity. Depending on your database, this might be
           important! You can create case-insensitive regular expressions
           using this syntax: (?i:expr)A comma-separated list of regular
           expressions -->
      <includes>.*</includes>

      <!-- All elements that are excluded from your schema (several Java
           regular expressions, separated by comma). Excludes match before
           includes -->
      <excludes></excludes>

      <!-- The schema that is used locally as a source for meta information.
           This could be your development schema or the production schema, etc
           This cannot be combined with the schemata element.

           If left empty, jOOQ will generate all available schemata. See the
           manual's next section to learn how to generate several schemata -->
      <inputSchema>[your database schema / owner / name]</inputSchema>
    </database>

    <generate>
      <!-- See advanced configuration properties -->
    </generate>

    <target>
      <!-- The destination package of your generated classes (within the
           destination directory) -->
      <packageName>[org.jooq.your.packagename]</packageName>

      <!-- The destination directory of your generated classes -->
      <directory>[/path/to/your/dir]</directory>
    </target>
  </generator>
</configuration>

There are also lots of advanced configuration parameters, which will be treated in the manual's next section Note, you can find the official XSD file at http://www.jooq.org/xsd/jooq-codegen-2.1.0.xsd for a formal specification

# Run jOOQ code generation

Code generation works by calling this class with the above property file as argument.

org.jooq.util.GenerationTool /jooq-config.xml

Be sure that these elements are located on the classpath:

• The property file
• jooq.jar, jooq-meta.jar, jooq-codegen.jar
• The JDBC driver you configured

# A command-line example (For Windows, unix/linux/etc will be similar)

• Put the property file, jooq*.jar and the JDBC driver into a directory, e.g. C:\temp\jooq
• Go to C:\temp\jooq
• Run java -cp jooq.jar;jooq-meta.jar;jooq-codegen.jar;[JDBC-driver].jar;. org.jooq.util.GenerationTool /[property file]

Note that the property file must be passed as a classpath resource

# Run code generation from Eclipse

Of course, you can also run code generation from your IDE. In Eclipse, set up a project like this. Note that this example uses jOOQ's log4j support by adding log4j.xml and log4j.jar to the project classpath:

Once the project is set up correctly with all required artefacts on the classpath, you can configure an Eclipse Run Configuration for org.jooq.util.GenerationTool.

With the properties file as an argument

And the classpath set up correctly

Finally, run the code generation and see your generated artefacts

# Run generation with ant

You can also use an ant task to generate your classes. As a rule of thumb, remove the dots "." and dashes "-" from the .properties file's property names to get the ant task's arguments:

<!-- Task definition -->
<taskdef name="generate-classes" classname="org.jooq.util.GenerationTask">
  <classpath>
    <fileset dir="${path.to.jooq.distribution}">
      <include name="jOOQ.jar"/>
      <include name="jOOQ-meta.jar"/>
      <include name="jOOQ-codegen.jar"/>
    </fileset>
    <fileset dir="${path.to.mysql.driver}">
      <include name="${mysql.driver}.jar"/>
    </fileset>
  </classpath>
</taskdef>

<!-- Run the code generation task -->
<target name="generate-test-classes">
  <generate-classes
      jdbcurl="jdbc:mysql://localhost/test"
      jdbcuser="root"
      jdbcpassword=""
      generatordatabaseinputschema="test"
      generatortargetpackage="org.jooq.test.generatedclasses"
      generatortargetdirectory="${basedir}/src"/>
</target>

Note that when running code generation with ant's <java/> task, you may have to set fork="true":

<!-- Run the code generation task -->
<target name="generate-test-classes">
  <java fork="true" classname="org.jooq.util.GenerationTool">
    [...]
  </java>
</target>

# Integrate generation with Maven

Using the official jOOQ-codegen-maven plugin, you can integrate source code generation in your Maven build process:

<plugin>

  <!-- Specify the maven code generator plugin -->
  <groupId>org.jooq</groupId>
  <artifactId>jooq-codegen-maven</artifactId>
  <version>2.4.2</version>

  <!-- The plugin should hook into the generate goal -->
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>

  <!-- Manage the plugin's dependency. In this example, we'll use a Postgres database -->
  <dependencies>
    <dependency>
      <groupId>postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>8.4-702.jdbc4</version>
    </dependency>
  </dependencies>

  <!-- Specify the plugin configuration -->
  <configuration>

    <!-- JDBC connection parameters -->
    <jdbc>
      <driver>org.postgresql.Driver</driver>
      <url>jdbc:postgresql:postgres</url>
      <user>postgres</user>
      <password>test</password>
    </jdbc>

    <!-- Generator parameters -->
    <generator>
      <name>org.jooq.util.DefaultGenerator</name>
      <database>
        <name>org.jooq.util.postgres.PostgresDatabase</name>
        <includes>.*</includes>
        <excludes></excludes>
        <inputSchema>public</inputSchema>
      </database>
      <generate>
        <relations>true</relations>
        <deprecated>false</deprecated>
      </generate>
      <target>
        <packageName>org.jooq.util.maven.example</packageName>
        <directory>target/generated-sources/jooq</directory>
      </target>
    </generator>
  </configuration>
</plugin>

See the full example of a pom.xml including the jOOQ-codegen artefact here: https://github.com/jOOQ/jOOQ/blob/master/jOOQ-codegen-maven-example/pom.xml

# Migrate properties files from jOOQ 1.7, early versions of jOOQ 2.0.x:

Before jOOQ 2.0.4, the code generator was configured using properties files These files are still supported for source code generation, but their syntax won't be maintained any longer. If you wish to migrate to XML, you can migrate the file using this command on the command line

org.jooq.util.GenerationTool /jooq-config.properties migrate

Using the migrate flag, jOOQ will read the properties file and output a corresponding XML file on system out

# Use jOOQ generated classes in your application

Be sure, both jOOQ.jar and your generated package (see configuration) are located on your classpath. Once this is done, you can execute SQL statements with your generated classes.

The jOOQ User Manual. Multiple Pages : Meta model code generation : Configuration and setup of the generator

previous : next