3.5.3.1.1. InstanceContainer

The InstanceContainer interface is a root of data containers hierarchy. It is designed to hold a single entity instance and has the following methods:

  • setItem() - sets an entity instance to the container.

  • getItem() - returns the instance stored in the container. If the container is empty, the method throws an exception. Use this method when you are sure that an entity has been set in the container, then you don’t have to check the returned value for null.

  • getItemOrNull() - returns the instance stored in the container. If the container is empty, this method returns null. Always check the returned value for null before using it.

  • getEntityMetaClass() - returns the meta-class of the entity that can be stored in this container.

  • setView() - sets a view that must be used when loading entities for this container. Keep in mind that containers themselves do not load data, so this attribute just indicates the desired view for a loader connected to this container.

  • getView() - returns a view that must be used when loading entities for this container.

InstanceContainer events

The InstanceContainer interface allows you to register listeners to the following events.

  • ItemPropertyChangeEvent is sent when the value of an attribute of the instance stored in the container is changed. Example of subscribing to the event for a container defined in the screen XML with customerDc id:

    @Subscribe(id = "customerDc", target = Target.DATA_CONTAINER)
private void onCustomerDcItemPropertyChange(
        InstanceContainer.ItemPropertyChangeEvent<Customer> event) {
    Customer customer = event.getItem();
    String changedProperty = event.getProperty();
    Object currentValue = event.getValue();
    Object previousValue = event.getPrevValue();
    // ...
}

  • ItemChangeEvent is sent when another instance (or null) is set in the container. Example of subscribing to the event for a container defined in the screen XML with customerDc id:

    @Subscribe(id = "customerDc", target = Target.DATA_CONTAINER)
private void onCustomerDcItemChange(InstanceContainer.ItemChangeEvent<Customer> event) {
    Customer customer = event.getItem();
    Customer previouslySelectedCustomer = event.getPrevItem();
    // ...
}