5.5.3.1.1. Декларативное создание
Как правило, источники данных объявляются декларативно в элементе 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
.