3.5.4.3. DataLoadCoordinator

最低版本7.1

API 文档

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

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

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

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

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

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

参阅下面的使用示例。

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

    1. <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
    2.         xmlns:c="http://schemas.haulmont.com/cuba/screen/jpql_condition.xsd" ...>
    3.     <data readOnly="true">
    4.         <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
    5.             <loader id="ownersDl">
    6.                 <query>
    7.                     <![CDATA[select e from demo_Owner e]]> (1)
    8.                     <condition>
    9.                         <c:jpql>
    10.                             <c:where>e.category = :component_categoryFilterField</c:where> (2)
    11.                         </c:jpql>
    12.                         <c:jpql>
    13.                             <c:where>e.name like :component_nameFilterField</c:where> (3)
    14.                         </c:jpql>
    15.                     </condition>
    16.                 </query>
    17.             </loader>
    18.         </collection>
    19.         <collection id="petsDc" class="com.company.demo.entity.Pet">
    20.             <loader id="petsDl">
    21.                 <query><![CDATA[select e from demo_Pet e where e.owner = :container_ownersDc]]></query> (4)
    22.             </loader>
    23.         </collection>
    24.     </data>
    25.     <facets>
    26.         <dataLoadCoordinator auto="true"/>
    27.     </facets>
    28.     <layout>
    29.         <pickerField id="categoryFilterField" metaClass="demo_OwnerCategory"/>
    30.         <textField id="nameFilterField"/>
    1- 查询中没有参数，所以 ownersDl 加载器会在 BeforeShowEvent 触发。
    2- ownersDl 加载器也会在 categoryFilterField 组件值更改的时候触发。
    3- ownersDl 加载器也会在 nameFilterField 组件值更改的时候触发。由于条件使用了 like 子句，值会被自动包装在 ‘(?i)% %’ 中，以便提供大小写不敏感查找。
    4- petsDl 加载器会在 ownersDc 数据容器内容变化时触发。

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

    1. <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd"
    2.         xmlns:c="http://schemas.haulmont.com/cuba/screen/jpql_condition.xsd" ...>
    3.     <data readOnly="true">
    4.         <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
    5.             <loader id="ownersDl">
    6.                 <query>
    7.                     <![CDATA[select e from demo_Owner e]]>
    8.                     <condition>
    9.                         <c:jpql>
    10.                             <c:where>e.category = :category</c:where>
    11.                         </c:jpql>
    12.                         <c:jpql>
    13.                             <c:where>e.name like :name</c:where>
    14.                         </c:jpql>
    15.                     </condition>
    16.                 </query>
    17.             </loader>
    18.         </collection>
    19.         <collection id="petsDc" class="com.company.demo.entity.Pet">
    20.             <loader id="petsDl">
    21.                 <query><![CDATA[select e from demo_Pet e where e.owner = :owner]]></query>
    22.             </loader>
    23.         </collection>
    24.     </data>
    25.     <facets>
    26.         <dataLoadCoordinator>
    27.             <refresh loader="ownersDl"
    28.                      onScreenEvent="Init"/> (1)
    30.             <refresh loader="ownersDl" param="category"
    31.                      onComponentValueChanged="categoryFilterField"/> (2)
    33.             <refresh loader="ownersDl" param="name"
    34.                      onComponentValueChanged="nameFilterField" likeClause="CASE_INSENSITIVE"/> (3)
    36.             <refresh loader="petsDl" param="owner"
    37.                      onContainerItemChanged="ownersDc"/> (4)
    38.         </dataLoadCoordinator>
    39.     </facets>
    40.     <layout>
    41.         <pickerField id="categoryFilterField" metaClass="demo_OwnerCategory"/>
    42.         <textField id="nameFilterField"/>
    1- ownersDl 加载器会在 InitEvent 事件触发。
    2- ownersDl 加载器会在 categoryFilterField 组件值更改的时候触发。
    3- ownersDl 加载器会在 nameFilterField 组件值更改的时候触发。 由于条件使用了 like 子句，值会被自动包装在 ‘(?i)% %’ 中，以便提供大小写不敏感查找。
    4- petsDl 加载器会在 ownersDc 数据容器内容变化时触发。

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

    1. <window xmlns="http://schemas.haulmont.com/cuba/screen/window.xsd" ...>
    2.     <data readOnly="true">
    3.         <collection id="ownersDc" class="com.company.demo.entity.Owner" view="owner-view">
    4.             <loader id="ownersDl">
    5.                 <query>
    6.                     <![CDATA[select e from demo_Owner e]]>
    7.                 </query>
    8.             </loader>
    9.         </collection>
    10.         <collection id="petsDc" class="com.company.demo.entity.Pet">
    11.             <loader id="petsDl">
    12.                 <query><![CDATA[select e from demo_Pet e where e.owner = :container_ownersDc]]></query> (1)
    13.             </loader>
    14.         </collection>
    15.     </data>
    16.     <facets>
    17.         <dataLoadCoordinator auto="true">
    18.             <refresh loader="ownersDl" onScreenEvent="Init"/> (2)
    19.         </dataLoadCoordinator>
    20.     </facets>
    1- petsDl 加载器配置在 ownersDc 数据容器内容变化时自动触发。
    2- ownersDl 为手动配置，在 InitEvent 事件触发。