Package io.jmix.ui.model

Interface DataContext

All Known Subinterfaces:
DataContextInternal
All Known Implementing Classes:
DataContextImpl, NoopDataContext
@InstallSubject("commitDelegate") public interface DataContext
Interface for tracking changes in entities loaded to UI.

Within DataContext, an entity with the given identifier is represented by a single object instance, no matter where and how many times it is used in object graphs.

  • Method Details

    • find

      @Nullable <T> T find(Class<T> entityClass, Object entityId)
      Returns an entity instance by its class and id.
      Returns:
      entity instance or null if there is no such entity in the context

    • find

      @Nullable <T> T find(T entity)
      Returns the instance of entity with the same id if it exists in this context.
      Returns:
      entity instance or null if there is no such entity in the context

    • contains

      boolean contains(Object entity)
      Returns true if the context contains the given entity (distinguished by its class and id).

    • merge

      @CheckReturnValue <T> T merge(T entity, MergeOptions options)
      Merge the given entity into the context. The whole object graph with all references will be merged.

      If an entity with the same identifier already exists in the context, the passed entity state is copied into it and the existing instance is returned. Otherwise, a copy of the passed instance is registered in the context and returned.

      If the given instance is new and the context doesn't contain an instance with the same identifier, the context will save the new instance on commit(). Otherwise, even if some attributes of the merged instance are changed as a result of copying the state of the passed instance, the merged instance will not be committed. Such modifications are considered as a result of loading more fresh state from the database.

      WARNING: use the returned value because it is always a different object instance. The only case when you get the same instance is if the input was previously returned from the same context as a result of find(Class, Object) or merge().

      Parameters:
      entity - instance to merge
      options - merge options
      Returns:
      the instance which is tracked by the context

    • merge

      @CheckReturnValue <T> T merge(T entity)
      Same as merge(Object, MergeOptions) with default options.

    • merge

      @CheckReturnValue EntitySet merge(Collection entities, MergeOptions options)
      Merge the given entities into the context. The whole object graph for each element of the collection with all references will be merged.

      Same as merge(Object) but for a collection of instances.

      Returns:
      set of instances tracked by the context

    • merge

      @CheckReturnValue EntitySet merge(Collection entities)
      Merge the given entities into the context. The whole object graph for each element of the collection with all references will be merged.

      Same as merge(Object, MergeOptions) but for a collection of instances.

      Returns:
      set of instances tracked by the context

    • remove

      void remove(Object entity)
      Removes the entity from the context and registers it as deleted. The entity will be removed from the data store upon subsequent call to commit().

      If the given entity is not in the context, nothing happens.

    • evict

      void evict(Object entity)
      Removes the entity from the context so the context stops tracking it.

      If the given entity is not in the context, nothing happens.

    • evictModified

      void evictModified()
      Clears the lists of created/modified/deleted entities and evicts these entities.

    • clear

      void clear()
      Evicts all tracked entities.
      See Also:

    • create

      <T> T create(Class<T> entityClass)
      Creates an entity instance and merges it into the context.

      Same as: 

       Foo foo = dataContext.merge(metadata.create(Foo.class));
      Parameters:
      entityClass - entity class
      Returns:
      a new instance which is tracked by the context

    • hasChanges

      boolean hasChanges()
      Returns true if the context has detected changes in the tracked entities.

    • isModified

      boolean isModified(Object entity)
      Returns true if the context has detected changes in the given entity.

    • setModified

      void setModified(Object entity, boolean modified)
      Registers or unregisters the given entity as modified.
      Parameters:
      entity - entity instance which is already merged into the context
      modified - true to register or false to unregister

    • getModified

      Set<Object> getModified()
      Returns an immutable set of entities registered as modified.

    • isRemoved

      boolean isRemoved(Object entity)
      Returns true if the context has registered removal of the given entity.

    • getRemoved

      Set<Object> getRemoved()
      Returns an immutable set of entities registered for removal.

    • commit

      EntitySet commit()
      Commits changed and removed instances using DataManager or a custom commit delegate. After successful commit, the context contains updated instances returned from the backend code.
      Returns:
      set of committed and merged back to the context instances. Does not contain removed instances.
      See Also:

    • getParent

      @Nullable DataContext getParent()
      Returns a parent context, if any. If the parent context is set, commit() method merges the changed instances to it instead of sending them to DataManager or a custom commit delegate.

    • setParent

      void setParent(DataContext parentContext)
      Sets the parent context. If the parent context is set, commit() method merges the changed instances to it instead of sending them to DataManager or a custom commit delegate.

    • addChangeListener

      Subscription addChangeListener(Consumer<DataContext.ChangeEvent> listener)
      Adds a listener to DataContext.ChangeEvent.

    • addPreCommitListener

      Subscription addPreCommitListener(Consumer<DataContext.PreCommitEvent> listener)
      Adds a listener to DataContext.PreCommitEvent.

      You can also add an event listener declaratively using a controller method annotated with Subscribe: 

          @Subscribe(target = Target.DATA_CONTEXT)
    protected void onPreCommit(DataContext.PreCommitEvent event) {
       // handle event here
    }
      Parameters:
      listener - listener
      Returns:
      subscription

    • addPostCommitListener

      Subscription addPostCommitListener(Consumer<DataContext.PostCommitEvent> listener)
      Adds a listener to DataContext.PostCommitEvent.

      You can also add an event listener declaratively using a controller method annotated with Subscribe: 

          @Subscribe(target = Target.DATA_CONTEXT)
    protected void onPostCommit(DataContext.PostCommitEvent event) {
       // handle event here
    }
      Parameters:
      listener - listener
      Returns:
      subscription

    • getCommitDelegate

      @Nullable Function<SaveContext,Set<Object>> getCommitDelegate()
      Returns a function which will be used to commit data instead of standard implementation.

    • setCommitDelegate

      void setCommitDelegate(Function<SaveContext,Set<Object>> delegate)
      Sets a function which will be used to commit data instead of standard implementation.