public final class

OfflineODataParameters

extends Object
java.lang.Object
   ↳ com.sap.cloud.mobile.odata.offline.OfflineODataParameters

Summary

Public Constructors
OfflineODataParameters()
Public Methods
Map<String, String> getCustomCookies()
Returns the custom cookies to be added to all HTTP communications.
Map<String, String> getCustomHeaders()
Returns the custom HTTP request headers.
String getExtraStreamParameters()
Returns the additional advanced stream parameters.
Integer getPageSize()
Returns the maximum page size to used for OfflineODataProvider driven paging.
String getStoreEncryptionKey()
Returns the key used to encrypt the local data store.
String getStoreName()
Returns an arbitrary name to identify this store.
URL getStorePath()
Returns the file system path to store the local data store.
Integer getTimeout()
Returns timeout value in seconds.
String getURLSuffix()
Returns the URL suffix path the server.
boolean isEnableIndividualErrorArchiveDeletion()
Specifies whether or not to enable deleting of individual entities from the ErrorArchive; the entity set which contains information about failed requests during the last upload.
boolean isEnableRepeatableRequests()
Returns true if the OData backend or mobile services supports repeatable requests.
boolean isEnableRequestQueueOptimization()
Returns true if request queue optimization is enabled.
boolean isEnableTransactionBuilder()
Returns true if transaction builder is enabled.
boolean isEnableUndoLocalCreation()
Returns true if an optimization that deleting an entity that was created locally but not yet uploaded undoes the creation is enabled.
void setCustomCookies(Map<String, String> customCookies)
Defines the custom cookies to be added to HTTP requests between the OfflineODataProvider and the server, and the server to the OData back end.
void setCustomHeaders(Map<String, String> customHeaders)
Defines the custom headers to be added to HTTP requests between the OfflineODataProvider and the server, and the server to the OData back end.
void setEnableIndividualErrorArchiveDeletion(boolean enableIndividualErrorArchiveDeletion)
Specifies whether or not to enable deleting of individual error archive entity from ErrorArchive entity set.
void setEnableRepeatableRequests(boolean enableRepeatableRequests)
Defines true if the OData backend or mobile services supports repeatable requests.
void setEnableRequestQueueOptimization(boolean enableRequestQueueOptimization)
Defines whether OfflineOdata supports request queue optimization before uploading to the OData backend.
void setEnableTransactionBuilder(boolean enableTransactionBuilder)
Defines whether to enable OfflineOData transaction builder to group requests into change sets before uploading to the OData back-end.
void setEnableUndoLocalCreation(boolean enableUndoLocalCreation)
Defines whether an optimization that deleting an entity that was created locally but not yet uploaded undoes the creation is enabled.
void setExtraStreamParameters(String extraStreamParameters)
Defines the additional advanced stream parameters.
void setPageSize(Integer pageSize)
Defines the maximum number of entities that can be returned in a single local read request; i.e.
void setStoreEncryptionKey(String storeEncryptionKey)
Defines the key used to encrypt the local data store.
void setStoreName(String storeName)
Defines the store name to identify the store.
void setStorePath(URL storePath)
Defines the file system path to store the local data store.
void setTimeout(Integer timeout)
Defines the timeout value in seconds.
void setURLSuffix(String urlSuffix)
Defines the suffix to add to the URL of each HTTP request sent to the server.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public OfflineODataParameters ()

Public Methods

public Map<String, String> getCustomCookies ()

Returns the custom cookies to be added to all HTTP communications.

Returns
  • the custom cookies to be added to all HTTp communications.

public Map<String, String> getCustomHeaders ()

Returns the custom HTTP request headers.

Returns
  • the custom HTTP request headers.

public String getExtraStreamParameters ()

Returns the additional advanced stream parameters.

Returns
  • the additional advanced stream parameters.

public Integer getPageSize ()

Returns the maximum page size to used for OfflineODataProvider driven paging.

Returns
  • the maximum page size to used for OfflineODataProvider driven paging.

public String getStoreEncryptionKey ()

Returns the key used to encrypt the local data store.

Returns
  • the key used to encrypt the local data store.

public String getStoreName ()

Returns an arbitrary name to identify this store.

Returns
  • an arbitrary name to identity this store.

public URL getStorePath ()

Returns the file system path to store the local data store.

Returns
  • the file system path to store the local data store.

public Integer getTimeout ()

Returns timeout value in seconds.

Returns
  • timeout value in seconds.

public String getURLSuffix ()

Returns the URL suffix path the server.

Returns
  • the URL suffix path the server.

public boolean isEnableIndividualErrorArchiveDeletion ()

Specifies whether or not to enable deleting of individual entities from the ErrorArchive; the entity set which contains information about failed requests during the last upload.

The value is 'false' by default.

