A defining request is a read request that targets the OData endpoint associated with the offline store and retrieves a subset of the endpoint data. Multiple defining requests can be defined for each endpoint.
Defining requests retrieve data from the OData Producer that is sent to the client, either during initialization of the offline store or during a refresh.
To set up defining requests, use the ODataOfflineStoreOptions object from the OData Offline API. The application automatically populates the “definingRequests” parameter. You can then reference each request in the application configuration file, as shown below:
[defining_request] name=DefiningRequestName is_shared_data=N|Y refresh_interval=NNN track_deltas=AUTO|ALWAYS|NEVER delta_token_lifetime=NNN
Keep the following in mind when writing defining requests:
To build relationships in your application, you can use $expand queries, referential constraints, or a combination of the two.
If you are tracking deltas using the OData Producer and require entity relationships in the offline store, you cannot use $expand queries but instead must have associations with a referential constraint. Ensure that each defining request references a single entity set. The server detects the associations with referential constraints and uses these referential constraints to build the relationships between the types selected in your defining requests.
For example, the sample metadata document has an association between CustomerType and OrderType, called CustomerType_OrderType, which defines a referential constraint. If you specify two defining requests, ~/Customers and ~/Orders, the server uses the referential constraint defined in the association CustomerType_OrderType to build the relationship between the Customers and Orders entity sets in the offline store.
Use $expand queries to build relationships between entity sets only if you are not tracking deltas, or if you are tracking deltas using the server. You cannot use $expand queries if you are tracking deltas using the OData Producer.
When you use an $expand to expand the relationship between two top-level entity sets, an association set is being implicitly referenced. For example, ~/Customer?$expand=Orders implicitly references the Customers_Orders association set. The SAP Mobile Platform server allows you to mix referential constraints and $expand to build relationships. However, you cannot mix referential constraints and $expand for the same implicitly referenced association set.
Consider the following example, which uses entity sets from the sample metadata document:
~/Customers?$expand=Orders ~/OrderItems ~/Products
The relationship between Customers and Orders is computed using the $expand, but relationships between Orders, OrderItems, and Products are computed using referential constraints.
In the example below, the relationships between Orders, OrderItems, and Products is computed using referential constraints. However, only the relationship between Orders and Customers in Canada is computed using the $expand. The relationship between Customers in the US and Orders is not computed using referential constraints because the Customers_Orders association set is implicitly expanded in the first defining request.
~/Customers?$expand=Orders&$filter=Country eq 'CAN' ~/Customers?$filter=Country eq 'US' ~/Orders ~/OrderItems ~/Products
Consider performance. For example, if the OData Producer supports deltas on single collections, but not when $expands are used, then using multiple defining requests with the referential constraints allows the use of OData Producer deltas which may out perform delta computation. Even if the OData Producer supports deltas with $expands, the computation may be expensive and it may be faster to use multiple requests with referential constraints.
Use multiple defining requests with referential constraints when using sharing. If you have a shared collection (such as Products) that is referenced from non-shared collections, then you would need to use multiple defining request with referential constraints.
If a relationship is many-to-many, you must use $expand queries because referential constraints are not supported for many-to-many relationships.
This is not an exhaustive list. The choice of defining request is highly dependent on the needs of the offline application.