public final class

OfflineODataProvider

extends Object
implements DataServiceProvider AutoCloseable
java.lang.Object
   ↳ com.sap.cloud.mobile.odata.offline.OfflineODataProvider

Class Overview

The class represents a DataServiceProvider for Offline OData.

It implements java.lang.AutoCloseable and com.sap.cloud.mobile.odata.DataServiceProvider interfaces

See Also

Summary

Constants
String LOGGER_NAME OfflineODataProvider logger name.
Public Constructors
OfflineODataProvider(URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, SslClientAuth sslClientAuth, OfflineODataDelegate delegate)
Constructs an OfflineODataProvider instance.
OfflineODataProvider(URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient)
Constructs an OfflineODataProvider instance.
OfflineODataProvider(URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, OfflineODataDelegate delegate)
Constructs an OfflineODataProvider instance.
OfflineODataProvider(URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, SslClientAuth sslClientAuth)
Constructs an OfflineODataProvider instance.
Public Methods
void addDefiningQuery(OfflineODataDefiningQuery definingQuery)
Adds a defining query to the provider.
void cancelDownload()
Cancels all refreshes and file downloads including those that are queued.
void cancelUpload()
Cancels the current upload.
static void clear(URL path, String name)
Deletes the physical store from the file system.
void clear()
Deletes the physical store from the file system.
static void clear(String name)
Deletes the physical store from the file system.
void close()
Closes the OfflineODataProvider, freeing any resources.
void createEntity(EntityValue entity, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createEntity(EntityValue, HttpHeaders, RequestOptions)
void createLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)
void createMedia(EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createMedia(EntityValue, StreamBase, HttpHeaders, RequestOptions)

Note: key of the entity will be removed if it has been set.

void deleteByQuery(DataQuery query, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteByQuery(DataQuery, HttpHeaders, RequestOptions)
void deleteEntity(EntityValue entity, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteEntity(EntityValue, HttpHeaders, RequestOptions)
void deleteLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)
void deleteStream(EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options)
OfflineODataProvider doesn't support Edm.Stream type yet, the method operates same as delete entity, the value of the link parameter must be entity.getMediaStream().
void download(List<OfflineODataDefiningQuery> subset, Action0 successHandler, Action1<OfflineODataException> failureHandler)
Downloads the data for the defining queries from the OData back end to update the local data.
void download(Action0 successHandler, Action1<OfflineODataException> failureHandler)
Downloads the data for all defining queries from the OData back end to update the local data.
ByteStream downloadMedia(EntityValue entity, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#downloadMedia(EntityValue, HttpHeaders, RequestOptions)
ByteStream downloadStream(EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options)
OfflineODataProvider doesn't support Edm.Stream yet, the method operates same as downloadMedia of entity, the link parameter is the value of entity.getMediaStream().
DataValue executeMethod(DataMethod method, ParameterList parameters, HttpHeaders headers, RequestOptions options)
Execute FunctionImport

Offline OData supports POST, PUT, PATCH/MERGE, and DELETE function import requests.

QueryResult executeQuery(DataQuery query, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#executeQuery(DataQuery, HttpHeaders, RequestOptions)
CsdlDocument fetchMetadata(HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#fetchMetadata()
void forceReauthentication()
Causes the offline store to remove any stored authentication it may have, causing it to reauthenticate the next time it needs to send a request to SMP/CPms server.
List<OfflineODataErrorArchiveEntity> getErrorArchive()
Query the entity set of OfflineOData store ErrorArchive.
List<OfflineODataErrorArchiveEntity> getErrorArchive(DataQuery query)
Query the entity set of OfflineOData store ErrorArchive with query options.
List<OfflineODataEvent> getEventLog()
Query the entity set of OfflineOData event Log.
List<OfflineODataEvent> getEventLog(DataQuery query)
Query the entity set of OfflineOData event Log with query options.
CsdlDocument getMetadata()
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#getMetadata()
String getServiceName()
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#getServiceName()
OfflineODataServiceOptions getServiceOptions()
Returns OfflineODataProvider service options.
boolean hasMetadata()
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#hasMetadata()
boolean hasPendingDownload()
Checks whether or not there is a pending download ( a download that was cancelled either explicitly or because the provider was closed ).
boolean hasPendingUpload()
Checks whether or not there is a pending upload ( a upload that was cancelled either explicitly or because the provider was closed).
boolean isRequestQueueEmpty()
Checks whether or not there are any pending requests stored in the request queue that have not yet been uploaded.
static String libraryVersion()
Returns version information about this library.
void loadMetadata(HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#loadMetadata( HttpHeaders, RequestOptions )
void logDefiningQueries(Level logLevel)
Dumps defining queries (as a JSON object) that have been added to the offline store to log.
void logRequestQueue(Level logLevel)
Dumps content (as a JSON object) of request queue of the offline store to log.
void open(Action0 successHandler, Action1<OfflineODataException> failureHandler)
Opens the provider.
void pingServer(HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#pingServer( HttpHeaders, RequestOptions )
void processBatch(RequestBatch batch, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#processBatch( RequestBatch, HttpHeaders, RequestOptions )
void removeDefiningQuery(OfflineODataDefiningQuery definingQuery)
Removes a defining query.
void sendStore(Action0 successHandler, Action1<OfflineODataException> failureHandler)
Sends the Offline OData store to sever.
void setMetadata(CsdlDocument value)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#setMetadata(CsdlDocument)
void setServiceOptions(OfflineODataServiceOptions serviceOptions)
Defines OfflineODataProvider service options.
void undoPendingChanges(EntityValue entity)
Undo pending local changes for a given entity.
void unloadMetadata()
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#unloadMetadata
void updateEntity(EntityValue entity, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#updateEntity(EntityValue, HttpHeaders, RequestOptions)
void updateLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#updateLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)
void upload(Action0 successHandler, Action1<OfflineODataException> failureHandler)
Uploads local data to update the OData back end.
void upload(UploadCategory[] categories, Action0 successHandler, Action1<OfflineODataException> failureHandler)
Partial upload allows Offline OData applications to upload a subset of the requests in the request queue.
void uploadMedia(EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions options)
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#uploadMedia(EntityValue, StreamBase, HttpHeaders, RequestOptions)
void uploadStream(EntityValue entity, StreamLink link, StreamBase content, HttpHeaders headers, RequestOptions options)
OfflineODataProvider doesn't support Edm.Sream type yet, the method operates same as uploadStream of entity, the link parameter is the value of entity.getMediaStream().
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.sap.cloud.mobile.odata.DataServiceProvider
From interface java.lang.AutoCloseable

Constants

public static final String LOGGER_NAME

OfflineODataProvider logger name.

Constant Value: "com.sap.cloud.mobile.odata.offline"

Public Constructors

public OfflineODataProvider (URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, SslClientAuth sslClientAuth, OfflineODataDelegate delegate)

Constructs an OfflineODataProvider instance.

OfflineODataProvider depends on Android Context from AndroidSystem.

Example Usage:

The sample shows how to use OfflineODataProvider constructor and open method.

And it turns an asynchronous open call to be synchronous and makes CRUD operations after a successful open.

 // Retrieve the OkHttpClient initialized in Foundation module
 OkHttpClient okHttpClient = ClientProvider.get();

 // Initialize application context for use by OfflineODataProvider
 AndroidSystem.setContext(applicationContext);

 // Specify parameters for OfflineODataProvider construction
 OfflineODataParameters parameters = new OfflineODataParameters();
 parameters.setStoreEncryptionKey("secret-key");

 // Create a new instance of offlineODataProvider use try-with-resources statement, to ensure OfflineODataProvider instance
 // to be closed after usage.
 try (OfflineODataProvider offlineODataProvider = new OfflineODataProvider(new URL(SERVICE_URL), parameters, okHttpClient)) {
     // Construct a DataService instance
     DataService dataService = new DataService(offlineODataProvider);

     // Add defining queries
     offlineODataProvider.addDefiningQuery(new OfflineODataDefiningQuery("Customers", "Customers", false));
     offlineODataProvider.addDefiningQuery(new OfflineODataDefiningQuery("Orders", "Orders", false));
     offlineODataProvider.addDefiningQuery(new OfflineODataDefiningQuery("OrderItems", "OrderItems", false));

     final CountDownLatch completed = new CountDownLatch( 1 );
     final AtomicReference<Exception> ex = new AtomicReference<>();

     // Open the provider
     offlineODataProvider.open(() -> completed.countDown(),
                               (error) -> { logger.error("Exception encountered in OfflineOData open: ", error);
                                            ex.set(error);
                                            completed.countDown(); } );
     completed.await();
     if ( ex.get() != null ) {
         // Handle the open error.
     } else {
         // Continue operating on offlineODataProvider after open.
         // Once the provider is opened, various operations can be performed, such as executing CRUD actions, uploading
         // and downloading updates from backend service.


     }
 }
 

Parameters
serviceRoot the service root of the OData back end. This value depends on the "Rewrite Mode" configuration of the application on SAP Cloud Platform mobile service for development and operation. If "Rewrite Mode" is set to "Rewrite URL" then the path of the service root is the Application Connection Name. If "Rewrite Mode" is set to "Rewrite URL on the Back End" then the path or the service root should be the same as the path of the back end URL specified on the SAP Cloud Platform mobile service for development and operations.

For example, if the SAP Cloud Platform mobile service for development and operations being used is at https://sapcpms/, the application is configured with an Application Connection Name of "myconn" on an OData back end with service root "http://myhost:80/odata/endpoint", then the serviceRoot should be "https://sapcpms/myconn/" for "Rewrite URL" and "https://sapcpms/odata/endpoint" for "Rewrite URL on Back End".

parameters the configuration parameters for the OfflineODataProvider.
okHttpClient the HTTP client is used by OfflineODataProvider to handle network authentication.
sslClientAuth an optional parameter, it provides client authenticate certificate to OfflineODataProvider.
delegate an optional parameter, the methods of the delegate are called at various stages during execution of open, download and upload.
Throws
OfflineODataException if an error occurs initializing the OfflineODataProvider.
See Also

public OfflineODataProvider (URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient)

Constructs an OfflineODataProvider instance.

OfflineODataProvider depends on Android Context from AndroidSystem.

Parameters
serviceRoot the service root of the OData back end. This value depends on the "Rewrite Mode" configuration of the application on SAP Cloud Platform mobile service for development and operation. If "Rewrite Mode" is set to "Rewrite URL" then the path of the service root is the Application Connection Name. If "Rewrite Mode" is set to "Rewrite URL on the Back End" then the path or the service root should be the same as the path of the back end URL specified on the SAP Cloud Platform mobile service for development and operations.

For example, if the SAP Cloud Platform mobile service for development and operations being used is at https://sapcpms/, the application is configured with an Application Connection Name of "myconn" on an OData back end with service root "http://myhost:80/odata/endpoint", then the serviceRoot should be "https://sapcpms/myconn/" for "Rewrite URL" and "https://sapcpms/odata/endpoint" for "Rewrite URL on Back End".

parameters the configuration parameters for the OfflineODataProvider.
okHttpClient the HTTP client is used by OfflineODataProvider to handle network authentication.
Throws
OfflineODataException if an error occurs initializing the OfflineODataProvider.

public OfflineODataProvider (URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, OfflineODataDelegate delegate)

Constructs an OfflineODataProvider instance.

OfflineODataProvider depends on Android Context from AndroidSystem.

Parameters
serviceRoot the service root of the OData back end. This value depends on the "Rewrite Mode" configuration of the application on SAP Cloud Platform mobile service for development and operation. If "Rewrite Mode" is set to "Rewrite URL" then the path of the service root is the Application Connection Name. If "Rewrite Mode" is set to "Rewrite URL on the Back End" then the path or the service root should be the same as the path of the back end URL specified on the SAP Cloud Platform mobile service for development and operations.

For example, if the SAP Cloud Platform mobile service for development and operations being used is at https://sapcpms/, the application is configured with an Application Connection Name of "myconn" on an OData back end with service root "http://myhost:80/odata/endpoint", then the serviceRoot should be "https://sapcpms/myconn/" for "Rewrite URL" and "https://sapcpms/odata/endpoint" for "Rewrite URL on Back End".

parameters the configuration parameters for the OfflineODataProvider.
okHttpClient the HTTP client is used by OfflineODataProvider to handle network authentication.
delegate an optional parameter, the methods of the delegate are called at various stages during execution of open, download and upload.
Throws
OfflineODataException if an error occurs initializing the OfflineODataProvider.

public OfflineODataProvider (URL serviceRoot, OfflineODataParameters parameters, OkHttpClient okHttpClient, SslClientAuth sslClientAuth)

Constructs an OfflineODataProvider instance.

OfflineODataProvider depends on Android Context from AndroidSystem.

Parameters
serviceRoot the service root of the OData back end. This value depends on the "Rewrite Mode" configuration of the application on SAP Cloud Platform mobile service for development and operation. If "Rewrite Mode" is set to "Rewrite URL" then the path of the service root is the Application Connection Name. If "Rewrite Mode" is set to "Rewrite URL on the Back End" then the path or the service root should be the same as the path of the back end URL specified on the SAP Cloud Platform mobile service for development and operations.

For example, if the SAP Cloud Platform mobile service for development and operations being used is at https://sapcpms/, the application is configured with an Application Connection Name of "myconn" on an OData back end with service root "http://myhost:80/odata/endpoint", then the serviceRoot should be "https://sapcpms/myconn/" for "Rewrite URL" and "https://sapcpms/odata/endpoint" for "Rewrite URL on Back End".

parameters the configuration parameters for the OfflineODataProvider.
okHttpClient the HTTP client is used by OfflineODataProvider to handle network authentication.
sslClientAuth an optional parameter, it provides client authenticate certificate to OfflineODataProvider.
Throws
OfflineODataException if an error occurs initializing the OfflineODataProvider.

Public Methods

public void addDefiningQuery (OfflineODataDefiningQuery definingQuery)

Adds a defining query to the provider. There are three types of defining queries:

  • type 1 - A defining query that identifies one or more entities where the automaticallyRetrievesStreams property is set to false. In this case, even if the defining query identifies media entities, the media streams will not be downloaded.
  • type 2 - A defining query that identifies one or more entities, some of which may be media entities, and where the automaticallyRetrievesStreams property is set to true. In this case, the media streams will be downloaded as well for media entities.
  • type 3 - A defining query that identifies a single media entity and the automaticallyRetrievesStreams property is set to true. The URL specified in this case MUST be the read link of the media entity, not the read link of the media stream. For example, if the media entity's read link is Documents(101) and the media stream's read link is Documents(101)/$value, the expected URL of the defining query is Documents(101).

Defining queries can be added before or after the OfflineODataProvider has been opened.

The defining queries added when OfflineODataProvider is not opened, are not persisted. They will be lost after the device is power off or application is terminated.

For performance reasons, it is not recommended (although it is supported) to use $expand in defining queries, unless your OData back end supports deltas with $expand in defining queries.

The Offline OData server component can take advantage of referential constraints to build relationship information instead of relying on $expand. For example, if the relationship (Association) between Customers and Orders has a referential constraint in the meta data document, the defining query https://sapcpms/odata/endpoint/Customers?$expand=Orders is equivalent to the pair of defining queries https://sapcpms/odata/endpoint/Customers and https://sapcpms/odata/endpoint/Orders; in both cases, all Customers, Orders, and relationship information for Customers and Orders are downloaded.

Parameters
definingQuery the defining query to add.
Throws
OfflineODataException if an error occurs adding the defining query.

public void cancelDownload ()

Cancels all refreshes and file downloads including those that are queued. This method will also cancel an initial download and file transfer if it is called while the store is opening.

Throws
OfflineODataException if there are no downloads or file downloads to cancel.

public void cancelUpload ()

Cancels the current upload.

Throws
OfflineODataException if there are no uploads to cancel.

public static void clear (URL path, String name)

Deletes the physical store from the file system. All instances of the OfflineODataProvider must be closed before it can be deleted.

This method depends on Android Context from AndroidSystem.

Parameters
path the path of the local data store ( file:/storage/sdcard/... ). If null, the default location is where the application is installed.
name the name of the store. If null, the default store name is used.
Throws
OfflineODataException if an error occurs removing the store.
See Also
  • com.sap.cloud.mobile.odata.core.AndroidSystem

public void clear ()

Deletes the physical store from the file system.

This method will close the OfflineODataProvider before attempting to delete the physical store.

Note that, this will also clear any information about the defining queries. Therefore, before opening again, any defining queries required for the initial download will need to be respecified.

Throws
OfflineODataException if an error occurs removing the store.

public static void clear (String name)

Deletes the physical store from the file system. All instances of the OfflineODataProvider must be closed before it can be deleted.

This method depends on Android Context from AndroidSystem.

Parameters
name the name of the store. If null, the default store name is used.
Throws
OfflineODataException if an error occurs removing the store.
See Also
  • com.sap.cloud.mobile.odata.core.AndroidSystem

public void close ()

Closes the OfflineODataProvider, freeing any resources. If a download or upload is active, it will be cancelled (it may be resumable after the provider is re-opened).

The provider needs to be closed if it is no longer needed.

Throws
OfflineODataException if an error occurs closing the OfflineODataProvider.

public void createEntity (EntityValue entity, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createEntity(EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void createLink (EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void createMedia (EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#createMedia(EntityValue, StreamBase, HttpHeaders, RequestOptions)

Note: key of the entity will be removed if it has been set. No key should be set when creating a media entity.

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void deleteByQuery (DataQuery query, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteByQuery(DataQuery, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void deleteEntity (EntityValue entity, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteEntity(EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void deleteLink (EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void deleteStream (EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options)

OfflineODataProvider doesn't support Edm.Stream type yet, the method operates same as delete entity, the value of the link parameter must be entity.getMediaStream().

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#deleteStream(EntityValue, StreamLink, HttpHeaders, RequestOptions)

Parameters
link this value must be entity.getMediaStream.
Throws
DataServiceException runtime exception when an error occurs.
See Also

public void download (List<OfflineODataDefiningQuery> subset, Action0 successHandler, Action1<OfflineODataException> failureHandler)

Downloads the data for the defining queries from the OData back end to update the local data. If the defining queries are delta enabled, only the changes will be downloaded.

Example Usage:

 // Create subset of defining queries to download
 List< OfflineODataDefiningQuery > subset = new ArrayList<>();
 subset.add(new OfflineODataDefiningQuery("Customers", "Customers", false));

 // Download data asynchronously
 offlineODataProvider.upload(subset,
                             () -> logger.info("Download completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData download: ", error));

 
 

Parameters
subset the subset of the defining queries to download.
successHandler a success callback function.
failureHandler a failure callback function.
See Also

public void download (Action0 successHandler, Action1<OfflineODataException> failureHandler)

Downloads the data for all defining queries from the OData back end to update the local data. If the defining queries are delta enabled, only the changes will be downloaded.

Example Usage:

 // Download data asynchronously
 offlineODataProvider.upload(() -> logger.info("Download completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData download: ", error));

 
 

Parameters
successHandler a success callback function.
failureHandler a failure callback function.
See Also

public ByteStream downloadMedia (EntityValue entity, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#downloadMedia(EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public ByteStream downloadStream (EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options)

OfflineODataProvider doesn't support Edm.Stream yet, the method operates same as downloadMedia of entity, the link parameter is the value of entity.getMediaStream().

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#downloadStream(EntityValue, StreamLink, HttpHeaders, RequestOptions)

Parameters
link this value must be entity.getMediaStream.
Throws
DataServiceException runtime exception when an error occurs.
See Also

public DataValue executeMethod (DataMethod method, ParameterList parameters, HttpHeaders headers, RequestOptions options)

Execute FunctionImport

Offline OData supports POST, PUT, PATCH/MERGE, and DELETE function import requests. It does not support GET function import requests because GET requests are executed locally and there is no way to predict or simulate what the GET response will be when executed on the backend. Similarly, Function Import modification requests (POST, PUT, PATCH, DELETE) made locally have no impact on the local data, again, because the effect cannot be predicted in the way that the effect for standard CRUD operations can.

Code Example:

 method = dataService.getDataMethod("POST_T1_01");
method.setHttpMethod(POST);
ParameterList parameters = new ParameterList();
Parameter par = new Parameter();
par.setName("a");
IntValue intValue = IntValue.of(77);
par.setValue(intValue);
par.setType(intValue.getDataType());
parameters.add(par);
this.getDataService().executeMethod(method, parameters);

Service.upload(this);
Service.download(this);

DataQuery queryT1 = new DataQuery();
queryT1.setRequestPath("T1");
queryT1.setQueryString("?$filter=pk eq " + 77);
Service.queryAndPrint(testnum(2), queryT1, Printer.QueryResultType.EntityList);


 
Please reference com.sap.cloud.mobile.odata.DataServiceProvider#executeMethod(DataMethod, ParameterList, HttpHeaders, RequestOptions)

Parameters
method DataMethod instance includes Function Import name and HttpMethod.
parameters contains parameter list to call Function Import.
headers HttpHeaders.
options RequestOptions
Throws
DataServiceException runtime exception when an error occurs.
See Also
  • com.sap.cloud.mobile.odata.DataServiceException

public QueryResult executeQuery (DataQuery query, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#executeQuery(DataQuery, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public CsdlDocument fetchMetadata (HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#fetchMetadata()

Throws
DataServiceException runtime exception when an error occurs.

public void forceReauthentication ()

Causes the offline store to remove any stored authentication it may have, causing it to reauthenticate the next time it needs to send a request to SMP/CPms server.

Example Usage:

 offlineODataProvider.forceReauthentication()

 
 

public List<OfflineODataErrorArchiveEntity> getErrorArchive ()

Query the entity set of OfflineOData store ErrorArchive.

Returns
  • List of OfflineODataErrorArchiveEntity
Throws
OfflineODataException if the store is not open.

public List<OfflineODataErrorArchiveEntity> getErrorArchive (DataQuery query)

Query the entity set of OfflineOData store ErrorArchive with query options.

Parameters
query Query options on error archive entity set.
Returns
  • List of OfflineODataErrorArchiveEntity instances.
Throws
OfflineODataException when the passed query object is not based on error archive entity set or store is not open.

public List<OfflineODataEvent> getEventLog ()

Query the entity set of OfflineOData event Log.

Returns
  • List of OfflineODataEvent instances.
Throws
OfflineODataException if the store is not open.

public List<OfflineODataEvent> getEventLog (DataQuery query)

Query the entity set of OfflineOData event Log with query options.

Parameters
query Query options on event log entity set.
Returns
  • List of OfflineODataEvent instances.
Throws
OfflineODataException when the passed query object is not based on event log entity set or store is not open.

public CsdlDocument getMetadata ()

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#getMetadata()

Throws
DataServiceException runtime exception when an error occurs.

public String getServiceName ()

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#getServiceName()

public OfflineODataServiceOptions getServiceOptions ()

Returns OfflineODataProvider service options.

Returns
  • OfflineODataProvider service options.

public boolean hasMetadata ()

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#hasMetadata()

public boolean hasPendingDownload ()

Checks whether or not there is a pending download ( a download that was cancelled either explicitly or because the provider was closed ). It may be possible to continue the download by triggering a new download.

Returns
  • true if there is a pending download, and false otherwise.
Throws
OfflineODataException if an error occurs determining whether there is a pending download.

public boolean hasPendingUpload ()

Checks whether or not there is a pending upload ( a upload that was cancelled either explicitly or because the provider was closed). It may be possible to continue the upload by triggering a new upload.

Returns
  • true if there is a pending upload, and false otherwise.
Throws
OfflineODataException if an error occurs determining whether there is a pending upload.

public boolean isRequestQueueEmpty ()

Checks whether or not there are any pending requests stored in the request queue that have not yet been uploaded.

Returns
  • true if the request queue is empty, false otherwise.
Throws
OfflineODataException if an error occurs determining whether the request queue is empty.

public static String libraryVersion ()

Returns version information about this library.

Returns
  • a string containing version information about this library

public void loadMetadata (HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#loadMetadata( HttpHeaders, RequestOptions )

Throws
DataServiceException runtime exception when an error occurs.
See Also
  • com.sap.cloud.mobile.odata.DataServiceException

public void logDefiningQueries (Level logLevel)

Dumps defining queries (as a JSON object) that have been added to the offline store to log.

Parameters
logLevel The log level to be used for logging.

public void logRequestQueue (Level logLevel)

Dumps content (as a JSON object) of request queue of the offline store to log.

Parameters
logLevel The log level to be used for logging.

public void open (Action0 successHandler, Action1<OfflineODataException> failureHandler)

Opens the provider. After this call, the internal metadata data structure will be changed so any values cached in memory will need to be re-retrieved.

Example Usage:

 // Open OfflineODataProvider asynchronously
 offlineODataProvider.open(() -> logger.info("Open completed successfully."),
                           (error) -> logger.error("Exception encountered in OfflineOData open: ", error));

 
 

Parameters
successHandler a success callback function.
failureHandler a failure callback function.
See Also

public void pingServer (HttpHeaders paramHttpHeaders, RequestOptions paramRequestOptions)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#pingServer( HttpHeaders, RequestOptions )

Throws
DataServiceException runtime exception when an error occurs.
See Also
  • com.sap.cloud.mobile.odata.DataServiceException

public void processBatch (RequestBatch batch, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#processBatch( RequestBatch, HttpHeaders, RequestOptions )

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void removeDefiningQuery (OfflineODataDefiningQuery definingQuery)

Removes a defining query.

The defining queries of type 1 and 2 can only be removed before the OfflineODataProvider is open for the first time.

The defining queries of type 3 can be removed before or after the OfflineODataProvider has been opened.

Removing type 3 defining queries are not persistent when the OfflineODataProvider is not open, they will be lost the device is power off or application is terminated.

Parameters
definingQuery the defining query to remove.
Throws
OfflineODataException if an error occurs removing the defining query.

public void sendStore (Action0 successHandler, Action1<OfflineODataException> failureHandler)

Sends the Offline OData store to sever.

Example Usage:

 // Send store asynchronously
 offlineODataProvider.sendStore(() -> logger.info("Send store completed successfully."),
                                (error) -> logger.error("Exception encountered in offlineOData send store:" + error.getMessage()));

 
 

Parameters
successHandler a success callback function.
failureHandler a failure callback function.
See Also

public void setMetadata (CsdlDocument value)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#setMetadata(CsdlDocument)

Throws
DataServiceException runtime exception when an error occurs.
See Also
  • com.sap.cloud.mobile.odata.DataServiceException

public void setServiceOptions (OfflineODataServiceOptions serviceOptions)

Defines OfflineODataProvider service options.

Parameters
serviceOptions OfflineODataProvider service options. If null, OfflineODataProvider uses the default OfflineODataServiceOptions.

public void undoPendingChanges (EntityValue entity)

Undo pending local changes for a given entity. While you can make changes to existing entities and new entities locally, you can also undo the changes without uploading them. An existing entity will be restored to the original status as if no any changes had been made. A new entity will be removed as if the entity had never been created.

For example, say you have an existing entity customer101. You can either:

  • Patch customer101 several times. Undoing the changes will restore all property values.
  • Associate customer101 to some purchase orders. Undoing the changes will remove the relationships.
  • Delete customer101. Undoing this change will bring customer101 back.

As another example, say you have created a new entity customer102 locally. No matter what subsequent operations you apply to it, undoing the changes will remove customer102 as if this entity had never been created.

There are some more complex cases that Offline OData provides flexible support. For example, say you created a new entity order102 that deep inserted a new related entity customer102 in one request. There can be different sequences of performing undo:

  • Undo changes for customer102 first. In this case, customer102 will be removed, and order102 will remain (since you are not undoing changes for order102) but is not related to any customer (since customer102 has been removed). The original request for creating order102 and customer102 will be adjusted accordingly to produce the correct result.

    You can continue to undo changes for order102, which will remove it.

  • Undo changes for order102 first. In this case, order102 will be removed, and customer102 will remain (since you are not undoing changes for customer102) but is not related to any order (since order102 has been removed). The original request for creating order102 and customer102 will be adjusted accordingly to produce the correct result.

    You can continue to undo changes for customer102, which will remove it.

Undoing pending changes and enableUndoLocalCreation are somewhat related but there are some key differences:

  • Undoing local creation is an optimization for the back end to not send a POST request if a new entity created locally is deleted before it is uploaded. Undoing pending changes is not intended to be an optimization but rather allows correcting mistakes or changing your mind about what you did.
  • Undoing local creation only applies to new entities created locally. Undoing pending changes also applies to existing entities that have been downloaded from back end.
  • For a new entity created locally, you can remove it by undoing pending changes for it without performing a deletion. However, you need to perform a deletion on the entity if you want to apply undoing local creation in order to remove it.
  • Undoing local creation takes effect (removing affected requests from request queue) when you perform an upload. Undoing pending changes takes effect (removing affected requests from request queue) when you call the method.
  • The undoing local creation algorithm respects cascading deletes while undo pending changes does not.
  • Because undoing local creation is an optimization, it will not remove requests for deleted entities which would cause entities that were downloaded from the server to be deleted. Undoing pending changes on the other hand disregards whether the requests have a side affect on a server entity or not; it simply removes all references to the specified entity in the request queue.

Parameters
entity the entity to undo pending changes.
Throws
OfflineODataException if an error occurs when undoing changes.

public void unloadMetadata ()

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#unloadMetadata

Throws
DataServiceException runtime exception when an error occurs.
See Also
  • com.sap.cloud.mobile.odata.DataServiceException

public void updateEntity (EntityValue entity, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#updateEntity(EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void updateLink (EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#updateLink(EntityValue, Property, EntityValue, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void upload (Action0 successHandler, Action1<OfflineODataException> failureHandler)

Uploads local data to update the OData back end.

Example Usage:

 // Upload data asynchronously
 offlineODataProvider.upload(() -> logger.info("Upload completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData upload: ", error));

 
 

Parameters
successHandler a success callback function.
failureHandler a failure callback function.
See Also

public void upload (UploadCategory[] categories, Action0 successHandler, Action1<OfflineODataException> failureHandler)

Partial upload allows Offline OData applications to upload a subset of the requests in the request queue. Requests from multiple upload categories can be uploaded together by performing a partial upload, which is accomplished by calling the upload function with a list of upload categories to upload. All requests that the selected requests depend on are included in the upload, even if those requests are not in the specified upload categories.

Example Usage:

 // Upload data asynchronously
 // Upload with a pre-defined upload category of type string literal
 UploadCategory[] sampleUploadCategory1 = { new UploadCategory( "uploadCategory1" );
 offlineODataProvider.upload( sampleUploadCategory1,
                             () -> logger.info("Upload completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData upload: ", error));

 // Upload customer1 with its entity ID as an upload category of type string literal, even if it wasn't originally set as an upload category
 UploadCategory[] sampleUploadCategory2 = { new UploadCategory( customer1.getEditLink() ) ;
 offlineODataProvider.upload( sampleUploadCategory2,
                             () -> logger.info("Upload completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData upload: ", error));

 // Upload customer2 with its entity value as an upload category of type entity value
 UploadCategory[] sampleUploadCategory3 = { new UploadCategory( customer2 ) };
 offlineODataProvider.upload( sampleUploadCategory3,
                             () -> logger.info("Upload completed successfully."),
                             (error) -> logger.error("Exception encountered in OfflineOData upload: ", error));

 }
 

Parameters
categories Upload categories. The supported upload category types are: StringLiteral, EntityValue. GeneratedID is an unsupported upload category type.
successHandler A success callback function.
failureHandler A failure callback function.

public void uploadMedia (EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions options)

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#uploadMedia(EntityValue, StreamBase, HttpHeaders, RequestOptions)

Throws
DataServiceException runtime exception when an error occurs.
See Also

public void uploadStream (EntityValue entity, StreamLink link, StreamBase content, HttpHeaders headers, RequestOptions options)

OfflineODataProvider doesn't support Edm.Sream type yet, the method operates same as uploadStream of entity, the link parameter is the value of entity.getMediaStream().

Please reference com.sap.cloud.mobile.odata.DataServiceProvider#uploadStream(EntityValue, StreamLink, StreamBase, HttpHeaders, RequestOptions)

Parameters
link this value must be entity.getMediaStream.
Throws
DataServiceException runtime exception when an error occurs.
See Also