new
Creates a new Entity instance with the fields set in the init block, schedules its insert into the entity cache without flushing, and returns it — all without suspending.
Unlike newSuspend, which flushes before returning, this performs no database access whatsoever, which is what makes it callable from a non-suspending context: an entity initialization block, a plain factory function, or a builder that assembles a whole object graph before touching the connection. A transaction still has to be in context, since the pending insert is held by that transaction's EntityCache.
This is not the JDBC DAO's new. There, new { } issues the INSERT before it returns; here the statement is deferred, which is why the entity it returns is not yet hydrated. newSuspend is the function with the JDBC semantics.
The returned entity usually has no id yet — the row does not exist, so neither does its auto-generated key. Until the insert is issued, EntityID.value throws for such an entity and it cannot be looked up by id through findById or testCache. An id is available immediately only when it does not come from the database: an explicit id argument, or an id column with a client-side default such as uuid("id").autoGenerate().
What does work before the flush is reading and writing the entity's own columns, which are served from the entity cache, and using the entity as a reference target: the child stores the very EntityID instance that the parent's insert fills in, and EntityCache.flush orders inserts so the parent is written first.
The pending insert is issued at the first of:
an explicit flushCache or EntityCache.flush;
any other statement executed in the same transaction — a query flushes the entities of the tables it reads, while an insert, update, upsert, delete or DDL statement flushes everything pending;
the transaction's commit.
Everything still pending for one table is written by a single batch statement, so scheduling several entities and flushing once is the cheapest way to insert many rows through the DAO. Use newSuspend instead where a suspending context is available and the id is needed right away.
Return
The created entity, scheduled for insert but not yet written to the database.
Parameters
Block where the entity's fields can be set. Must be non-suspending, since scheduling is performed synchronously.
Throws
if there is no transaction in context.
Composite/explicit-id variant of new. Passing a non-null id is also the way to obtain an entity whose id is usable before the insert is issued.
Return
The created entity, scheduled for insert but not yet written to the database.
Parameters
The id of the entity. Set this to null if it should be automatically generated.
Block where the entity's fields can be set. Must be non-suspending.
Throws
if there is no transaction in context.