3.6.2.2.2. Query Parameters

This is a legacy API. For new data API available since release 7.0, see Data Components.

A JPQL query in a datasource may contain parameters of several types. A parameter type is determined by a prefix of a parameter name. A prefix is a part of the name before the $ character. The interpretation of the name after $ is described below.

  • The ds prefix

    The parameter value is data from another datasource that is registered in the same DsContext. For example:

    <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>

    In the example above, a query parameter of the ordersDs datasource will be a current entity instance located in the customersDs datasource.

    If parameters with the ds prefix are used, dependencies between datasources are created automatically. They lead to updating the datasource if its parameter are changed. In the example above, if the selected Customer is changed, the list of its Orders is changed automatically.

    Please note that in the example of the parameterized query, the left part of the comparison operator is the value of the o.customer.id identifier, and the right part – the Customer instance that is contained in the customersDs datasource. This comparison is valid since when running a query at Middleware, the implementation of the Query interface, by assigning values to query parameters, automatically adds entity ID instead of a passed entity instance.

    A path through the entity graph to an attribute (from which the value should be used) can be specified in the parameter name after the prefix and name of a datasource, for example:

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

    or

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

  • The custom prefix.

    A parameter value will be taken from the Map<String, Object> object that is passed into the refresh() method of a datasource. For example:

    <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"));

    Casting an instance to its identifier, if necessary, is performed similarly to parameters with the ds prefix. The path through the entity graph in the parameter name is not supported in this case.

  • The param prefix.

    A parameter value is taken from the Map<String, Object> object that is passed into the init() method of a controller. For example:

    <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()));

    Casting an instance to its identifier, if necessary, is performed similarly to parameters with the ds prefix. The path through the entity graph in the parameter name is supported.

  • The component prefix.

    A parameter value will be a current value of a visual component, which path is specified in the parameter name. For example:

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

    The path to a component should include all nested frames.

    Casting an instance to its identifier, if necessary, is similar to ds parameters. The path through the entity graph in the parameter name is supported as the continuation of the path to a component in this case.

    The datasource will not be refreshed automatically if the component value is changed.

  • The session prefix.

    A parameter value will be a value of the user session attribute specified in the parameter name.

    The value is extracted by the UserSession.getAttribute() method, so predefined names of session attributes are also supported.

    • userId – ID of the currently registered or substituted user;

    • userLogin – login of the currently registered or substituted user in lowercase.

    Example:

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

    Casting an instance to its identifier, if necessary, is similar to ds parameters. In this case, the path through the entity graph in the parameter name is not supported.