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:

<data>
    <instance id="departmentDc"
              class="ui.ex1.entity.Department"> (1)
        <fetchPlan extends="_base">
            <property name="employee" fetchPlan="_base"/>
        </fetchPlan>
        <loader/>
        <collection id="employeesDc" property="employee"/> (2)
    </instance>
</data>

1	`InstanceContainer` stores an instance of the `Department` entity that has the `employee` attribute.
2	`CollectionPropertyContainer` stores a collection of instances of the `Employee` entity that is an attribute of the `Department` entity.

Also, you can create a property container programmatically:

@Autowired
private DataComponents dataComponents;

private InstanceContainer<Department> departmentDc;
private CollectionPropertyContainer<Employee> employeesDc;


private void createPropertyContainer() {
    employeesDc = dataComponents.createCollectionContainer(
            Employee.class, departmentDc, "employee");
}

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 Department and Employee entities, the master container is the one storing the Department 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:

@Autowired
private CollectionPropertyContainer<Employee> employeesDc;

private void filterByPosition(Position position) {
    List<Employee> filtered = getEditedEntity().getEmployee().stream()
            .filter(employee -> employee.getPosition().equals(position))
            .collect(Collectors.toList());
    employeesDc.setDisconnectedItems(filtered);
}

private void resetFilter() {
    employeesDc.setDisconnectedItems(getEditedEntity().getEmployee());
}