> Personally, I would prefer a clear simple API like tableByName() and > fieldByName(). The indirection of a Name class would make the API a bit > tedious, and there are already so many classes that seem to leak into > the top-level API.
You're right. There are quite a few types that are not really needed, or at least should be hidden from the public API. This was recently brought up by Christopher Deckers, contributor of the jOOQ Console: https://groups.google.com/d/topic/jooq-user/q6Yf7voPaqQ/discussion There's clearly need for action, eventually. The public API will be reviewed as of jOOQ 3.0.0: https://sourceforge.net/apps/trac/jooq/ticket/1192 Any concrete feedback on current types is welcome! For the record: The jOOQ DSL evolved step by step. It wasn't easy to foresee which types will last and which ones won't. Many "internal" features turned out to be useful in the "external" API. The same may apply to a new Name type (or an improved NamedQueryPart type). This might prove to be very useful for type-checking in SQL syntax clauses that only accept column names, for instance. Name would then be a super-type of TableField. Hard to say right now, so I think the combination of various ways of creating a Name QueryPart might eventually turn out to be a nice-to-have feature for the DSL in general. >> Another option is to use the existing API and enhance it compatibly. >> Take Factory.field(String, QueryPart...) for instance: >> http://www.jooq.org/javadoc/latest/org/jooq/impl/Factory.html#field%28java.lang.String,%20java.lang.Class,%20org.jooq.QueryPart...%29 >> >> It allows for a dedicated escape syntax for QueryPart placeholders >> {0}, {1}, {2} and keywords {keyword}. This could be an option, as >> well, to allow for [escaped names] > > I would prefer jOOQ to just do the right thing if I've told it what the > table (or alias) name is and what the field name is. Telling it to use a > particular escape syntax, or even having to tell it to use _a_ escape > syntax, seem superfluous in a high-level public API. Your immediate use-case doesn't justify the need for such a feature in the public API, indeed. But having such an escape syntax might make implementing custom QueryParts much easier while at the same time allowing for removing quite a few internal classes (which was the case with the {0}, {1} placeholder syntax). While these features seem highly "internal", they turn out to be very useful for jOOQ extension, eventually. The way you're requesting it right now. Not every database uses the same syntax for escaping names, so in jOOQ's plain SQL context, it might turn out to be useful to support a database-independent syntax > I would add something like "This uses the classes that we generated in > Step 2 (with a link)" near the top of pages such as this: > http://www.jooq.org/tutorial.php#step2 I'd prefer to keep it in the manual. The tutorial is external to the manual (think of the PDF version). But of course, I could make the tutorial *part* of the manual... > And/or I might like a link to the actual class names in the example > code. Actually, API links in the example code would be really useful, > though that's a lot of work, and lots of links to keep up-to-date. That's a nice idea. It wouldn't be so much work. The manual is generated from an XML structure. It supports <reference/> tags that can link to jOOQ classes - which are translated to Javadoc links. They're always up to date. I'll think about that, thanks for the hint! Cheers Lukas
