Module is.codion.framework.model

Package is.codion.framework.model

Interface EntityEditor.EditorEntity

All Superinterfaces:

Observable<Entity>, Observer<Entity>, Sensor

Enclosing interface:

EntityEditor<R extends EntityEditor<R>>

public static interface EntityEditor.EditorEntity
extends Observable<Entity>

Provides access to the entity instance being edited.

A new editor starts out holding a null valued entity, not a defaulted one — present() reports no value for every attribute, including those specifying a default value. Applying the defaults is left to whatever presents the editor, which calls defaults() once it is set up to edit a new record, as the Swing edit panel and the Android edit view both do on construction. The editor can not do so itself: a default value supplied via EntityEditor.EditorValue.defaultValue() is resolved when the defaults are applied, and the edit model must have had the chance to configure those first.

Its consumers receive the entity the editor holds once it has changed, as get() returns it: the one set via set(Entity), or the defaulted or cleared one after defaults() or clear(), never null. Whether it is an existing entity or a new one is told by Entity.exists(), or by this editor's exists() where its predicate has been replaced, up to date when the consumers are notified.

When the entity changes as a whole, via set(Entity), replace(Entity), defaults() or clear(), the editor holds every new value before any is notified, the values which changed being notified one at a time, in the order of the attributes. An edit made while they are notified is ignored, so setting an entity never modifies it, whether the edit comes from a component still showing a value from the previous entity, a combo box filtered by an earlier value clearing its selection for example, or from a consumer of one value setting another. Such a consumer reacts to edits via EntityEditor.EditorValue.edited(), and to the entity having been set via this editor entity's consumers, notified once every value has been.

See Also:

• defaults()

Nested Class Summary

Nested classes/interfaces inherited from interface is.codion.common.reactive.observer.Observer

Observer.Builder<T,B extends Observer.Builder<T,B>>

Method Summary

Modifier and Type	Method	Description
Sensor	changing()	Notified, without data, synchronously when the active entity is about to change via set(Entity), defaults() or clear() — before any loading begins and before the detail subtree is touched.
void	clear()	Clears all values, disregarding the EntityEditor.EditorValue.persist() directive — the difference from defaults(), which retains persistent values.
void	defaults()	Resets this editor to its default values, retaining values flagged to EntityEditor.EditorValue.persist().
EntityEditor.Exists	exists()
Entity	get()
EntityEditor.Modified	modified()	Returns an ObservableState indicating whether any values have been modified.
EntityEditor.Present	present()
ObservableState	primaryKeyPresent()
void	refresh()	Refreshes the active Entity from the database, discarding all changes.
void	replace(Entity entity)	Silently replaces the editor entity values without firing changing() or Observable.changed() events; only replaced() fires.
Observer<Entity>	replaced()	Returns an observer notified each time the entity is silently replaced — via replace(Entity), Unlike Observable.changed(), it is not preceded by changing().
void	revert()	Reverts all attribute value changes, restoring the original values as they were, not applying propagators and regardless of EntityEditor.EditorValue.editable(), unlike EntityEditor.EditorValue.revert().
void	set(Entity entity)	Populates this editor entity with the values from the given entity, making it the active entity.
ObservableState	valid()

Methods inherited from interface is.codion.common.reactive.observable.Observable

changed, getOrThrow, getOrThrow, is, isNot, isNull, isNullable, optional

Methods inherited from interface is.codion.common.reactive.observer.Observer

addConsumer, addWeakConsumer, observer, removeConsumer, removeWeakConsumer, sensor, when, when

Methods inherited from interface is.codion.common.reactive.sensor.Sensor

addListener, addWeakListener, removeListener, removeWeakListener

Method Details

get

Entity get()

Specified by:

get in interface Observable<Entity>

Returns:

an immutable copy of the entity being edited

set

void set(Entity entity)

Populates this editor entity with the values from the given entity, making it the active entity. Use defaults() or clear() to reset the editor.

changing() fires synchronously, before any loading begins; throwing a CancelException from a changing() listener cancels the operation. The active entity itself is then applied synchronously, after which detail editors registered via EntityEditor.DetailEditors.add(EditorLink) are reloaded via their link's load action, with Observable.changed() firing once the full detail subtree is in place. Use replace(Entity) for silent post-persist refreshes that should not re-fire change events.

The active entity is applied synchronously, so get() reflects the new values as soon as this method returns. Without registered detail editors there is nothing to load and the operation is fully synchronous, Observable.changed() having fired by the time this method returns.

With registered detail editors, and the editor bound to UI components, the detail editors are loaded asynchronously, on a background thread; the method then returns before the detail subtree is in place and before Observable.changed() fires. Note that consecutive calls supersede one another in that case, an in-flight load is abandoned when a new one begins and only the last fires Observable.changed(), so it does not necessarily fire once per call. Otherwise the operation is fully synchronous.

The entity the event carries is the one that was set, captured before the load began. It is not re-read when the event fires, so it does not reflect an edit made while the load was in flight; get() does. The values of a detail editor edited in that window do not survive the load, see AbstractEntityEditor.async().

