OnlineODataProvider

open class OnlineODataProvider : ObjectBase, DataServiceProvider, ClientRegistrationProvider, @unchecked Sendable

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 that EntityValue.entitySet is available.

    Throws

    DataServiceException if the entity set hasn’t been explicitly provided before calling createEntity 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 as label 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 or CharStream. 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 using ServiceOptions.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 is true.

    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 or DataNetworkException 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 by loadMetadata, or is automatically available in a generated DataService proxy class.

    Declaration

    Swift

    open var hasMetadata: Bool { get }

  • Obsolete. Use sessionCookies or sharedCookies.

    Declaration

    Swift

    open var httpCookies: HTTPCookies { get }

  • Obsolete. Use sessionHeaders or sharedHeaders.

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

    See also

    metadata, hasMetadata.

    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 as loadMetadata) 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.

    See also

    ServiceOptions.pingMethod, ServiceOptions.pingResource, ServiceOptions.pingAccept.

    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 to false.

    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 return false, 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 the ServiceOptions.clientInstanceID. The server’s metadata is expected to include a ClientRegistrationSet entity set with entity type ClientRegistration, a key property named ClientID of type long (Edm.Int64), and a property named ClientGUID of type guid (Edm.Guid). If a new registration is successfully created, ServiceOptions.clientInstanceID is set, and will subsequently be used to populate the Client-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 also true, should all requests for this data service be traced with data? Defaults to false. 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).

    See also

    metadata, hasMetadata.0

    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 the deleteFromServer parameter is true.

    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.