Module org.jooq
Package org.jooq.impl

Class QOM

java.lang.Object
org.jooq.impl.QOM
@Experimental public final class QOM extends Object
A draft of the new query object model API.

This API is EXPERIMENTAL. Use at your own risk.

Purpose

This class provides a single namespace for jOOQ's query object model API. Every QueryPart from the DSL API has a matching QueryPart representation in this query object model API, and a shared internal implementation in the org.jooq.impl package, that covers both the DSL and model API functionality.

The goal of this model API is to allow for expression tree transformations via QueryPart#$replace(Function1) as well as via per-querypart methods, such as for example QOM.Substring.$startingPosition(Field), and traversals via QueryPart.$traverse(Traverser) that are independent of the DSL API that would otherwise be too noisy for this task.

Design

In order to avoid conflicts between the model API and the DSL API, all model API in this class follows these naming conventions:

  • All public model API types are nested in the QOM class, whereas DSL API types are top level types in the org.jooq package.
  • All accessor methods and their corresponding "immutable setters" (returning a copy containing the modification) are named $property(), e.g. QOM.Substring.$startingPosition() and QOM.Substring.$startingPosition(Field).
  • All private model API utility types are named UXyz, e.g. QOM.UEmpty

Limitations

The API offers public access to jOOQ's internal representation, and as such, is prone to incompatible changes between minor releases, in addition to the incompatible changes that may arise due to this API being experimental. In this experimental stage, the following limitations are accepted:

  • Not all QueryPart implementations have a corresponding public QueryPart type yet, but may just implement the API via a QOM.UEmpty or QOM.UNotYetImplemented subtype, and may not provide access to contents via accessor methods.
  • Some child elements of a QueryPart may not yet be represented in the model API, such as for example the SELECT … FOR UPDATE clause, as substantial changes to the internal model are still required before being able to offer public access to it.

Mutability

While some elements of this API are historically mutable (either mutable objects are returned from QueryPart subtypes, or argument objects when constructing an QueryPart remains mutable, rather than copied), users must not rely on this mutable behaviour. Once this API stabilises, all mutability will be gone, accidental remaining mutability will be considered a bug.

Notes

A future Java 17 distribution of jOOQ might make use of sealed types to improve the usability of the model API in pattern matching expressions etc. Other Java language features that benefit pattern matching expression trees might be adopted in the future in this area of the jOOQ API.

Author:
Lukas Eder