OnlineODataProvider
open class OnlineODataProvider : ObjectBase, DataServiceProvider, ClientRegistrationProvider
A data service provider for online OData.
-
Constructs an online OData provider.
Declaration
Swift
public convenience init(serviceRoot: URL, sapURLSession: SAPURLSession = SAPURLSession())
Parameters
serviceRoot
Service root URL.
-
Constructs an online OData provider.
Declaration
Swift
public convenience init(serviceName: String, serviceRoot: URL, sapURLSession: SAPURLSession = SAPURLSession())
Parameters
serviceName
Service name.
serviceRoot
Service root URL.
-
URL session instance to be used by this data service.
Declaration
Swift
public var sapURLSession: SAPURLSession? { get set }
-
If this data service requires a security token, then acquire it now.
See also
ServiceOptions.requiresToken
.Declaration
Swift
open func acquireToken() throws
-
Create an entity in the target system. Automatically calls
CsdlDocument.resolveEntity
to ensure thatEntityValue.entitySet
is available.Throws
DataServiceException
if the entity set hasn’t been explicitly provided before callingcreateEntity
and there isn’t a unique entity set for the entity type.See also
EntityValue.ofType
,EntityValue.inSet
.Declaration
Swift
open func createEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity to be created.
headers
Request-specific headers.
options
Request-specific options.
-
Create a link from a source entity to a target entity.
Declaration
Swift
open func createLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
from
Source entity for the link to be created.
property
Source navigation property for the link to be created.
to
Target entity for the link to be created.
headers
Request-specific headers.
options
Request-specific options.
-
Create a media entity with the specified content in the target system. If the
entity
has non-stream structural properties in addition to the key properties and media content, such aslabel
in the examples below, then this function will send two requests to the server: a first request to upload (POST) the media stream, and a second request (PATCH/PUT) to update the non-stream properties. It is not currently supported to make these two calls atomic. Caution: Having too many threads simultaneously creating streams may result in out-of-memory conditions on memory-constrained devices.Declaration
Swift
open func createMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity to be created.
content
Initial content. Must be a
ByteStream
orCharStream
. Will be closed before this function returns.headers
Request-specific headers.
options
Request-specific options.
-
Lookup a data method by qualified name (for function/action definitions) or by unqualified name (for function/action imports).
Declaration
Swift
open func dataMethod(name: String) -> DataMethod
Parameters
name
Name of the data method to be returned.
Return Value
The data method.
-
Execute query to delete data from the target system.
Declaration
Swift
open func deleteByQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
query
Data query specifying the information to be deleted.
headers
Request-specific headers.
options
Request-specific options.
-
Delete an entity from the target system.
Declaration
Swift
open func deleteEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity to be deleted.
headers
Request-specific headers.
options
Request-specific options.
-
Delete a link from a source entity to a target entity.
Declaration
Swift
open func deleteLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
from
Source entity for the link to be deleted.
property
Source navigation property for the link to be deleted.
to
Target entity for the link to be deleted.
headers
Request-specific headers.
options
Request-specific options.
-
Ask the server to forget (delete) the repeatable request with the specified
requestID
.Declaration
Swift
open func deleteRepeatableRequest(requestID: GuidValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
requestID
Repeatability-Request-ID header value used in previous repeatable request.
headers
Optional request-specific headers.
options
Optional request-specific options.
-
Ask the server to forget (delete) the repeatable requests with the specified
requestIDs
.Declaration
Swift
open func deleteRepeatableRequests(requestIDs: GuidValueList?, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
requestIDs
List of request IDs, or
nil
if Repeatability-Client-ID header value was used in previous repeatable requests, and for improved efficiency the bulk deletion of repeatable requests can be done usingServiceOptions.repeatabilityClientID
.headers
Optional request-specific headers.
options
Optional request-specific options.
-
Delete the content of a stream property from the target system.
Declaration
Swift
open func deleteStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity containing the stream property whose content is to be deleted.
headers
Request-specific headers.
options
Request-specific options.
link
Stream link for the stream to be deleted.
-
Execute a query and obtain the result as a stream of delta items.
Declaration
Swift
open func deltaStream(query: DataQuery, headers: HTTPHeaders = HTTPHeaders.empty, options: RequestOptions = RequestOptions.none) throws -> DeltaStream
Parameters
query
Data query.
headers
Request-specific headers.
options
Request-specific options.
Return Value
Delta stream.
-
Obtain a stream for downloading the content of a media entity from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using
ByteStream.readAndClose
, may result in out-of-memory conditions on memory-constrained devices.Declaration
Swift
open func downloadMedia(entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream
Parameters
entity
Entity whose content is to be downloaded.
headers
Request-specific headers.
options
Request-specific options.
Return Value
A stream for downloading the content of a media entity. This must be closed by the caller, or else a resource leak may occur.
-
Obtain a stream for downloading the content of a stream property from the target system. Caution: streams are often used for large content that may not fit (all at once) in available application memory. Having too many threads simultaneously downloading streams, or using
ByteStream.readAndClose
, may result in out-of-memory conditions on memory-constrained devices.See also
Property.getStreamLink
.Declaration
Swift
open func downloadStream(entity: EntityValue, link: StreamLink, headers: HTTPHeaders, options: RequestOptions) throws -> ByteStream
Parameters
entity
Entity containing the stream property whose content is to be downloaded.
link
Stream link for the stream to be downloaded.
headers
Request-specific headers.
options
Request-specific options.
Return Value
A stream for downloading the content of a stream property. This must be closed by the caller, or else a resource leak may occur.
-
Lookup an entity set (or singleton entity) by name. Note that OData singleton entities are represented by entity sets where
EntitySet.isSingleton
istrue
.Declaration
Swift
open func entitySet(name: String) -> EntitySet
Parameters
name
Name of the entity set to be returned.
Return Value
The entity set.
-
Execute a query and obtain the result as a stream of entity values.
Declaration
Swift
open func entityStream(query: DataQuery, headers: HTTPHeaders = HTTPHeaders.empty, options: RequestOptions = RequestOptions.none) throws -> EntityStream
Parameters
query
Data query.
headers
Request-specific headers.
options
Request-specific options.
Return Value
Entity stream.
-
Execute a data method (action or function) in the target system. Actions may have backend side-effects. Functions should not have backend side-effects.
Throws
DataServiceException
orDataNetworkException
if an error occurs during action invocation.Declaration
Swift
open func executeMethod(_ method: DataMethod, parameters: ParameterList, headers: HTTPHeaders, options: RequestOptions) throws -> DataValue?
Parameters
method
Data method.
parameters
Method parameters.
headers
Request-specific headers.
options
Request-specific options.
Return Value
The method result, or
nil
if the method has no result. -
Execute a data query to get data from the target system.
Declaration
Swift
open func executeQuery(_ query: DataQuery, headers: HTTPHeaders, options: RequestOptions) throws -> QueryResult
Parameters
query
Data query specifying the information to be returned.
headers
Request-specific headers.
options
Request-specific options.
Return Value
The query result.
-
Fetch latest service metadata and return it, but don’t change the
metadata
property.See also
loadMetadata
.Declaration
Swift
open func fetchMetadata(headers: HTTPHeaders, options: RequestOptions) throws -> CSDLDocument
Parameters
headers
Optional request-specific headers.
options
Optional request-specific options.
Return Value
Latest service metadata.
-
true
if the service metadata has been loaded byloadMetadata
, or is automatically available in a generated DataService proxy class.Declaration
Swift
open var hasMetadata: Bool { get }
-
Obsolete. Use
sessionCookies
orsharedCookies
.Declaration
Swift
open var httpCookies: HTTPCookies { get }
-
Obsolete. Use
sessionHeaders
orsharedHeaders
.Declaration
Swift
open var httpHeaders: HTTPHeaders { get }
-
Checks locally whether a previous
registerClient
call successfuly created a client registration for the remote OData service.Declaration
Swift
open func isClientRegistered() throws -> Bool
Return Value
true
if a registration was already established. -
Load service metadata (if not already loaded).
Declaration
Swift
open func loadMetadata(headers: HTTPHeaders, options: RequestOptions) throws
Parameters
headers
Optional request-specific headers.
options
Optional request-specific options.
-
Set the shared
Authorization
header to be used for HTTP/HTTPS with pre-emptive BASIC authentication. If credentials are required by the remote data service, they must be set before any function calls (such asloadMetadata
) which may make a network request. For services which require challenge-based authentication, a request interceptor/observer should be used.See also
sharedHeaders
.Declaration
Swift
open func login(username: String, password: String)
Parameters
username
Client’s username.
password
Client’s password.
-
The OData CSDL document (service metadata).
Declaration
Swift
open var metadata: CSDLDocument { get set }
-
Options for network communication, which for OData uses HTTP or HTTPS.
Declaration
Swift
@inline(__always) public final var networkOptions: NetworkOptions { get }
-
Ping the server, by sending a non-changing request that the server can respond to quickly. The default ping behaviour is to send a GET request for the service document.
Declaration
Swift
open func pingServer(headers: HTTPHeaders, options: RequestOptions) throws
Parameters
headers
Optional request-specific headers.
options
Optional request-specific options.
-
Should
traceWithData
show pretty-printed JSON/XML content? Defaults tofalse
.Declaration
Swift
@inline(__always) public final var prettyTracing: Bool { get set }
-
Execute a request batch in the target system.
Declaration
Swift
open func processBatch(_ batch: RequestBatch, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
batch
The request batch.
headers
Request-specific headers.
options
Request-specific options.
-
If
isClientRegistered
would returnfalse
, create a new client registration and record its key (ClientID property of type GUID) in local file~/ClientRegistration/<ServiceName>.json
. Otherwise just load the previously locally-saved registration ID into theServiceOptions.clientInstanceID
. The server’s metadata is expected to include aClientRegistrationSet
entity set with entity typeClientRegistration
, a key property namedClientID
of typelong
(Edm.Int64), and a property namedClientGUID
of typeguid
(Edm.Guid). If a new registration is successfully created,ServiceOptions.clientInstanceID
is set, and will subsequently be used to populate theClient-Instance-ID
HTTP header for all OData calls. The purpose of creating such a client registration is to enable the server to associate various resources with the current instance of the current client application. A “current instance” can survive multiple restarts of the client application so long as the same Client-Instance-ID header value is provided for each OData call to the remote service. This is particularly useful for offline applications which rely on server-side OData change tracking implementations that store per-client server-side state to facilitate change tracking.Declaration
Swift
open func registerClient(_ client: EntityValue?) throws
Parameters
client
Instance of
ClientRegistration
entity type. If omitted, a default instance will be created. -
The service name.
Declaration
Swift
open var serviceName: String { get }
-
Options for this data service, both client-side and server-side.
Declaration
Swift
@inline(__always) public final var serviceOptions: ServiceOptions { get }
-
The service root URL. The service root URL always terminates with a forward slash.
Declaration
Swift
open var serviceRoot: String { get set }
-
HTTP cookies which should be sent in future online requests (by the current session / thread).
Declaration
Swift
open var sessionCookies: HTTPCookies { get }
-
HTTP headers which should be sent in future online requests (by the current session / thread).
Declaration
Swift
open var sessionHeaders: HTTPHeaders { get }
-
HTTP cookies which should be sent in future online requests (shared by all sessions / threads).
Declaration
Swift
open var sharedCookies: HTTPCookies { get }
-
HTTP headers which should be sent in future online requests (shared by all sessions / threads).
Declaration
Swift
open var sharedHeaders: HTTPHeaders { get }
-
Should all requests for this data service be traced? Defaults to
false
.Declaration
Swift
@inline(__always) public final var traceRequests: Bool { get set }
-
If
traceRequests
is alsotrue
, should all requests for this data service be traced with data? Defaults tofalse
. Note that care must be taken when enabling tracing with data, as the resulting log files may contain sensitive information. On the other hand, tracing with data may sometimes be invaluable for troubleshooting purposes.Declaration
Swift
@inline(__always) public final var traceWithData: Bool { get set }
-
Unload service metadata (if previously loaded).
Declaration
Swift
open func unloadMetadata() throws
-
Forget any client registration previously established by
registerClient
. Also attempts to make a call to the server to delete the associated entity, if thedeleteFromServer
parameter istrue
.Declaration
Swift
open func unregisterClient(deleteFromServer: Bool) throws
Parameters
deleteFromServer
Specify a value of
true
to request the server to also delete the corresponding entity. -
Update an entity in the target system.
Declaration
Swift
open func updateEntity(_ entity: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity to be updated.
headers
Request-specific headers.
options
Request-specific options.
-
Update a link from a source entity to a target entity.
Declaration
Swift
open func updateLink(from: EntityValue, property: Property, to: EntityValue, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
from
Source entity for the link to be updated.
property
Source navigation property for the link to be updated. This must be a one-to-one navigation property.
to
Target entity for the link to be updated.
headers
Request-specific headers.
options
Request-specific options.
-
Upload content for a media entity to the target system Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices. Note: this function cannot be used to create a media entity. See
DataService.createMedia
.Declaration
Swift
open func uploadMedia(entity: EntityValue, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity whose content is to be uploaded.
content
Upload stream content. Will be closed before this function returns.
headers
Request-specific headers.
options
Request-specific options.
-
Upload content for a stream property to the target system. Caution: Having too many threads simultaneously uploading streams may result in out-of-memory conditions on memory-constrained devices.
See also
Property.getStreamLink
.Declaration
Swift
open func uploadStream(entity: EntityValue, link: StreamLink, content: StreamBase, headers: HTTPHeaders, options: RequestOptions) throws
Parameters
entity
Entity containing the stream property whose content is to be uploaded.
link
Stream link for the stream to be uploaded.
content
Upload stream content. Will be closed before this function returns.
headers
Request-specific headers.
options
Request-specific options.