3.6.2.4. Слушатели источников данных

Это устаревший API. Новый API, доступный начиная с v.7.0, описан в разделе Компоненты данных.

Слушатели источников данных (datasource listeners) позволяют получать оповещения об изменении состояния источников данных и экземпляров сущностей, в них находящихся.

Существует четыре типа слушателей. Три из них: ItemPropertyChangeListener, ItemChangeListener и StateChangeListener определены в интерфейсе Datasource и могут быть использованы в любых источниках данных. CollectionChangeListener определен в интерфейсе CollectionDatasource и может быть использован только в источниках данных, работающих с коллекциями сущностей.

По сравнению с ValueChangeListener, слушатели источников данных удобнее для использования с точки зрения контроля над жизненным циклом экрана, поэтому рекомендуется использовать их с компонентами, привязанными к источникам данных.

Пример использования слушателей источников данных:

public class EmployeeBrowse extends AbstractLookup {

    private Logger log = LoggerFactory.getLogger(EmployeeBrowse.class);

    @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());
        });
    }
}

Интерфейсы слушателей описаны ниже.

  • ItemPropertyChangeListener добавляется с помощью метода Datasource.addItemPropertyChangeListener(). Слушатель вызывается, если изменилось значение какого-либо атрибута сущности, находящейся в данный момент в источнике. Через объект события можно получить сам измененный экземпляр, имя измененного атрибута, старое и новое значение.

    Слушатель ItemPropertyChangeListener можно использовать для действий в ответ на изменение пользователем сущности из UI, то есть редактирования полей ввода.

  • ItemChangeListener добавляется с помощью метода Datasource.addItemChangeListener(). Он вызывается при смене выбранного экземпляра, возвращаемого методом getItem().

    Для Datasource это происходит при установке другого экземпляра (или null) методом setItem().

    Для CollectionDatasource данный слушатель вызывается, когда в связанном визуальном компоненте меняется выделенный элемент. Например, это может быть выделенная строка таблицы, элемент дерева, или выделенный элемент выпадающего списка.

  • StateChangeListener добавляется с помощью метода Datasource.addStateChangeListener(). Он вызывается при изменении состояния источника данных. Источник данных может находиться в одном из трех состояний, соответствующих перечислению Datasource.State:

    • NOT_INITIALIZED - источник только что создан.

    • INVALID - создан весь DsContext, к которому относится данный источник.

    • VALID - источник данных в рабочем состоянии: Datasource содержит экземпляр сущности или null, CollectionDatasource - коллекцию экземпляров или пустую коллекцию.

      Получение оповещения об изменении состояния источника может быть актуально для сложных редакторов, состоящих из нескольких фреймов, где сложно отследить момент проставления редактируемой сущности в источник. В этом случае можно использовать слушатель StateChangeListener для отложенной инициализации некоторых элементов экрана:

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

  • CollectionChangeListener добавляется с помощью метода CollectionDatasource.addCollectionChangeListener(). Слушатель вызывается при изменении коллекции сущностей, хранящейся в источнике данных. Объект события имеет метод getOperation(), возвращающий значение типа CollectionDatasource.Operation: REFRESH, CLEAR, ADD, REMOVE, UPDATE. Этот тип указывает операцию, которая привела к изменению коллекции.