OfflineODataProvider

open class OfflineODataProvider : DataServiceProvider

A data service provider for Offline OData.

  • OfflineODataProvider service options.

    Declaration

    Swift

    public var serviceOptions: OfflineODataServiceOptions
  • The version of the Offline OData library.

    Declaration

    Swift

    public static var libraryVersion: String { get }
  • Initializes an OfflineODataProvider.

    Throws

    OfflineODataError if an error occurs initializing the OfflineODataProvider.

    Declaration

    Swift

    public init( serviceRoot: URL, parameters: OfflineODataParameters, sapURLSession: SAPURLSession, delegate: OfflineODataDelegate? = nil ) throws

    Parameters

    serviceRoot

    The service root of the OData backend. This value depends on the Rewrite Mode configuration of the application in SAP Cloud Platform mobile service for development and operations. 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 Back End then the path or the service root should be the same as the path of the Back-End URL specified in 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 to an OData backend with service root http://myhost:80/odata/endpoint then 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.

    sapURLSession

    The SAPURLSession to handle network authentication.

    delegate

    The methods of this delegate are called at various stages during the execution of open, download, and upload.

    Return Value

    Instance of OfflineODataProvider.

  • The name of the Offline OData store.

    Declaration

    Swift

    open var serviceName: String { get }
  • The name of the Offline OData store.

    Declaration

    Swift

    open var serviceName_NS: NSString { get }
  • Whether or not the provider has metadata.

    Declaration

    Swift

    open var hasMetadata: Bool { get }
  • Metadata of the service. See CSDLDocument.

    Declaration

    Swift

    open var metadata: CSDLDocument { get set }
  • Logger of the provider. App developers can configure log level on the logger and control what level of information will be logged.

    See SAPCommon.Logger.

    Declaration

    Swift

    public var logger: SAPCommon.Logger { get }
  • Deletes the physical store from the file system. All instances of the OfflineODataProvider must be closed before the physical store can be deleted.

    Throws

    OfflineODataError if an error occurs deleting the store.

    Declaration

    Swift

    public static func clear(at path: URL?, withName name: String?) throws

    Parameters

    path

    The file system path of the local data store.

    name

    The name of the store.

  • 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

    OfflineODataError if an error occurs closing or deleting the store.

    Declaration

    Swift

    public func clear() throws
  • 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).

    Throws

    OfflineODataError if an error occurs closing the OfflineODataProvider.

    Declaration

    Swift

    public func close() throws
  • Checks whether or not the there are any pending requests stored in the request queue that have not yet been uploaded.

    Throws

    OfflineODataError if an error occurs determing whether the request queue is empty.

    Declaration

    Swift

    public func requestQueueIsEmpty() throws -> Bool

    Return Value

    true if the request queue is empty and false otherwise.

  • Checks whether or not there is a pending download.

    Throws

    OfflineODataError if an error occurs determing whether or not there is a pending download.

    Declaration

    Swift

    public func hasPendingDownload() throws -> Bool

    Return Value

    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.

  • Checks whether or not there is a pending upload.

    Throws

    OfflineODataError if an error occurs determing whether or not there is a pending upload.

    Declaration

    Swift

    public func hasPendingUpload() throws -> Bool

    Return Value

    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.

  • Open 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.

    Declaration

    Swift

    public func open( completionHandler: @escaping ( _ error: OfflineODataError? ) -> Void ) -> Void

    Parameters

    completionHandler

    The completion handler.

  • Upload local data to update the OData backend.

    Declaration

    Swift

    public func upload( completionHandler:@escaping ( _ error: OfflineODataError? ) -> Void ) -> Void

    Parameters

    completionHandler

    The completion handler.

  • Download the data for all defining queries from the OData backend to update the local data. If the defining queries are delta enabled, only the changes will be downloaded.

    Declaration

    Swift

    public func download( completionHandler:@escaping( _ error: OfflineODataError? ) -> Void ) -> Void

    Parameters

    completionHandler

    The completion handler.

  • Downloads the data for the specified subset of defining queries from the OData backend to update the local data. If the defining queries are delta enabled, only the changes will be downloaded.

    Declaration

    Swift

    public func download( withSubset subset: [OfflineODataDefiningQuery], completionHandler:@escaping ( _ error: OfflineODataError? ) -> Void ) -> Void

    Parameters

    subset

    The subset of the defining queries to download.

    completionHandler

    The completion handler.

  • Cancels all downloads and file downloads including those that are queued. This method will also cancel an initial download and file download if it is called while the OfflineODataProvider is opening for the first time.

    Throws

    OfflineODataError if there are no downloads or file downloads to cancel

    Declaration

    Swift

    public func cancelDownload() throws
  • Cancels the current upload.

    Throws

    OfflineODataError if there are no uploads to cancel

    Declaration

    Swift

    public func cancelUpload() throws
  • Asynchronously sends Offine store to CPms server.

    Declaration

    Swift

    public func sendStore( completionHandler:@escaping ( _ error: OfflineODataError? ) -> Void ) -> Void

    Parameters

    completionHandler

    The completion handler.

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

    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.

    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.

    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.

    For performance reasons, it is not recommended (although it is supported) to use $expand in defining queries, unless your OData backend 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 metadata 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.

    Throws

    OfflineODataError if an error occurs adding the defining query.

    Declaration

    Swift

    public func add(definingQuery: OfflineODataDefiningQuery) throws

    Parameters

    definingQuery

    The defining query to add.

  • Remove a defining query.

    See also

    Reference add(definingQuery:) function for the three types of defining queries.

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

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

    Throws

    OfflineODataError if an error occurs removing the defining query.

    Declaration

    Swift

    public func remove(definingQuery: OfflineODataDefiningQuery) throws

    Parameters

    definingQuery

    The defining query to remove.

  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func createEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func createLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

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

    Declaration

    Swift

    open func createMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func deleteByQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func deleteEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func deleteStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func deleteLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func downloadMedia(entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func downloadStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func executeQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws -> QueryResult
  • Query the ErrorArchive, the builtin Offline OData entity set which contains information about requests that failed during the last upload.

    Declaration

    Swift

    open func fetchErrorArchive(query: DataQuery = DataQuery()) throws -> Array<OfflineODataErrorArchiveEntity>
  • Query the EventLog, the builtin Offline OData entity set which contains information about Offline OData events such as upload and download.

    Declaration

    Swift

    open func fetchEventLog(query: DataQuery = DataQuery()) throws -> Array<OfflineODataEvent>
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func processBatch(_ batch: RequestBatch, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func updateEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func updateLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func uploadMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
  • Dump content (as a JSON object) of request queue of the offline store to log.

    See SAPCommon.LogLevel.

    Declaration

    Swift

    public func logRequestQueue( level: SAPCommon.LogLevel = SAPCommon.LogLevel.debug ) throws -> Void

    Parameters

    logLevel

    The log level to use for logging. Default to debug.

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

    See SAPCommon.LogLevel.

    Declaration

    Swift

    public func logDefiningQueries( level: SAPCommon.LogLevel = SAPCommon.LogLevel.debug ) throws -> Void

    Parameters

    logLevel

    The log level to use for logging. Default to debug.

  • Offline OData does not support this method.

    Declaration

    Swift

    open func executeMethod(_ method: DataMethod, parameters: ParameterList, headers: HTTPHeaders, options: RequestOptions) throws -> DataValue?
  • Pings the server to check that both the Offline Server component and the OData backend are reachable. This function will return successfully if both are reachable and will throw an error otherwise.

    Throws

    DataServiceError If an error occurs pinging the server.

    Declaration

    Swift

    open func pingServer( headers: HTTPHeaders = HTTPHeaders.empty, options: RequestOptions = RequestOptions.none ) throws -> Void
  • 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:

    1. Patch customer101 several times. Undoing the changes will restore all property values.

    2. Associate customer101 to some purchase orders. Undoing the changes will remove the relationships.

    3. 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:

    1. 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.

    2. 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 undoing local creation (see OfflineODataParameters.enableUndoLocalCreation) are somewhat related but there are some key differences:

    1. 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.

    2. 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.

    3. 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.

    4. 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.

    5. The undoing local creation algorithm respects cascading deletes while undo pending changes does not.

    6. 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. Undo 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.

    Declaration

    Swift

    open func undoPendingChanges(for entity: EntityValue) throws

    Parameters

    for

    The entity to undo pending changes.

  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func loadMetadata( headers: HTTPHeaders = HTTPHeaders.empty, options: RequestOptions = RequestOptions.none ) throws -> Void
  • See definition in DataServiceProvider.

    Declaration

    Swift

    open func unloadMetadata() throws