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 : jOOQ classes and their usage : The Factory classprevious : next

# The Factory and the jOOQ API

jOOQ exposes a lot of interfaces and hides most implementation facts from client code. The reasons for this are:

The org.jooq.impl.Factory class is the main class from where you will create all jOOQ objects. The Factory implements org.jooq.Configuration and needs to be instanciated with the Configuration's properties:

If you are planning on using several RDBMS (= SQLDialects) or several distinct JDBC Connections in your software, this will mean that you have to create a new Factory every time.

# Factory settings

The jOOQ Factory allows for some optional configuration elements to be used by advanced users. The Settings class is a JAXB-annotated type, that can be provided to a Factory in several ways:

Subsequent sections of the manual contain some more in-depth explanations about these settings:

Please refer to the jOOQ runtime configuration XSD for more details:
http://www.jooq.org/xsd/jooq-runtime-2.1.0.xsd

# Factory subclasses

There are a couple of subclasses for the general Factory. Each SQL dialect has its own dialect-specific factory. For instance, if you're only using the MySQL dialect, you can choose to create a new Factory using any of the following types: 

// A general, dialect-unspecific factory
Factory create = new Factory(connection, SQLDialect.MYSQL);

// A MySQL-specific factory
MySQLFactory create = new MySQLFactory(connection);

The advantage of using a dialect-specific Factory lies in the fact, that you have access to more proprietary RDMBS functionality. This may include:

Another type of Factory subclasses are each generated schema's factories. If you generate your schema TEST, then you will have access to a TestFactory. This will be useful in the future, when access to schema artefacts will be unified. Currently, this has no use.

# Static Factory methods

With jOOQ 2.0, static factory methods have been introduced in order to make your code look more like SQL. Ideally, when working with jOOQ, you will simply static import all methods from the Factory class: 

import static org.jooq.impl.Factory.*;

This will allow to access functions even more fluently: 

concat(trim(FIRST_NAME), trim(LAST_NAME));
// ... which is in fact the same as:
Factory.concat(Factory.trim(FIRST_NAME), Factory.trim(LAST_NAME));

Objects created statically from the Factory do not need a reference to any factory, as they can be constructed independently from your Configuration (connection, dialect, schema mapping). They will access that information at render / bind time. See more details on the QueryParts' internals

# Potential problems

The jOOQ Factory expects its underlying java.sql.Connection to be open and ready for java.sql.PreparedStatement creation. You are responsible yourself for the lifecycle dependency between Factory and Connection. This means:

So if you want your queries to run in separate transactions, if you want to roll back a transaction, if you want to close a Connection and return it to your container, you will have to take care of that yourself. jOOQ's Factory will always expect its Connection to be in a ready state for creating new PreparedStatements. If it is not, you have to create a new Factory.

Please keep in mind that many jOOQ objects will reference your Factory for their whole lifecycle. This is especially interesting, when dealing with Updatable Records, that can perform CRUD operations on the Factory's underlying Connection.


The jOOQ User Manual. Multiple Pages : jOOQ classes and their usage : The Factory classprevious : next

Fork me on GitHub
The jOOQ Logo