Named Queries

Named queries are a concept where the actual query criteria is constructed within the Business Entity or the Data Access class. The consumer simply passes in a query name and a list of arguments (similar to Dictionary of <PrimitiveHolder> classes).The Business Entity or the Data Access class will convert this into the actual query parameters. This moves the responsibility of handling the complexity when building complex query strings into the Business Entity or alternatively into the Data Access class - allowing the back end developer to also decide on optimal use of indexes etc.

Named queries are supported using an additional property of the FetchDataRequest parmeter: NamedQuery

Named queries are identified by an INamedQueryParameter instance with the following properties:

Property NameDescription
NameA character value used to identify the query within the Business Entity.
ParametersA list (with dictionary like ContainsKey and GetItem methods) of parameters with a name and values (a list of <Primitive Type>Holder classes)


Within the BusinessEntity's FetchData method a developer should test if a NamedQuery is requested and build the actual query string and assign other FetchDataRequest properties (like Tables) accordingly.

Sample implementation in a Business Entity

In this sample the Business Entity is prepared to handle a named query with the name "SearchInAddress". The consumer passes this named query with a character value of "Grand" and under the "Query" parameter (a randomly selected parameter name).


Sample consumer code
{ Consultingwerk/SmartComponentsDemo/OERA/Sports2000/dsCustomer.i }
DEFINE VARIABLE oRequest AS FetchDataRequest NO-UNDO .

/* *************************** Main Block *************************** */

oRequest = NEW FetchDataRequest () . 

oRequest:NamedQuery = NEW NamedQueryParameter("SearchInAddress") .
oRequest:NamedQuery:Parameters:Add ("Query", "Grand") .

FrameworkSettings:ServiceAdapter:RetrieveData ("", 
                                               OUTPUT DATASET dsCustomer) .

 In the Business Entity the following override to FetchData builds the actual query:

Sample Business Entity implementation
METHOD OVERRIDE PUBLIC VOID FetchData (poFetchDataRequest AS Consultingwerk.OERA.IFetchDataRequest):

    IF VALID-OBJECT (poFetchDataRequest:NamedQuery) THEN DO:

        CASE poFetchDataRequest:NamedQuery:Name:
           WHEN "SearchInAddress":U THEN DO:

               /* Verify required parameter */
               IF NOT poFetchDataRequest:NamedQuery:Parameters:ContainsKey ("Query":U) THEN 
                   UNDO, THROW NEW NamedQueryParameterMissingException (poFetchDataRequest:NamedQuery:Name,
                                                                        "Query":U) .

               ASSIGN poFetchDataRequest:Tables = "eCustomer":U
                      poFetchDataRequest:Queries = SUBSTITUTE ("for each eCustomer where eCustomer.Name begins &1 ~
                                                                                      or eCustomer.City begins &1 ~
                                                                                      or eCustomer.Address begins &1 ~
                                                                                      or eCustomer.Address2 begins &1", 
                                                               QUOTER (CAST (poFetchDataRequest:NamedQuery:Parameters:GetItem("Query":U), CharacterHolder):Value)) .
               /* Handle unknown query name */
               UNDO, THROW NEW InvalidNamedQueryException (poFetchDataRequest:NamedQuery:Name) .

        END CASE . 

    SUPER:FetchData (poFetchDataRequest).

Note, that the InvalidNamedQueryException and NamedQueryParameterMissingException error classes are build for custom code like this.

DatasetModel Classes

Dataset Model classes do also allow to execute named queries. Two additional RetrieveData methods have been implemented:

    Purpose: Retrieves data from the backend
    @param poNamedQuery The INamedQueryParameter that defines a named query
METHOD PUBLIC VOID RetrieveData (poNamedQuery AS INamedQueryParameter)
    Purpose: Retrieves data from the backend
    @param pcTables The comma delimited list of the Table Names to retrieve
    @param poNamedQuery The INamedQueryParameter that defines a named query
                                 poNamedQuery AS INamedQueryParameter)


The SmartBusinessEntityAdapter supports the execution of named queries by providing the NamedQuery property which can be set before the RetrieveData method is invoked.