4.5.3.3. Datasource Listeners

Datasource listeners receive notifications of changes in the state of datasources and entities contained in them.

There are four types of listeners. Three of them: ItemPropertyChangeListener, ItemChangeListener and StateChangeListener are defined in the Datasource interface and can be used in any datasource. CollectionChangeListener is defined in CollectionDatasource and can be used only in datasources working with collections of entities.

Example of using datasource listeners:

public class EmployeeBrowse extends AbstractLookup {

    private Logger log = LoggerFactory.getLogger(getClass());

    @Inject
    private CollectionDatasource<Employee, UUID> employeesDs;

    @Override
    public void init(Map<String, Object> params) {
        employeesDs.addItemPropertyChangeListener(event -> {
            log.info("Property {} of {} has been changed from {} to {}",
                    event.getProperty(), event.getItem(), event.getPrevValue(), event.getValue());
        });

        employeesDs.addStateChangeListener(event -> {
            log.info("State of {} has been changed from {} to {}",
                    event.getDs(), event.getPrevState(), event.getState());
        });

        employeesDs.addItemChangeListener(event -> {
            log.info("Datasource {} item has been changed from {} to {}",
                    event.getDs(), event.getPrevItem(), event.getItem());
        });

        employeesDs.addCollectionChangeListener(event -> {
            log.info("Datasource {} content has been changed due to {}",
                    event.getDs(), event.getOperation());
        });
    }
}

The listener interfaces are described below.

  • ItemPropertyChangeListener is added by the Datasource.addItemPropertyChangeListener() method. The listener is invoked when an attribute of an entity contained in the datasource is changed. The modified entity instance itself, the name of changed attribute, old and new values can be obtained from the event object passed to the listener.

    The ItemPropertyChangeListener can be used to react to changes made in an entity instance by UI components, i.e. when a user edits input fields.

  • ItemChangeListener is added by the Datasource.addItemChangeListener() method. The listener is invoked when a selected entity instance returned by the Datasource.getItem() method is changed.

    For Datasource, it happens when another instance (or null) is set to the datasource with setItem() method.

    For CollectionDatasource, this listener is invoked when a selected element is changed in a linked visual component. For example, it may be a selected table row, tree element or item in a drop-down list.

  • StateChangeListener is added by the Datasource.addStateChangeListener() method. The listener is invoked when a state of the datasource is changed. The datasource can be in one of three states corresponding to the Datasource.State enumeration:

    • NOT_INITIALIZED – datasource has just been created.

    • INVALID – the whole DsContext, which this datasource is related to, is created.

    • VALID – datasource is ready: Datasource contains an entity instance or null, CollectionDatasource – collection of instances or an empty collection.

    Receiving a notification about changes in datasource state may be important for complex editors, which consist of several frames where it is difficult to trace the moment of setting an edited entity into the datasource. In this case, StateChangeListener can be used for the delayed initialization of certain screen elements:

    employeesDs.addStateChangeListener(event -> {
    if (event.getState() == Datasource.State.VALID)
        initDataTypeColumn();
});

  • CollectionChangeListener is added by the CollectionDatasource.addCollectionChangeListener() method. The listener is invoked when a entity collection, which is stored in the datasource, is changed. The event object provides the getOperation() method returning value of type CollectionDatasource.Operation: REFRESH, CLEAR, ADD, REMOVE, UPDATE. It indicates the operation that caused the collection changes.