For master editors with registered detail editors the events are ordered bottom-up: changing() fires before the detail subtree is touched; each detail editor is then set (firing Observable.changed(), never changing()); finally Observable.changed() fires on the master once every detail editor is in its post-set state. This makes Observable.changed() the "everything done" signal for the full master/detail tree.

Parameters:

entity - the entity to set

Throws:

NullPointerException - in case the entity is null

IllegalArgumentException - in case the entity is not of the correct type

See Also:

• EntityEditor.EditorValue.defaultValue()
• EntityEditor.EditorValue.persist()
• ValueAttributeDefinition.defaultValue()
• changing()

changing

Sensor changing()

Notified, without data, synchronously when the active entity is about to change via set(Entity), defaults() or clear() — before any loading begins and before the detail subtree is touched. The post-change counterpart is Observable.changed().

Throwing a CancelException from a listener cancels the change. Note that replace(Entity) does not notify it, nor do detail editors when reset as part of a master operation.

Returns:

a sensor notified each time the entity is about to change

See Also:

• set(Entity)
• defaults()
• clear()

replaced

Observer<Entity> replaced()

Returns an observer notified each time the entity is silently replaced — via replace(Entity), Unlike Observable.changed(), it is not preceded by changing().

For master editors with registered detail editors, this fires after the detail subtree has been replaced — by the time listeners run, every detail editor is in its post-persist state. This makes replaced() the "everything done" signal for the full master/detail tree.

Returns:

an observer notified each time the entity is silently replaced

See Also:

• replace(Entity)

replace

void replace(Entity entity)

Silently replaces the editor entity values without firing changing() or Observable.changed() events; only replaced() fires.

If the new entity has the same primary key as the current one (the typical post-persist refresh case), detail editors are not touched — their state is owned by their own persist tasks — and the replacement is fully synchronous, as it is when no detail editors are registered. If the primary key changes, registered detail editors are reloaded via their link's load action, since the master's identity has changed; the entity values are applied synchronously, while as with set(Entity) that detail reload may be performed asynchronously when the editor is bound to UI components, with replaced() firing once the full detail subtree is in place.

Parameters:

entity - the replacement entity

Throws:

NullPointerException - in case the entity is null

IllegalArgumentException - in case the entity is not of the correct type

See Also:

• replaced()
• set(Entity)

refresh

void refresh()

Refreshes the active Entity from the database, discarding all changes.

Throws:

IllegalStateException - in case the active entity does not exist

See Also:

• exists()

defaults

void defaults()

Resets this editor to its default values, retaining values flagged to EntityEditor.EditorValue.persist(). Registered detail editors are reset to their defaults as well.

A persisted value which isn't null applies its propagators, as if it had just been set, in the order of the attributes, so the values derived from it are derived rather than given their defaults, a persisted one included. A persisted null propagates nothing. The derived values are defaults, not edits.

Fires changing() and then Observable.changed() on this editor; throwing a CancelException from a changing() listener cancels the operation. Detail editors are reset silently, firing only replaced(). This is an in-memory reset and is always performed synchronously, even when the editor is bound to UI components.

Note that this is also how a new editor arrives at its default values in the first place, since it starts out holding a null valued entity, see EntityEditor.EditorEntity.

See Also:

• clear()
• EntityEditor.EditorValue.defaultValue()
• EntityEditor.EditorValue.persist()
• ValueAttributeDefinition.defaultValue()
• changing()

clear

void clear()

Clears all values, disregarding the EntityEditor.EditorValue.persist() directive — the difference from defaults(), which retains persistent values. Registered detail editors are cleared as well.

Fires changing() and then Observable.changed() on this editor; throwing a CancelException from a changing() listener cancels the operation. Detail editors are cleared silently, firing only replaced(). Like defaults(), this is an in-memory reset and is always performed synchronously.

See Also:

• defaults()
• changing()

revert

void revert()

Reverts all attribute value changes, restoring the original values as they were, not applying propagators and regardless of EntityEditor.EditorValue.editable(), unlike EntityEditor.EditorValue.revert().

exists

EntityEditor.Exists exists()

Returns:

an ObservableState indicating whether the entity exists in the database

See Also:

• EntityEditor.Exists.predicate()

modified

EntityEditor.Modified modified()

Returns an ObservableState indicating whether any values have been modified.

Note that only existing entities are modified, new, or non-existing entities are never modified.

Returns:

an ObservableState indicating the modified state of this editor entity

See Also:

• EntityEditor.Modified.additional()
• EntityEditor.Exists

present

EntityEditor.Present present()

Returns:

the EntityEditor.Present instance

primaryKeyPresent

ObservableState primaryKeyPresent()

Returns:

an ObservableState indicating whether the value of the entity primary key is present

valid

ObservableState valid()

Returns:

an ObservableState indicating the valid status of the underlying Entity.

See Also:

• EntityEditor.validate(Attribute)
• EntityValidator.validate(Entity)