Module is.codion.framework.model
Package is.codion.framework.model

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>>
public static interface EntityEditor.EditorValue<T> extends Value<T>
Provides edit access to an Attribute value in the underlying entity being edited.

  • Method Details

    • attribute

      Attribute<T> attribute()
      Returns:
      the attribute

    • set

      void set(@Nullable T value)
      Sets this value, an edit. Ignored while the values of an entity being set are notified, setting an entity never modifying it, see EntityEditor.EditorEntity.
      Specified by:
      set in interface Value<T>
      Parameters:
      value - the value
      Throws:
      IllegalStateException - in case the value is not editable
      See Also:

    • original

      @Nullable T original()
      Returns:
      the original value, or the current one if not modified
      See Also:

    • revert

      void revert()
      Reverts to the original value if modified. This is an edit of this value, like set(Object), applying its propagators, which give their targets their original values back, and throwing an exception if not editable().
      See Also:

    • validate

      void validate()
      Updates the valid state of this value according to the underlying validator
      See Also:

    • persist

      State persist()

      Returns a State controlling 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 State controlling whether the given attribute value should persist when defaults are set
      See Also:

    • valid

      ObservableState valid()
      Returns:
      an ObservableState indicating the valid status of this attribute value.

    • present

      ObservableState present()
      Returns:
      an ObservableState indicating 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 Observable holding the validation message while this value is invalid, empty otherwise
      See Also:

    • warned

      ObservableState warned()

      Returns an ObservableState indicating 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 ObservableState indicating 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 Observable holding the warning for this value, empty when there is none
      See Also:

    • modified

      ObservableState modified()

      Returns an ObservableState instance 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 ObservableState indicating the modified state of the value of the given attribute
      See Also:

    • edited

      Observer<T> edited()

      Returns an observer notified each time this value is modified via set(Object).

      This event is NOT triggered when the value changes due to the entity being set via EntityEditor.EditorEntity.set(Entity), EntityEditor.EditorEntity.defaults() or EntityEditor.EditorEntity.clear().

      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 State instance controlling whether the value of the given attribute is editable. Non-editable values throw an exception on set(Object), values derived via propagate(Attribute, Function) excepted.

      Returns:
      a State controlling the editable state of the value of the given attribute
      See Also:

    • defaultValue

      Value<Supplier<@Nullable T>> defaultValue()

      Returns the Value instance 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 Value instance controlling the default value supplier
      See Also:

    • propagate

      <V> void propagate(Attribute<V> attribute, Function<@Nullable T,@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 via set(Entity, Object), the function is applied to derive the target attribute value. 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 via revert(), leaves the entity as it was. A value persisted when EntityEditor.EditorEntity.defaults() resets the editor, unless null, propagates as if it had just been set. A foreign key value replaced because the referenced entity was updated or deleted elsewhere is not an edit and does not propagate, nor does EntityEditor.EditorEntity.revert().

      When editing via the editor, derived values are set via their respective EntityEditor.EditorValue instances, triggering edit events. When setting values in an entity, derived values are set directly on the entity via Entity.set(Attribute, Object). Either way the target attribute need not be editable().

      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 to
      deriver - the function deriving the target value from the source attribute's value

    • propagate

      <V> void propagate(Attribute<V> attribute, Predicate<@Nullable T> condition, Function<@Nullable T,@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 to
      condition - the condition the value must satisfy to be propagated
      deriver - the function deriving the target value from the source attribute's value

    • set

      void set(Entity entity, @Nullable T value)

      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 value may be null.

      Parameters:
      entity - the entity
      value - the value to set
      See Also: