Defining Requests

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:

Currently, only defining requests where the resource path identifies an entity set or entity type instance are supported.
Shared request names must be unique, and must be identical on both the client and server.
If you are using a mix of delta-enabled and nondelta-enabled defining requests, and you are using referential constraints to build relationships, the dependent entity in a relationship cannot be in a delta-enabled defining request if the principal entity is in a nondelta-enabled relationship. For example, say you have two defining requests, Customers and Orders (based on the sample metadata). Since there is a referential constraint between them and no expands are specified, the offline server automatically uses the referential constraints to build relationships. In this case, it is the Customers that are the principal entities and the Orders are the dependent entity. If the Customers defining request is not delta enabled, then the Orders defining request must not delta enabled. However, if the Customers defining request is delta enabled, the Orders defining request may or may not be delta enabled.
If you are not using deltas, you can use the same entity type in more than one defining request, but you cannot perform a selective refresh of one of those defining requests without the others.
If you are using a mix of delta-enabled and nondelta-enabled requests, you cannot use the same entity type in both a delta-enabled and a nondelta-enabled defining request, either directly referenced in the resource path or through an $expand.

Using Defining Requests to Build Entity Relationships

To build relationships in your application, you can use $expand queries, referential constraints, or a combination of the two.

Referential constraints
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.
$expand queries
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.
Combining referential constraints and $expand queries
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
```

Relationship Considerations

Consider the type of application when deciding whether to use multiple separate defining requests with referential constraints or a single request with $expand.

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.

Note

This is not an exhaustive list. The choice of defining request is highly dependent on the needs of the offline application.