InstanceContainer

The InstanceContainer interface is a root of the data containers hierarchy. It is designed to hold a single entity instance.

You can define InstanceContainer in the XML descriptor in the following way:

<data>
    <instance id="customerDc"
              class="ui.ex1.entity.Customer">
        <fetchPlan extends="_base">
            <property name="city" fetchPlan="_base"/>
            <property name="favouriteBrands" fetchPlan="_base"/>
        </fetchPlan>
        <loader/>
        <collection id="favouriteBrandsDc" property="favouriteBrands"/>
    </instance>
</data>

Methods

InstanceContainer 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. You should always check the returned value for null before using it.

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

  • setFetchPlan - sets a fetch plan 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.

  • getFetchPlan() - returns a fetch plan that must be used when loading entities for this container.

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)
public 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)
public void onCustomerDcItemChange(InstanceContainer.ItemChangeEvent<Customer> event) {
    Customer customer = event.getItem();
    Customer previouslySelectedCustomer = event.getPrevItem();
    // ...
}