3.6.2.2.2. Параметры запроса

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

JPQL-запрос в источнике данных может содержать параметры нескольких видов. Вид параметра определяется по префиксу имени параметра. Префиксом является часть имени до знака "$". Интерпретация имени после "$" рассматривается ниже.

  • Префикс ds.

    Значением параметра являются данные другого источника данных, зарегистрированного в этом же DsContext. Например:

    <collectionDatasource id="customersDs" class="com.sample.sales.entity.Customer" view="_local">
    <query>
         <![CDATA[select c from sales$Customer c]]>
    </query>
</collectionDatasource>

<collectionDatasource id="ordersDs" class="com.sample.sales.entity.Order" view="_local">
    <query>
         <![CDATA[select o from sales$Order o where o.customer.id = :ds$customersDs]]>
    </query>
</collectionDatasource>

    В данном случае параметром запроса источника данных ordersDs будет текущий экземпляр сущности, находящийся в источнике данных customersDs.

    При использовании параметров с префиксом ds между источниками данных автоматически создаются зависимости, приводящие к обновлению источника если меняется значение его параметра. В приведенном примере если изменяется выбранный Покупатель, автоматически обновляется список его Заказов.

    Обратите внимание, что в примере запроса с параметром левой частью оператора сравнения является значение идентификатора o.customer.id, а правой - экземпляр Customer, содержащийся в источнике customersDs. Такое сравнение допустимо, так как при выполнении запроса на Middleware реализация интерфейса Query, присваивая значения параметрам запроса, автоматически подставляет ID сущности вместо переданного экземпляра сущности.

    В имени параметра после префикса и имени источника может быть также указан путь по графу сущностей к атрибуту, из которого нужно взять значение, например:

    <query>
    <![CDATA[select o from sales$Order o where o.customer.id = :ds$customersDs.id]]>
</query>

    или

    <query>
    <![CDATA[select o from sales$Order o where o.tagName = :ds$customersDs.group.tagName]]>
</query>

  • Префикс custom.

    Значение параметра будет взято из объекта Map<String, Object>, переданного в метод refresh() источника данных. Например:

    <collectionDatasource id="ordersDs" class="com.sample.sales.entity.Order" view="_local">
    <query>
        <![CDATA[select o from sales$Order o where o.number = :custom$number]]>
    </query>
</collectionDatasource>
    ordersDs.refresh(ParamsMap.of("number", "1"));

    Приведение экземпляра при необходимости к его идентификатору осуществляется аналогично параметрам с префиксом ds. Путь по графу сущностей в имени параметра в данном случае не поддерживается.

  • Префикс param.

    Значение параметра будет взято из объекта Map<String, Object>, переданного при открытии экрана в метод init() контроллера. Например:

    <query>
    <![CDATA[select e from sales$Order e where e.customer = :param$customer]]>
</query>
    openWindow("sales$Order.lookup", WindowManager.OpenType.DIALOG, ParamsMap.of("customer", customersTable.getSingleSelected()));

    Приведение экземпляра при необходимости к его идентификатору осуществляется аналогично параметрам с префиксом ds. Поддерживается путь к атрибуту по графу сущностей в имени параметра.

  • Префикс component.

    Значением параметра будет текущее значение визуального компонента, путь к которому указан в имени параметра. Например:

    <query>
    <![CDATA[select o from sales$Order o where o.number = :component$filter.orderNumberField]]>
</query>

    Путь к компоненту должен включать все вложенные фреймы.

    Приведение экземпляра при необходимости к его идентификатору аналогично параметрам ds. Поддерживается путь к атрибуту по графу сущностей в имени параметра как продолжение пути к компоненту.

    При изменении значения компонента источник данных автоматически не обновляется.

  • Префикс session.

    Значением параметра будет значение атрибута пользовательской сессии, указанного в имени параметра.

    Значение извлекается методом UserSession.getAttribute(), поэтому поддерживаются также предопределенные имена атрибутов сессии:

    • userId - ID текущего зарегистрированного или замещенного пользователя;

    • userLogin - логин текущего зарегистрированного или замещенного пользователя в нижнем регистре.

      Пример:

      <query>
    <![CDATA[select o from sales$Order o where o.createdBy = :session$userLogin]]>
</query>

      Приведение экземпляра при необходимости к его идентификатору аналогично параметрам ds. Путь по графу сущностей в имени параметра в данном случае не поддерживается.

Если значение параметра не найдено по правилам, задаваемым префиксом, для данного параметра устанавливается значение null. То есть если, например, в запросе указан параметр с именем param$some_name, а в мэп параметров экрана нет ключа some_name, то для параметра param$some_name устанавливается значение null.