Module is.codion.framework.model

Package is.codion.framework.model

Interface EntityEditor.EditorEntity

All Superinterfaces:

Observable<Entity>, Observer<Entity>

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.

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
Observer<Entity>	changing()	Fires 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.
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.observer.Observable

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

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

addConsumer, addListener, addWeakConsumer, addWeakListener, observer, removeConsumer, removeListener, removeWeakConsumer, removeWeakListener, when, when

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. When the editor is bound to UI components only 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. Otherwise the operation is fully synchronous.

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

Observer<Entity> changing()

Fires 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 fire this event, nor do detail editors when reset as part of a master operation.

Returns:

an observer 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. If the primary key changes, 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.

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.

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)