By default, when one failed request is deleted from the ErrorArchive, the whole entity set is cleared along with the associated requests in the request queue. By setting this option to 'true', the app can choose exactly which failed requests to delete. Deleting an individual failed request from the ErrorArchive will cause that request and any following requests in the request queue (sent or unsent) that depend on the failed request to be deleted as well.

For example, imagine the following requests are made by the app some of which fail when they are executed on the backend:

 // Request 1: Update customer101 which will fail in the backend
 offlineODataProvider.updateEntity( customer101, HttpHeaders.empty, RequestOptions.none );
 
 // Request 2: Update customer102 which will fail in the backend
 offlineODataProvider.updateEntity( customer102, HttpHeaders.empty, RequestOptions.none );
 
 // Request 3: Update customer101 again
 offlineODataProvider.updateEntity( customer101, HttpHeaders.empty, RequestOptions.none );
 
 // Upload requests 1 - 3
 offlineODataProvider.upload( successHandler, failureHandler );
 
 // Request 4: Update customer102 again
 offlineODataProvider.updateEntity( customer102, HttpHeaders.empty, RequestOptions.none );
 

During the upload, the first two requests fail due to issues in the backend. The third request (the second customer101 update) will not be sent to the backend at all because a request it depends on (the first customer101 update) failed. At the end of the upload, the ErrorArchive will have three error requests, one for each failed request in the upload.

With enableIndividualErrorArchiveDeletion set to 'false', deleting any entity from the ErrorArchive will result in requests 1, 2, and 3 being removed but will leave request 4 in the request queue unchanged.

With enableIndividualErrorArchiveDeletion set to 'true', the app decides which failed requests to delete explicitly. If the app chooses to delete failed request 3, request 3 is the only request that will be deleted because no other requests after it in the request queue depend on it. If the app chooses to delete failed request 1, both request 1 and request 3 will be removed from the request queue because request 3 depends on request 1. If failed request 2 is deleted, both request 2 and request 4 will be deleted because even though request 4 has not yet been upload, it depends on request 2.

Returns
  • 'true' if enabled deleting individual error archive entity.

public boolean isEnableRepeatableRequests ()

Returns true if the OData backend or mobile services supports repeatable requests.

Repeatable requests (or idempotent requests) is a feature of some OData backend that ensures OData modification requests are applied exactly once even if the request is received multiple times. This is useful in cases where OData responses may be lost due to intermittent network connectivity and is required by the "OfflineODataProvider" in order to guarantee that requests are applied exactly once to the OData backend.

If repeatable requests are supported by either the OData backend or mobile services, this parameter should be set to "true", so that Offline OData will generate the repeatable request headers (RequestID and RepeatabilityCreation) for each modification request. The RequestID and RepeatabilityCreation headers are required for the server's repeatable request implementation so that it can determine whether or not the request has already been applied.

If both the OData backend and mobiles services do not support repeatable requests, set this parameter to "false" so that the repeatable request headers are not generated or sent.

By default, enableRepeatableRequests value is true.

Returns
  • true if the OData backend or mobile services supports repeatable requests.

public boolean isEnableRequestQueueOptimization ()

Returns true if request queue optimization is enabled.

Request queue optimization is an algorithm that runs prior to an upload to reduce the number of requests that get sent to the backend while still maintaining the final state of the data as if all the requests the application made were sent as is.

Consider a simple example. Say the application creates a new entity and then updates that entity before uploading. With 'enableRequestQueueOptimization' set to 'false', both the create and update requests will be sent to the backend in the next upload. However, with 'enableRequestQueueOptimization' set to 'true', the create and update requests will be combined and only a create request will be sent in the next upload.

Consider another simple example. Say the application creates a new entity and then deletes that entity before doing the next upload. With 'enableRequestQueueOptimization' set to 'false', both the create and delete requests will be sent to the backend. However, with 'enableRequestQueueOptimization' set to 'true', neither request will be sent.

**Additional Notes:**

1. 'enableRequestQueueOptimization' is 'false' by default.

2. The request queue optimization algorithm will maintain transaction (OData change set) boundaries. That is requests within a transaction can be combined, and requests between the end and start of the next transaction that reference the the same entity can be combined, but the algorithm will not remove a request from within a transaction to combine with a request outside a transaction nor move a request from outside a transaction to combine with a request inside a transaction. In this context the transaction could have been created manually by creating a local change set or built as a result of enabling transaction builder (see 'enableTransactionBuilder').

For example, consider the following sequence of requests:

  1. Create Customer 1 with Name="John"
  2. Batch #1:
    1. Change Set #1:
      1. Create Customer 2 with Name="Jan"
      2. Update Customer 2 with Name="Jane"
  3. Update Customer 1 with Name="John Doe"
  4. Update Customer 2 with Name="Jane Do"
  5. Update Customer 2 with Name="Jane Doe"

