Property Containers

InstancePropertyContainer and CollectionPropertyContainer are designed to work with entity instances and collections that are attributes of other entities.

You can define property containers in the XML descriptor in the following way:

<instance id="userDc"
          class="com.company.onboarding.entity.User"> (1)
    <fetchPlan extends="_base">
        <property name="department" fetchPlan="_base"/>
        <property name="steps" fetchPlan="_base">
            <property name="step" fetchPlan="_base"/>
        </property>
        <property name="hobbies" fetchPlan="_base"/>
    </fetchPlan>
    <loader/>
    <collection id="stepsDc" property="steps"/> (2)
</instance>
1 InstanceContainer stores an instance of the User entity that has the steps attribute.
2 CollectionPropertyContainer stores a collection of UserStep entity instances located in the steps attribute of the User entity.

Methods

Property containers implement the Nested interface that defines methods to get the master container and the name of its attribute to bind the property container to. In the example with User and UserStep entities, the master container is the one storing the User instance.

InstancePropertyContainer works directly with the attribute of the master entity. It means that if you invoke its setItem() method, the value will be set to the corresponding master entity attribute and its ItemPropertyChangeEvent listener will be invoked.

CollectionPropertyContainer contains a copy of the master collection and its methods behave as follows:

  • getMutableItems() returns the mutable list of entities and changes in the list are reflected in the underlying property. That is, if you remove an item from this list, the master attribute will be changed and the ItemPropertyChangeEvent listener will be invoked on the master container.

  • getDisconnectedItems() returns the mutable list of entities, but changes in the list are not reflected in the underlying property. That is, if you remove an item from this list, the master attribute will stay the same.

  • setItems() sets a collection of entities to the container and the underlying property. The ItemPropertyChangeEvent listener is invoked on the master container.

  • setDisconnectedItems() sets a collection of entities to the container, but the underlying master attribute will stay the same.

The getDisconnectedItems() and setDisconnectedItems() methods can be used to temporarily change the representation of the collection in UI, for example to filter a table:

@ViewComponent
private CollectionPropertyContainer<UserStep> stepsDc;

private void filterByDueDate(LocalDate dueDate) {
    List<UserStep> filtered = getEditedEntity().getSteps().stream()
            .filter(userStep -> userStep.getDueDate().isAfter(dueDate))
            .collect(Collectors.toList());
    stepsDc.setDisconnectedItems(filtered);
}

private void resetFilter() {
    stepsDc.setDisconnectedItems(getEditedEntity().getSteps());
}