Regular API vs DSL API

[timowest]

I found the following comparison on your Examples page :

Use the DSL API when:
* You want your code to look like SQL
* You want your IDE to help you with auto-completion (you will not
be able to write select .. order by .. where .. join or any of that
stuff)

Use the regular API when:
* You want to create your query step-by-step, creating query parts
one-by-one
* You need to assemble your query from various places, passing the
query around, adding new conditions and joins on the way

Why do you restrict the DSL API to a builder approach? It could easily
work also in incremental fashion.

The separation adds some unnecessary complexity.

I am just throwing some suggestions, because I have come across
similar design decisions.

[Lukas Eder]

Hi Timo,

You are right. The phrasing from the examples page is not completely accurate. While there seem to be two distinct API. In fact, the implementation is the same, and the DSL API invokes methods from the regular one to build queries. There are two reasons for this separation:

1. For historic reasons: the "regular API" was there first. I added the DSL API later. In the beginning, I didn't even think of the fact, that I could include a DSL in my tool
2. For practical reasons: the "regular API" is might be better to use, when a "builder pattern" needs to be applied, as you put it. I know of many cases, where SQL construction is done most easily by passing an SQL statement object around and adding to it. The DSL imposes a rather strict order of clause additions, and that can be bad at some times.

Cheers
Lukas

2011/1/4 timowest <timo.we...@gmail.com>

[timowest]

Hi Lukas.

Ok, the order aspect is a good point.

Br,
Timo Westkämper.

On Jan 5, 9:38 am, Lukas Eder <lukas.e...@gmail.com> wrote:
> Hi Timo,
>
> You are right. The phrasing from the examples page is not completely
> accurate. While there seem to be two distinct API. In fact, the
> implementation is the same, and the DSL API invokes methods from the regular
> one to build queries. There are two reasons for this separation:
>

>    1. For historic reasons: the "regular API" was there first. I added the

>    DSL API later. In the beginning, I didn't even think of the fact, that I
>    could include a DSL in my tool

>    2. For practical reasons: the "regular API" is might be better to use,

>    when a "builder pattern" needs to be applied, as you put it. I know of many
>    cases, where SQL construction is done most easily by passing an SQL
>    statement object around and adding to it. The DSL imposes a rather strict
>    order of clause additions, and that can be bad at some times.
>
> Cheers
> Lukas
>

> 2011/1/4 timowest <timo.westkam...@gmail.com>

[timowest]

Another point which came to my mind.

How often do you know beforehand if your query will always have a
static structure and could be expressed in DSL form or will be of
varying structure and needs to be expressed with the regular API.

jOOQ enforces this division. Some users might start with the DSL
approach and will need to refactor the whole query into the regular
form when the structure becomes dynamic.

You start with something static and simple and add options which makes
the structure dynamic.

Br,
Timo.

[Lukas Eder]

Some users might start with the DSL approach and will need to refactor the whole query into the regular form when the structure becomes dynamic.

Hmm, I personally think that this is rarely the case, but I might be wrong. Is that something you know from your users? I prefer to keep the DSL API simple but maybe I'll reintroduce a getQuery() method exposing the implementation and the link to the regular API...

[timowest]

In our own query usage, about half of the queries are dynamic. Mostly
because similar static queries are merged into one form.

Actually the enforced order of the DSL API makes it complex, at least
on the code level. The supported use cases are simple.

DSL is about naming methods and supporting fluent / cascaded usage. It
is as simple as the regular form, just different.

Br,
Timo.