After the request queue optimization algorithm is run, the requests will be:

  1. Create Customer 1 with Name="John"
  2. Batch #1:
    1. Change Set #1:
      1. Create Customer 2 with Name="Jane"
  3. Update Customer 1 with Name="John Doe"

3. Certain requests may need to be sent as is. For example, imagine an entity which needs to move from one explicit state to another such as NEW, IN PROCESS, SOLUTION PROVIDED, CONFIRMED. For such requests, use 'OfflineODataRequestOptions' when executing the request and set 'OfflineODataRequestOptions.unmodifiableRequest' to 'true'. Such requests will be left as is (not combined with other requests) when the request queue optimization algorithm is run.

Returns
  • true if request queue optimization is enabled.

public boolean isEnableTransactionBuilder ()

Returns true if transaction builder is enabled.

Enabling transaction builder allows grouping requests into transactions (OData change sets) to be sent in the next upload that were not necessarily executed in a single change set initially. In other words, enabling this allows building large transactions for the next upload where all requests that need to go into the transactions are not known at one time.

Which requests go in which transactions is controlled by specifying 'OfflineODataRequestOptions.transactionID' when performing the requests. Requests that contain the same transaction ID will be put into the same transaction (see additional notes).

For example, consider the following sequence of requests:

  1. Create Customer 1 with a transaction ID "1"
  2. Create Order 1 with a transaction ID "1"
  3. Create Product 1 with NO transaction ID
  4. Create Customer 2 with a transaction ID "2"
  5. Update Customer 1 with a transaction ID "1"
  6. Update Customer 2 with a transaction ID "2"

Just prior to executing the upload, the transaction builder algorithm will run and these requests will result in the following requests being sent to the backend (in this example assume 'enableRequestQueueOptimization' is 'false'):

  1. Batch #1
    1. Change Set #1
      1. Create Customer 1
      2. Create Order 1
      3. Update Customer 1
  2. Create Product 1
  3. Batch #2
    1. Change Set #1
      1. Create Customer 2
      2. Update Customer 2

**Additional Notes:**

1. 'enableTransactionBuilder' is 'false' by default.

2. 'enableTransactionBuilder' can be used in combination with 'enableRequestQueueOptimization'.

3. To ensure referential integrity of related entities and to ensure all requests are valid OData requests, it is not always possible to group all requests with the same transaction ID into a single change set. Therefore, the transaction builder will group requests with the same transaction ID into as few change sets as possible.

4. In addition to referential integrity, 'OfflineODataRequestOptions.unmodifiableRequest' can affect the transaction builder. Only one unmodifiable request per entity will be put into a single change set.

Returns
  • true if transaction builder is enabled.

public boolean isEnableUndoLocalCreation ()

Returns true if an optimization that deleting an entity that was created locally but not yet uploaded undoes the creation is enabled. More specifically, if enabled, the optimization will remove requests from the request queue so the the backend never sees them.

**Additional Notes:**

1. 'enableUndoLocalCreation' is 'false' by default.

2. 'enableUndoLocalCreation' is different than 'enableRequestQueueOptimization'. The algorithm that 'enableRequestQueueOptimization' controls respects transaction boundaries and unmodifiable requests (see 'OfflineODataRequestOptions.unmodifiableRequest'). If 'enableUndoLocalCreation' is set to 'true', it does not matter whether the creates, updates and deletes are in different transactions or are unmodifiable, they will all be removed.

3. The algorithm will respect cascading deletes. That is, if a parent in a parent-child relationship is deleted, and this optimization is enabled, the algorithm will also ensure that requests for children that were also created and not yet uploaded will also be removed from the request queue. However, if deleting a locally created but not yet uploaded entity will cause an entity downloaded from the backend to be deleted (for example, if a cascading delete of the local entity causes a server entity to be deleted), the requests referencing the locally deleted entity will be sent to the backend to ensure the correct entities are deleted from the backend. If the application needs to guarantee requests creating and modifying a locally created entity are not sent to the backend, the application should use 'OfflineODataProvider.undoPendingChanges()'.

Consider the following examples:

1. Say you have created a new entity customer101 locally, updated it once and then deleted it. After performing these operations, you invoke upload(). Below is the operation sequence:

  • Request #1: Create customer101 locally
  • Request #2: Update customer101
  • Request #3: Delete customer101
  • Invoke upload()

Note that before invoking upload(), customer101 is not available (since it has been deleted) but request #1 to #3 are kept in the request queue.

If 'enableUndoLocalCreation' is 'false' (the default value), when calling upload(), request #1 to #3 will be sent to the backend. The entity customer101 will be created, updated then deleted in the backend.

