DataContext

DataContext is an interface for tracking changes in entities loaded to the UI layer. Tracked entities are marked as "dirty" on any modification of their attributes, and DataContext saves dirty entities when its save() method is invoked.

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 graphs of entities contained in this context.

In order to be tracked, an entity must be put into DataContext using its merge() method. If the context does not contain the entity with the same id, the context creates a new instance, copies the state of the passed instance to the new one and returns it. If the context already contains an instance with the same id, it copies the state of the passed instance to the existing one and returns the existing instance. This mechanism allows the context to always have only one instance of an entity with a particular identifier.

When you merge an entity, the whole object graph with the root in this entity will be merged. That is all referenced entities (including collections) will become tracked.

The main rule of using the merge() method is to continue working with the returned instance and discarding the passed one. In most cases, the returned object instance will be different. The only exception is when you pass to merge() an instance that was earlier returned from another invocation of merge() or find() of the same context.

An example of merging an entity into DataContext:

@ViewComponent
private CollectionContainer<Department> departmentsDc;

@Autowired
private DataManager dataManager;

@ViewComponent
private DataContext dataContext;

private void loadDepartment(Id<Department> departmentId) {
    Department department = dataManager.load(departmentId).one();
    Department trackedDepartment = dataContext.merge(department);
    departmentsDc.getMutableItems().add(trackedDepartment);
}

A single instance of DataContext exists for a given view. It is created if there is <data> element in the view XML descriptor.

Data loaders defined in XML automatically merge loaded entities into the DataContext if they don’t have the readOnly="true" attribute. By default, data loaders in entity list views scaffolded by Studio include this attribute, so if you need to track changes and save dirty entities in a list view, remove the readOnly="true" XML attribute for respective loaders.

If a referenced entity is not included in the fetch plan of the view but loaded by lazy loading, it is not merged into the view’s DataContext and hence not tracked for changes. Make sure all entities edited on the view are loaded eagerly by including references to them in the fetch plan.

Obtaining DataContext

  1. DataContext of a view can be obtained in its controller using injection:

    @ViewComponent
private DataContext dataContext;

  2. If you have a reference to a view, you can get its DataContext using the ViewControllerUtils class:

    private void sampleMethod(View sampleView) {
    DataContext dataContext = ViewControllerUtils.getViewData(sampleView).getDataContext();
    // ...
}

Parent DataContext

DataContext instances can form parent-child relationships. If a DataContext instance has parent context, it saves changed entities to the parent instead of saving them to the data store. This feature enables editing aggregates when detail entities are saved only together with the master entity. If an entity attribute is annotated with @Composition, the framework automatically sets parent context in the attribute detail view, so the changed attribute entity will be saved to the data context of the master entity.

You can easily provide the same behavior for any entities and views.

If you open a detail view that should save data to the current view’s data context, use the withParentDataContext() method:

private void detailViewWithCurrentDataContextAsParent() {
    DialogWindow<DepartmentDetailView> dialogWindow = dialogWindows.detail(this, Department.class)
            .withViewClass(DepartmentDetailView.class)
            .withParentDataContext(dataContext)
            .build();
    dialogWindow.open();
}

Events and Handlers

This section describes the DataContext lifecycle events that can be handled in view controllers.

To generate a handler stub in Jmix Studio, select the element in the view descriptor XML or in the Jmix UI structure panel and use the Handlers tab of the Jmix UI inspector panel.

Alternatively, you can use the Generate Handler button in the top panel of the view controller.

SaveDelegate

By default, DataContext saves changed and removed entities using the DataManager.save(SaveContext) method. The saveDelegate handler allows you to customize the logic of saving data, which is especially useful when working with DTO entities. For example, you can save the changed entities with a custom service:

@Autowired
private DepartmentService departmentService;

@Install(target = Target.DATA_CONTEXT)
private Set<Object> saveDelegate(final SaveContext saveContext) {
    return departmentService.saveEntities(
            saveContext.getEntitiesToSave(),
            saveContext.getEntitiesToRemove());
}

The save delegate should return the set of saved instances. If it’s impossible, return the original instances from saveContext.getEntitiesToSave() or just an empty set. Do not return removed instances. DataContext will merge back the returned instances so the view will continue working with the updated state.

ChangeEvent

This event is sent when the context detects changes in a tracked entity, a new instance is merged or an entity is removed.

@Subscribe(target = Target.DATA_CONTEXT)
public void onChange(final DataContext.ChangeEvent event) {
    log.debug("Changed entity: " + event.getEntity());
}

PreSaveEvent

This event is sent before saving changes. In this event listener, you can add arbitrary entity instances to the saved collections returned by getModifiedInstances() and getRemovedInstances() methods, for example:

@Subscribe(target = Target.DATA_CONTEXT)
public void onPreSave(final DataContext.PreSaveEvent event) {
    event.getModifiedInstances().add(department);
}

You can also prevent the save using the preventSave() method of the event, for example:

@Subscribe(target = Target.DATA_CONTEXT)
public void onPreSave2(DataContext.PreSaveEvent event) {
    if (checkSomeCondition()) {
        event.preventSave();
    }
}

PostSaveEvent

This event is sent after saving changes. In this event listener, you can get the collection of saved entities returned from DataManager or a custom save delegate. These entities are already merged into the DataContext. For example:

@Subscribe(target = Target.DATA_CONTEXT)
public void onPostSave(final DataContext.PostSaveEvent event) {
    log.debug("Saved: " + event.getSavedInstances());
}