Interface EntityEditor.EditorValue<T>
- Type Parameters:
T- the attribute value type
- All Superinterfaces:
Observable<T>, Observer<T>, Sensor, Value<T>
- Enclosing interface:
EntityEditor<R extends EntityEditor<R>>
-
Nested Class Summary
Nested classes/interfaces inherited from interface Value
Value.Builder<T,B>, Value.BuilderFactory, Value.Locked, Value.Notify, Value.Validator<T> -
Method Summary
Modifier and TypeMethodDescriptionReturns theValueinstance controlling the default value supplier for the given attribute.editable()Returns aStateinstance controlling whether the value of the given attribute is editable.edited()Returns an observer notified each time this value is modified viaset(Object), and each time it changes along with another value so modified: a value derived from it, a foreign key one of whose columns is modified, a column of a modified foreign key, and so on, transitively, a value derived from a foreign key of a modified column for example.error()Returns the validation message for this value, present only while the value is invalid.modified()Returns anObservableStateinstance indicating whether the value of the given attribute has been modified, that is, if the current value differs from its default value, in case of a new entity, or the original value, in case of an existing entity.original()persist()Returns aStatecontrolling whether the last used value for this attribute should persist when defaults are set.populate()Returns aStatecontrolling whether the editor populates this value, false by default, so that it can be edited where the entity being edited comes without it: a column which is not selected by default,selected(false), a large one typically, or one the table query leaves out.present()<V> voidAdds a propagation mapping from this attribute to the given attribute.<V> voidpropagate(Attribute<V> attribute, Predicate<? super @Nullable T> condition, Function<? super @Nullable T, ? extends @Nullable V> deriver) Adds a conditional propagation mapping from this attribute to the given attribute.voidrevert()Reverts to the original value if modified.voidSets this value, an edit.voidSets the given value for the underlying attribute in the given entity, applying the associated propagators, if any are specified, in case the value changes.valid()The valid state of every value, as itserror(), follows the last validation of the entity as a whole, so a rule spanning attributes is reflected by each value it involves, and an unmodified value of an existing entity is valid unless the validator validates it, seeEntityValidator.validated(Entity, is.codion.framework.domain.entity.attribute.Attribute).voidvalidate()Validates the entity anew, updating the valid state and error of this value, and of every other, according to the underlying validator, for a rule depending on something outside the entity which has changed.warned()Returns anObservableStateindicating whether this value carries a warning — a soft constraint (EntityValidator.warning(Entity, Attribute)).warning()Returns the warning for this value, present only while it carries one.Methods inherited from interface Observable
changed, get, getOrThrow, getOrThrow, is, isNot, isNull, isNullable, optionalMethods inherited from interface Observer
addConsumer, addWeakConsumer, observer, removeConsumer, removeWeakConsumer, sensor, when, whenMethods inherited from interface Sensor
addListener, addWeakListener, removeListener, removeWeakListenerMethods inherited from interface Value
addValidator, clear, link, link, locked, observable, removeValidator, unlink, unlink, update, validate
-
Method Details
-
attribute
-
set
Sets this value, an edit. Ignored while the values of an entity being set are notified, setting an entity never modifying it, seeEntityEditor.EditorEntity.The entity may not hold the value, a column whose default the database provides being left out of a new entity, see
EntityEditor.EditorEntity.defaults(), and a column not selected out of an existing one. A new entity has no value which is not in it, so the first one set is a change from null, as any other edit:modified(), itsoriginal()null, andrevertedto null. For an existing entity the first one set is taken as the value loaded, not as a change, so it does not modify the entity, and it is what a later edit is compared with, by the editor and by the optimistic lock of an update.- Specified by:
setin interfaceValue<T>- Parameters:
value- the value- Throws:
IllegalStateException- in case the value is not editable- See Also:
-
original
-
revert
void revert()Reverts to the original value if modified. This is an edit of this value, likeset(Object), applying its propagators, which give their targets their original values back, and throwing an exception if noteditable().- See Also:
-
validate
void validate()Validates the entity anew, updating the valid state and error of this value, and of every other, according to the underlying validator, for a rule depending on something outside the entity which has changed. The entity is validated on each edit, each entity set and each change of validator without this.- See Also:
-
populate
State populate()Returns a
Statecontrolling whether the editor populates this value, false by default, so that it can be edited where the entity being edited comes without it: a column which is not selected by default,selected(false), a large one typically, or one the table query leaves out. An existing entity which does not hold a value can not have it saved, seeset(Object).A value populated is one the editor holds:
- A new entity holds it, as null,
EntityEditor.EditorEntity.defaults()andEntityEditor.EditorEntity.clear()including it, where a column not selected is otherwise left out, so the entity inserted holds it as well. - An existing entity which is set or replaced without it gets it loaded, by its primary key, along with the
detail editors if any: on a background thread when
AbstractEntityEditor.async()is enabled and a UI is bound, the events firing once it has arrived, otherwise before the call returns. It arrives as a value the entity holds, not as a change, and is notified as when an entity is set. An edit of it made before it arrives is overwritten. Nothing is loaded for an entity without a row. - A fresher instance of the same entity which does not bring it,
EntityEditor.EditorEntity.replace(Entity), as when a table is refreshed, gets it loaded anew, so that the value is as fresh as the rest. The editor holds the value it had until the new one arrives, which is notified only if it differs.
For a foreign key it covers the foreign key's columns, the entity referenced loaded along with them.
Populating a value makes setting an entity asynchronous, as registering a detail editor does. With a UI bound,
EntityEditor.EditorEntity.set(Entity)andEntityEditor.EditorEntity.replace(Entity)of an existing entity which comes without the value return before it has arrived and beforeObservable.changed()orEntityEditor.EditorEntity.replaced()fires, where without it the event has fired by the time the call returns. The entity's other values are in place when the call returns, the value populated is not, so whatever needs the entity complete reacts to the event, not to the call returning. Consecutive calls supersede one another, only the last one's event firing. An entity which holds the value already, a new one included, is set synchronously as before. DisablingAbstractEntityEditor.async()loads the value before the call returns.A change of this state applies from the next entity set, it loads nothing for the one held.
Note that a value the editor holds travels with the entity, to the database and back on each update, and to the consumers of this editor's own
EntityEditor.PersistEvents, a table model based on it taking the row persisted from there. The entity published toPersistenceEventsis without the values populated which are not selected by default, so that such a value does not reach whatever holds the entity as a foreign key reference, a row of another table model, a combo box item or another editor's value, which are selected without it.- Returns:
- a
Statecontrolling whether the editor populates this value - Throws:
IllegalArgumentException- when enabled for an attribute which is neither a column nor a foreign key
- A new entity holds it, as null,
-
persist
State persist()Returns a
Statecontrolling whether the last used value for this attribute should persist when defaults are set.For the master foreign key of a detail editor registered via
EntityEditor.DetailEditors.add(EditorLink)this state is framework-managed: it is held false and locked for as long as the editor is registered.- Returns:
- a
Statecontrolling whether the given attribute value should persist when defaults are set - See Also:
-
valid
ObservableState valid()The valid state of every value, as its
error(), follows the last validation of the entity as a whole, so a rule spanning attributes is reflected by each value it involves, and an unmodified value of an existing entity is valid unless the validator validates it, seeEntityValidator.validated(Entity, is.codion.framework.domain.entity.attribute.Attribute).- Returns:
- an
ObservableStateindicating the valid status of this attribute value.
-
present
ObservableState present()- Returns:
- an
ObservableStateindicating whether the value of this attribute is non-null
-
error
Observable<String> error()Returns the validation message for this value, present only while the value is invalid.
- Returns:
- an
Observableholding the validation message while this value is invalid, empty otherwise - See Also:
-
warned
ObservableState warned()Returns an
ObservableStateindicating whether this value carries a warning — a soft constraint (EntityValidator.warning(Entity, Attribute)).Independent of
valid(): a warned value is a permitted one. Nothing is blocked by this being true.- Returns:
- an
ObservableStateindicating whether this value carries a warning - See Also:
-
warning
Observable<String> warning()Returns the warning for this value, present only while it carries one.
The soft counterpart to
error(): where an error says the value may not be saved, a warning says it may be, and that someone should look at it first.- Returns:
- an
Observableholding the warning for this value, empty when there is none - See Also:
-
modified
ObservableState modified()Returns an
ObservableStateinstance indicating whether the value of the given attribute has been modified, that is, if the current value differs from its default value, in case of a new entity, or the original value, in case of an existing entity.Note that unlike
EntityEditor.EditorEntity.modified()this state does not depend on whether the underlying entity exists.- Returns:
- an
ObservableStateindicating the modified state of the value of the given attribute - See Also:
-
edited
Returns an observer notified each time this value is modified via
set(Object), and each time it changes along with another value so modified: a value derived from it, a foreign key one of whose columns is modified, a column of a modified foreign key, and so on, transitively, a value derived from a foreign key of a modified column for example.This event is NOT triggered when the value changes due to the entity being set via
EntityEditor.EditorEntity.set(Entity),EntityEditor.EditorEntity.defaults()orEntityEditor.EditorEntity.clear(), nor when a foreign key value is replaced because the referenced entity was updated or deleted elsewhere, nor byEntityEditor.EditorEntity.revert(), none of these being an edit, as forpropagate(Attribute, Function).revert()is an edit, a value set back to its original.Note that this event is only triggered if the value actually changes.
- Returns:
- an observer notified when the given attribute value is edited
-
editable
State editable()Returns a
Stateinstance controlling whether the value of the given attribute is editable. Non-editable values throw an exception onset(Object), values derived viapropagate(Attribute, Function)excepted.- Returns:
- a
Statecontrolling the editable state of the value of the given attribute - See Also:
-
defaultValue
Returns the
Valueinstance controlling the default value supplier for the given attribute.Used when the underlying value is not persistent.
Use
EntityEditor.EditorEntity.defaults()to populate the editor with default values.- Returns:
- the
Valueinstance controlling the default value supplier - See Also:
-
propagate
<V> void propagate(Attribute<V> attribute, Function<? super @Nullable T, ? extends @Nullable V> deriver) Adds a propagation mapping from this attribute to the given attribute. Each time this attribute is changed via
set(Object)or in an entity viaset(Entity, Object), the function is applied to derive the target attribute value, as it is each time this attribute changes along with another attribute so changed, as foredited(): a value derived from it, a foreign key one of whose columns is changed, a column of a changed foreign key, and so on, transitively. A foreign key changing along with one of its columns, one it may share with another foreign key, holds null until its entity is loaded, its key set, so the function is given null. Setting the value it already has does not propagate. Setting it back to its original value gives the target attribute its original value back, rather than a derived one, which may differ from what the entity held, so an edit undone, by hand or viarevert(), leaves the entity as it was. A valuepersistedwhenEntityEditor.EditorEntity.defaults()resets the editor, unless null, propagates as if it had just been set, along with the values depending on it which are not null. A foreign key value replaced because the referenced entity was updated or deleted elsewhere is not an edit and does not propagate, nor doesEntityEditor.EditorEntity.revert().When editing via the editor, derived values are set via their respective
EntityEditor.EditorValueinstances, triggering edit events. When setting values in an entity, derived values are set directly on the entity viaEntity.set(Attribute, Object). Either way the target attribute need not beeditable().A target attribute has one propagation mapping, adding another replaces it. The mappings apply in the order their target attributes were added.
The function should depend only on the value it is given. When setting a value in an entity the editor holds a different entity, so the editor's own values say nothing about the one being set.
Propagation is transitive, a value derived for a target attribute in turn applies that attribute's own propagators. It stops as soon as a derived value equals the current one, and an attribute already propagating in the current cascade is given its derived value but propagates no further - so a pair deriving from each other settles after one lap whether or not it ever reaches a fixpoint.
// Populate billing address fields when customer changes editor.value(Invoice.CUSTOMER_FK).propagate(Invoice.BILLINGADDRESS, customer -> customer == null ? null : customer.get(Customer.ADDRESS)); editor.value(Invoice.CUSTOMER_FK).propagate(Invoice.BILLINGCITY, customer -> customer == null ? null : customer.get(Customer.CITY));- Type Parameters:
V- the target attribute value type- Parameters:
attribute- the target attribute to propagate toderiver- the function deriving the target value from the source attribute's value
-
propagate
<V> void propagate(Attribute<V> attribute, Predicate<? super @Nullable T> condition, Function<? super @Nullable T, ? extends @Nullable V> deriver) Adds a conditional propagation mapping from this attribute to the given attribute. It behaves as
propagate(Attribute, Function)when the condition holds for the value, and otherwise leaves the target attribute as it is, nothing propagating from it.Like the function, the condition should depend only on the value it is given.
// Populate the billing address when a customer is selected, keeping it when the customer is cleared editor.value(Invoice.CUSTOMER_FK).propagate(Invoice.BILLINGADDRESS, Objects::nonNull, customer -> customer.get(Customer.ADDRESS));- Type Parameters:
V- the target attribute value type- Parameters:
attribute- the target attribute to propagate tocondition- the condition the value must satisfy to be propagatedderiver- the function deriving the target value from the source attribute's value
-
set
Sets the given value for the underlying attribute in the given entity, applying the associated propagators, if any are specified, in case the value changes.
This method is used by components providing edit functionality outside the editor, such as editable table cells or multi-item editing dialogs, to ensure that derived values are updated along with the primary attribute value.
Note that
valuemay be null.- Parameters:
entity- the entityvalue- the value to set- See Also:
-