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(), or the defaulted one after the entity has been deleted, 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.

The consumers are notified once the entity is complete. With detail editors registered, or values to populate which the entity came without, that is once those have been loaded, which with a UI bound is on a background thread, the consumers then being notified after set(Entity) has returned, not before, see set(Entity). The values populated are notified when they arrive, as when an entity is set, an edit made meanwhile likewise ignored.

See Also:
  • 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, and with no value to populate which the entity does not hold, 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, or values to populate, and the editor bound to UI components, these are loaded asynchronously, on a background thread; the method then returns before the detail subtree and the values populated are 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, along with the values populated which were loaded for it. 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:
    • 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, nor a delete, which resets the editor to its defaults notifying Observable.changed(), a delete not being cancellable.

      Returns:
      a sensor notified each time the entity is about to change
      See Also:
    • 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(). A detail editor reset as part of its master's defaults() or clear(), which a detail load on the replace path finds empty, or whose detail load fails, notifies it as well. It is notified with the entity held, never null.

      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. Likewise it fires after the values to populate which the replacement came without have been loaded.

      Returns:
      an observer notified each time the entity is silently replaced
      See Also:
    • 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, unless the replacement comes without values to populate. Those are loaded anew, as for set(Entity), the editor holding the ones it had until they arrive, with replaced() firing once they have. A load still in flight for the entity, which has the same primary key, is left to land. 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. The same goes for the values to populate which an entity with another primary key comes without: they are loaded as the detail editors are, and replaced() fires once they have arrived.

      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:
    • 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:
    • 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.

      A column whose default the database provides, withDefault(), and which has no default value of its own, is left out of the entity, so the database fills it in on insert. So is a foreign key column whose default the database provides, where its foreign key gets no value, the other columns of such a foreign key being null. A default value of a foreign key column does not apply, as the foreign key would then reference an entity which is not loaded, which nothing shows. A foreign key is given a default value via its EntityEditor.EditorValue.defaultValue(). A value given for such a column and then cleared leaves a null in the entity, which the insert leaves out as well, see EntityEditor.EditorTasks.insert().

      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

      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:
    • 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

      Returns:
      an ObservableState indicating whether the entity exists in the database
      See Also:
    • 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:
    • present

      Returns:
      the EntityEditor.Present instance
    • primaryKeyPresent

      ObservableState primaryKeyPresent()
      Returns:
      an ObservableState indicating whether the value of the entity primary key is present
    • valid

      Returns:
      an ObservableState indicating the valid status of the underlying Entity.
      See Also: