Package org.eclipse.net4j.db.dml

Structured SQL data manipulation for the Net4j DB framework. The SQL factories create immutable expressions, conditions, references, parameters, and staged statement builders. A completed builder produces an immutable SQLTemplate; compiling that template with an IDBAdapter produces adapter-specific SQL and ordered JDBC parameter occurrences. The compiled SQLStatement is prepared through an existing IDBConnection, then bound and executed using Net4j and JDBC APIs.

SQLParameter is an immutable logical identity with at most one default strategy. A SQLValueSetter performs the complete JDBC operation at one position using a supplied Java value. SQLDefaultSetter performs the complete operation for an implementation-defined default without receiving an application value; that default need not be a SQL column's DEFAULT expression and is distinct from binding a supplied null. A Function converter transforms a Java value before standard JDBC binding. SQLStatement is an immutable compiled definition and binding coordinator; SQLParameterBinder is a separate mutable cursor that manages sequential binding positions and dispatches to the appropriate setter. The compiled statement can also bind defaults directly by position or by parameter identity with definition.bindDefault(statement, index, defaultSetter) or definition.bindDefault(statement, parameter, defaultSetter). Cursor skip() and skip(count) move forward without binding or clearing skipped positions; those positions must be handled separately when they need current values, especially when a prepared statement is reused.

For example, given schema fields id, name, an IDBTable table, an IDBAdapter adapter, and an IDBConnection connection:

 SQLParameter idParameter = SQL.param();
 SQLParameter nameParameter = SQL.param();
 SQLStatement definition = SQL.select(id, name) //
     .from(table) //
     .where(id).eq(idParameter).and(name).eq(nameParameter) //
     .compile(adapter);
 IDBPreparedStatement statement = definition.prepare(connection, ReuseProbability.HIGH);
 definition.bind(statement, 42); // Partial prefixes are allowed; returns the number bound.
 definition.bindFrom(statement, 2, "Ada"); // Binds one value at position 2; returns 1.
 definition.bindAll(statement, 42, "Ada"); // Requires both placeholder values; returns 2.
 definition.bindParameter(statement, idParameter, 42); // Binds every matching identity occurrence.
 definition.binder(statement).bind(42, "Ada"); // Independent stateful cursor.
 definition.binderFrom(statement, 2).bind("Ada"); // Independent cursor starting at position 2.
 try
 {
   ResultSet results = statement.executeQuery();
   // Consume results here.
 }
 finally
 {
   statement.close();
 }
 

Each use of a parameter creates a JDBC occurrence. Identity binding matches the exact parameter object and binds every occurrence; positional binding affects only the requested occurrence. Explicit setters override converters and default JDBC binding; explicit converters override configured parameter strategies; otherwise a configured setter precedes a configured converter and then default binding. Setters receive null and own its JDBC handling. Converters bypass null input, run once for each occurrence, and use the explicit or field-inferred type if they produce null. Reusing a statement after partial binding can leave older JDBC values at untouched positions. Binding is not atomic: a later converter or JDBC failure can follow earlier successful JDBC setters.

A configured setter may retain captured objects through the parameter and compiled statement. The API permits stateful setters; callers choose whether reuse, mutable state, thread safety, and connection-specific or execution-specific dependencies fit the setter's use.

Simple fluent condition chains follow SQL precedence: AND binds more tightly than OR, so where(a).eq(p1).or(b).eq(p2).and(c).eq(p3) means A OR (B AND C). To request (A OR B) AND C, compose complete conditions with SQLCondition.or(SQLCondition) and SQLCondition.and(SQLCondition). The compiler preserves this structured grouping and inserts necessary parentheses.

INSERT offers three alternatives: values(...) uses schema field order; columns(...).values(...) maps values to an explicit column list; and set(column).to(value) uses explicit named assignments. Do not mix these forms.

A direct expression in ORDER BY is ascending by default. Use SQL.asc(expression) or SQL.desc(expression) for explicit direction; orderByDesc() and thenByDesc() are convenience forms. Ordering items retain their supplied order.

Structured expressions such as SQL.add(), SQL.multiply(), SQL.and(), and SQL.or() retain semantic structure for precedence-aware parentheses. By contrast, SQL.fragment() accepts trusted raw text that is not parsed; explicitly group fragment expressions when needed. Raw text must not contain ?, even inside a quoted literal.

Scalar and IN subqueries must project exactly one column; EXISTS and NOT EXISTS have no such width restriction. Width is checked at compilation. Repeated from() calls create comma-separated sources unless followed by joins; when joins follow multiple sources, they are grouped as a CROSS JOIN left operand, and subsequent joins associate left-to-right. Arbitrary explicit JOIN-tree nesting is not supported.

SQL NULL comparisons keep SQL semantics: column = NULL is not rewritten. Use SQL.isNull(expression) or SQL.isNotNull(expression) for NULL tests.

For the complete guide, see the Net4j DB Framework Help contents.