3.6.2.1.1. Декларативное создание

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

Как правило, источники данных объявляются декларативно в элементе dsContext дескриптора экрана. В зависимости от взаимного расположения элементов объявлений создаются источники двух разновидностей:

  • если элемент расположен непосредственно в dsContext, создается обычный Datasource или CollectionDatasource, который содержит независимо загруженную сущность или коллекцию;

  • если элемент расположен внутри элемента другого источника, создается NestedDatasource, при этом внешний источник становится его хозяином.

Пример объявления источников данных:

<dsContext>
    <datasource id="carDs" class="com.haulmont.sample.entity.Car" view="carEdit">
        <collectionDatasource id="allocationsDs" property="driverAllocations"/>
        <collectionDatasource id="repairsDs" property="repairs"/>
    </datasource>

    <collectionDatasource id="colorsDs" class="com.haulmont.sample.entity.Color" view="_local">
        <query>
            <![CDATA[select c from sample$Color c order by c.name]]>
        </query>
    </collectionDatasource>
</dsContext>

Здесь источник carDs содержит один экземпляр сущности Car, а вложенные в него allocationsDs и repairsDs содержат коллекции связанных сущностей из атрибутов Car.driverAllocations и Car.repairs соответственно. Экземпляр Car вместе со связанными сущностями проставляется в источник данных извне. Если данный экран является экраном редактирования, то это происходит автоматически при открытии экрана. Источник данных colorsDs содержит коллекцию экземпляров сущности Color, загружаемую самим источником по указанному JPQL-запросу с представлением _local.

Рассмотрим схему XML.

dsContext - корневой элемент.

Элементы dsContext:

  • datasource - определяет источник данных, содержащий единственный экземпляр сущности.

    Атрибуты:

    • id - идентификатор источника, должен быть уникальным для данного DsContext.

    • class - Java класс сущности, которая будет содержаться в данном источнике

    • view - имя представления сущности. Если источник сам загружает экземпляры, то это представление будет использовано при загрузке. В противном случае это представление сигнализирует внешним механизмам о том, как нужно загрузить сущность для данного источника.

    • allowCommit - при установке значения false метод isModified() данного источника всегда возвращает false, а метод commit() ничего не делает. Таким образом, изменения содержащихся в источнике сущностей игнорируются. По умолчанию true, т.е. изменения отслеживаются и могут быть сохранены.

    • datasourceClass - собственный класс реализации источника данных, если необходим.

  • collectionDatasource - определяет источник данных, содержащий коллекцию экземпляров.

    Атрибуты collectionDatasource:

    • refreshMode - режим обновления источника, по умолчанию ALWAYS. В режиме NEVER при вызове refresh() источник не производит загрузку данных, а только переходит в состояние Datasource.State.VALID, оповещает слушателей и сортирует имеющиеся в нем экземпляры. Режим NEVER удобен, если необходимо программно заполнить CollectionDatasource предварительно загруженными или созданными сущностями. Например:

      @Override
public void init(Map<String, Object> params) {
    Set<Customer> entities = (Set<Customer>) params.get("customers");
    for (Customer entity : entities) {
        customersDs.includeItem(entity);
    }
    customersDs.refresh();
}

    • softDeletion - значение false отключает режим мягкого удаления при загрузке сущностей, т.е. будут загружены также и удаленные экземпляры. По умолчанию true.

      Элементы collectionDatasource:

    • query - запрос для загрузки сущностей

  • groupDatasource - полностью аналогичен collectionDatasource, но создает реализацию источника данных, пригодную для использования совместно с компонентом GroupTable.

  • hierarchicalDatasource - аналогичен collectionDatasource, и создает реализацию источника данных, пригодную для использования совместно с компонентами Tree и TreeTable.

    Специфическим атрибутом является hierarchyProperty, задающий имя атрибута сущности, по которому строится иерархия.

Класс реализации источника выбирается неявно на основе имени элемента XML и, как было сказано выше, взаимного расположения элементов. Однако если необходимо применить нестандартный источник данных, его класс может быть явно указан в атрибуте datasourceClass.