LookupField annotation

[knstvk]

Declarative, data-model-level control over the UI component Jmix generates for entity reference attributes: an EntityComboBox (dropdown) or an EntityPicker (view lookup), the actions on it, and optional opt-in lazy loading of dropdown items. Restores the CUBA @Lookup capability dropped in the Jmix migration and extends it with lazy loading that works for any data store, including non-persistent DTO entities. Applications using no annotation are unaffected — the no-annotation code paths are unchanged.

What's included

• Core API (jmix-core, io.jmix.core.entity.annotation): @LookupField (targetable at a class or a reference field), @LookupItemsQuery (explicit JPQL query or byInstanceName), and the LookupType enum (DROPDOWN / VIEW).
• Shared resolution (jmix-flowui): LookupFieldSupport + EffectiveLookupConfig — one source of truth for precedence (field annotation → entity-field-* properties → class annotation) and validation. Consumed by both generators.
• Live component generation: EntityFieldCreationSupport builds the picker/combobox and its lazy items callbacks; the items-fetch logic lives in the shared ItemsFetchCallbackSupport.
• Runtime view templates (builds on Runtime view templates #5225 / Runtime view templates #5226): template-generated detail views now honor the annotation via ComponentXmlFactory. Eager dropdowns render as true eager comboboxes backed by a generated data container; explicit-query and byInstanceName dropdowns render as lazy <itemsQuery>.
• XML: byInstanceName is now expressible directly in a hand-written <entityComboBox><itemsQuery>, with design-time Studio metadata for the attribute.

Behavior

• Items loading: eager (small dictionaries, client-side filtering), explicit paged JPQL query with :searchString, or byInstanceName (query conditions over the instance-name attributes; works for any store). Items load through DataManager, so row-level security applies.
• Never throws: invalid configuration logs a warning and degrades (lazy → eager → view lookup) so a field always renders.

Compatibility

Breaking on the protected/internal surface only (all within *Support extension points): EntityFieldCreationSupport precedence internals moved to LookupFieldSupport; DataLoaderSupport.getSearchString / VALUE_PARAMETER removed; instance-name helpers moved to ItemsFetchCallbackSupport; several bean constructors gained parameters. No released public API is affected.

Testing

Spock integration tests (in-memory HSQL) over resolver precedence/validation, live-component generation, the XML byInstanceName loader, template XML generation with degradation, and an end-to-end template render.

Follow-ups (non-blocking)

• Create a Studio issue to use @LookupField when generating views.
• Support for @LookupField meta-annotation in Dynamic Model. May require changes in the way the metadata store nested annotations like @LookupItemsQuery (currently they are stored as Java annotation objects).

[glebfox]

Should it be empty?