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 事件触发。