If 'enableUndoLocalCreation' is 'true', when calling upload, the optimization will happen by removing request #1 to #3, therefore they would not be sent to the backend.

2. Say you have created a new entity customer101 locally, and then also create a related order101 where the relationship between customers and orders is "on delete cascade". Then customer101 is deleted before any operations are uploaded. Then upload() is invoked. Below is the operation sequence:

  • Request #1: Create customer101 locally
  • Request #2: Create order101 related to customer101 locally
  • Request #3: Delete customer101
  • Invoke upload()

If 'enableUndoLocalCreation' is 'false' (the default value), when calling upload(), request #1 to #3 will be sent to the backend.

If 'enableUndoLocalCreation' is 'true', when calling upload, the optimization will happen by removing request #1 to #3, therefore they would not be sent to the backend.

Returns
  • true if the optimization is enabled.

public void setCustomCookies (Map<String, String> customCookies)

Defines the custom cookies to be added to HTTP requests between the OfflineODataProvider and the server, and the server to the OData back end.

The keys are cookie names. The values are cookie values.

Parameters
customCookies the custom cookies. If null, an empty customer cookies map is used..

public void setCustomHeaders (Map<String, String> customHeaders)

Defines the custom headers to be added to HTTP requests between the OfflineODataProvider and the server, and the server to the OData back end.

The keys are the header name. The values are header value.

Parameters
customHeaders the custom HTTP headers. If null, an empty customer headers map is used.

public void setEnableIndividualErrorArchiveDeletion (boolean enableIndividualErrorArchiveDeletion)

Specifies whether or not to enable deleting of individual error archive entity from ErrorArchive entity set.

By default, enableIndividualErrorArchiveDeletion is 'false'.

public void setEnableRepeatableRequests (boolean enableRepeatableRequests)

Defines true if the OData backend or mobile services supports repeatable requests.

By default, enableRepeatableRequests value is true.

Parameters
enableRepeatableRequests true if the OData back end-supports repeatable requests.

public void setEnableRequestQueueOptimization (boolean enableRequestQueueOptimization)

Defines whether OfflineOdata supports request queue optimization before uploading to the OData backend.

By default, enableRequestQueueOptimization is false.

Parameters
enableRequestQueueOptimization true to enable request queue optimization.

public void setEnableTransactionBuilder (boolean enableTransactionBuilder)

Defines whether to enable OfflineOData transaction builder to group requests into change sets before uploading to the OData back-end.

By default, enableTransactionBuilder is false.

Parameters
enableTransactionBuilder true to enable transaction build.

public void setEnableUndoLocalCreation (boolean enableUndoLocalCreation)

Defines whether an optimization that deleting an entity that was created locally but not yet uploaded undoes the creation is enabled.

By default, enableUndoLocalCreation is false.

Parameters
enableUndoLocalCreation true to enable undoing local creation.

public void setExtraStreamParameters (String extraStreamParameters)

Defines the additional advanced stream parameters.

This is an optional property.

Parameters
extraStreamParameters the parameters.

public void setPageSize (Integer pageSize)

Defines the maximum number of entities that can be returned in a single local read request; i.e. the maximum page size to use for OfflineODataProvider driven paging.

Reading an entity set will return at most this many entities in its response pay load. If the response is a partial set of entities then a "next link" to the next page of the response will be provided.

This is an optional property, if omitted, it will be no OfflineODataProvider driven paging.

The value must be positive integer.

Parameters
pageSize the page size.

public void setStoreEncryptionKey (String storeEncryptionKey)

Defines the key used to encrypt the local data store.

This is an optional property.

WARNING: If this property is omitted the store will be created without encrypting the data on the device.

Parameters
storeEncryptionKey the key to encrypt the local data store.

public void setStoreName (String storeName)

Defines the store name to identify the store.

This is an optional property. If omitted, a default name "localstore" will be used.

Parameters
storeName the name to identify the store.

public void setStorePath (URL storePath)

Defines the file system path to store the local data store.

This is an optional property. If omitted, the default location is where the application is installed.

Sample of storePath - "file:/storage/sdcard1/....", "file:///data/data/abc/d/...." or java.io.File instance method toURI().toURL()

Parameters
storePath the file system path to store the local data store.

public void setTimeout (Integer timeout)

Defines the timeout value in seconds.

WARNING: if the timeout set too low ( less than 30 seconds ), it would increase network traffic for checking the liveness of the connection which each timeout period to ensure that the connection is still active.

This is an optional property, if omitted, it will be no timeout.

Parameters
timeout the timeout value in seconds.

public void setURLSuffix (String urlSuffix)

Defines the suffix to add to the URL of each HTTP request sent to the server. When connecting through a proxy or web server, the URL suffix may be necessary to find the server.

This is an optional property.

Parameters
urlSuffix the URL suffix.