3.5.4.3. DataLoadCoordinator

API 文档

DataLoadCoordinator facet 设计用来声明式的将数据加载器和数据容器、可视化组件、界面事件进行连接。其有两种工作模式：

• 自动模式，依赖于使用特定前缀的参数名称。前缀表示产生参数值和更改事件的组件。如果加载器的查询语句中没有参数（尽管在查询条件中可能有参数），则该加载器会在 界面 的BeforeShowEvent或 界面片段 的AttachEvent中自动刷新。

  默认情况下，数据容器的参数前缀是 container_，可视化组件的参数前缀是 component_。

• 手动模式，连接通过 facet 或者通过 API 配置。

也可以有半自动模式，有些连接通过显式指定，而其它的则配置为自动模式。

当在界面中使用 DataLoadCoordinator 是，界面控制器的 @LoadDataBeforeShow 注解将会失去作用，因为数据的加载通过 facet 和自定义的时间处理器（如果有的话）控制。

参阅下面的使用示例。

1. 自动配置，auto 属性设置为 true。

   <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
           xmlns:c="http://schemas.haulmont.com/cuba/screen/jpql_condition.xsd" ...>
       <data readOnly="true">
           <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
               <loader id="ownersDl">
                   <query>
                       <![CDATA[select e from demo_Owner e]]> (1)
                       <condition>
                           <c:jpql>
                               <c:where>e.category = :component_categoryFilterField</c:where> (2)
                           </c:jpql>
                           <c:jpql>
                               <c:where>e.name like :component_nameFilterField</c:where> (3)
                           </c:jpql>
                       </condition>
                   </query>
               </loader>
           </collection>
           <collection id="petsDc" class="com.company.demo.entity.Pet">
               <loader id="petsDl">
                   <query><![CDATA[select e from demo_Pet e where e.owner = :container_ownersDc]]></query> (4)
               </loader>
           </collection>
       </data>
       <facets>
           <dataLoadCoordinator auto="true"/>
       </facets>
       <layout>
           <pickerField id="categoryFilterField" metaClass="demo_OwnerCategory"/>
           <textField id="nameFilterField"/>

   1	- 查询中没有参数，所以 ownersDl 加载器会在 BeforeShowEvent 触发。
   2	- ownersDl 加载器也会在 categoryFilterField 组件值更改的时候触发。
   3	- ownersDl 加载器也会在 nameFilterField 组件值更改的时候触发。由于条件使用了 like 子句，值会被自动包装在 ‘(?i)% %’ 中，以便提供大小写不敏感查找。
   4	- petsDl 加载器会在 ownersDc 数据容器内容变化时触发。

2. 手动配置，auto 属性未设置（或设置为 false），嵌套的记录定义了数据加载器会何时触发。

   <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
           xmlns:c="http://schemas.haulmont.com/cuba/screen/jpql_condition.xsd" ...>
       <data readOnly="true">
           <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
               <loader id="ownersDl">
                   <query>
                       <![CDATA[select e from demo_Owner e]]>
                       <condition>
                           <c:jpql>
                               <c:where>e.category = :category</c:where>
                           </c:jpql>
                           <c:jpql>
                               <c:where>e.name like :name</c:where>
                           </c:jpql>
                       </condition>
                   </query>
               </loader>
           </collection>
           <collection id="petsDc" class="com.company.demo.entity.Pet">
               <loader id="petsDl">
                   <query><![CDATA[select e from demo_Pet e where e.owner = :owner]]></query>
               </loader>
           </collection>
       </data>
       <facets>
           <dataLoadCoordinator>
               <refresh loader="ownersDl"
                        onScreenEvent="Init"/> (1)
               <refresh loader="ownersDl" param="category"
                        onComponentValueChanged="categoryFilterField"/> (2)
               <refresh loader="ownersDl" param="name"
                        onComponentValueChanged="nameFilterField" likeClause="CASE_INSENSITIVE"/> (3)
               <refresh loader="petsDl" param="owner"
                        onContainerItemChanged="ownersDc"/> (4)
           </dataLoadCoordinator>
       </facets>
       <layout>
           <pickerField id="categoryFilterField" metaClass="demo_OwnerCategory"/>
           <textField id="nameFilterField"/>

   1	- ownersDl 加载器会在 InitEvent 事件触发。
   2	- ownersDl 加载器会在 categoryFilterField 组件值更改的时候触发。
   3	- ownersDl 加载器会在 nameFilterField 组件值更改的时候触发。 由于条件使用了 like 子句，值会被自动包装在 ‘(?i)% %’ 中，以便提供大小写不敏感查找。
   4	- petsDl 加载器会在 ownersDc 数据容器内容变化时触发。

3. 半自动配置，当 auto 属性设置为 true 并且也有一些手动配置的触发器，facet 会为所有没有手动配置的加载器做自动配置。

   <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd" ...>
       <data readOnly="true">
           <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
               <loader id="ownersDl">
                   <query>
                       <![CDATA[select e from demo_Owner e]]>
                   </query>
               </loader>
           </collection>
           <collection id="petsDc" class="com.company.demo.entity.Pet">
               <loader id="petsDl">
                   <query><![CDATA[select e from demo_Pet e where e.owner = :container_ownersDc]]></query> (1)
               </loader>
           </collection>
       </data>
       <facets>
           <dataLoadCoordinator auto="true">
               <refresh loader="ownersDl" onScreenEvent="Init"/> (2)
           </dataLoadCoordinator>
       </facets>

   1	- petsDl 加载器配置在 ownersDc 数据容器内容变化时自动触发。
   2	- ownersDl 为手动配置，在 InitEvent 事件触发。