com.sap.cloud.server.odata

Interface DataServiceProvider

All Known Implementing Classes:

InMemoryDatabase, JsonEntityProvider, MetadataOnlyProvider, OfflineODataProvider, OnlineODataProvider, SQLDatabaseProvider

public interface DataServiceProvider

A provider interface for data services. Where applicable, client applications should use the DataService wrapper to invoke provider functions.

Method Summary

Modifier and Type	Method and Description
void	beginTransaction() Begin a server transaction.
void	commit() Commit the current server transaction.
void	createEntity(EntityValue entity, HttpHeaders headers, RequestOptions options) Create an entity in the target system.
void	createLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options) Create a link from a source entity to a target entity.
void	createMedia(EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions options) Create a media entity with the specified content in the target system.
void	deleteByQuery(DataQuery query, HttpHeaders headers, RequestOptions options) Execute query to delete data from the target system.
void	deleteEntity(EntityValue entity, HttpHeaders headers, RequestOptions options) Delete an entity from the target system.
void	deleteLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options) Delete a link from a source entity to a target entity.
void	deleteStream(EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options) Delete the content of a stream property from the target system.
ByteStream	downloadMedia(EntityValue entity, HttpHeaders headers, RequestOptions options) Obtain a stream for downloading the content of a media entity from the target system.
ByteStream	downloadStream(EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options) Obtain a stream for downloading the content of a stream property from the target system.
DataContext	entityContext(EntitySet entitySet, StructureType derivedType, int format, int version) Return a data context for a specified entity set, data format and data version.
DataValue	executeMethod(DataMethod method, ParameterList parameters, HttpHeaders headers, RequestOptions options) Execute a data method (action or function) in the target system.
QueryResult	executeQuery(DataQuery query, HttpHeaders headers, RequestOptions options) Execute a data query to get data from the target system.
CsdlDocument	fetchMetadata(HttpHeaders headers, RequestOptions options) Fetch latest service metadata and return it, but don't change the DataServiceProvider.metadata property.
DataTransaction	getDataTransaction() Return the current server transaction.
CsdlDocument	getMetadata() Return service metadata.
java.lang.String	getServiceName() Return service name.
boolean	hasMetadata() Return has service metadata been loaded.
void	loadMetadata(HttpHeaders headers, RequestOptions options) Load service metadata (if not already loaded).
java.lang.String	metadataText(int format) Return metadata document text of the service.
void	pingServer(HttpHeaders headers, RequestOptions options) Ping the server.
void	processBatch(RequestBatch batch, HttpHeaders headers, RequestOptions options) Execute a request batch in the target system.
DataContext	queryContext(int version) Return a data context for parsing a data query.
void	rollback() Rollback the current server transaction.
java.lang.String	serviceDocument(int format) Return the service document, in XML or JSON format.
void	setMetadata(CsdlDocument value) Set service metadata.
void	unloadMetadata() Unload service metadata (if previously loaded).
void	updateEntity(EntityValue entity, HttpHeaders headers, RequestOptions options) Update an entity in the target system.
void	updateLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options) Update a link from a source entity to a target entity.
void	uploadMedia(EntityValue entity, StreamBase content, HttpHeaders headers, RequestOptions 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.
void	uploadStream(EntityValue entity, StreamLink link, StreamBase content, HttpHeaders headers, RequestOptions options) Upload content for a stream property to the target system.

Method Detail

beginTransaction

void beginTransaction()

Begin a server transaction.

commit

void commit()

Commit the current server transaction.

createEntity

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

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.

Parameters:

entity - Entity to be created.

headers - Request-specific headers.

options - Request-specific options.

createLink

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

Create a link from a source entity to a target entity.

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.

createMedia

void createMedia(EntityValue entity,
                 StreamBase content,
                 HttpHeaders headers,
                 RequestOptions 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.

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.

deleteByQuery

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

Execute query to delete data from the target system.

Parameters:

query - Data query specifying the information to be deleted.

headers - Request-specific headers.

options - Request-specific options.

deleteEntity

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

Delete an entity from the target system.

Parameters:

entity - Entity to be deleted.

headers - Request-specific headers.

options - Request-specific options.

deleteLink

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

Delete a link from a source entity to a target entity.

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.

deleteStream

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

Delete the content of a stream property from the target system.

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.

downloadMedia

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

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.

Parameters:

entity - Entity whose content is to be downloaded.

headers - Request-specific headers.

options - Request-specific options.

Returns:

A stream for downloading the content of a media entity. This must be closed by the caller, or else a resource leak may occur.

downloadStream

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

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.

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.

Returns:

A stream for downloading the content of a stream property. This must be closed by the caller, or else a resource leak may occur.

entityContext

DataContext entityContext(EntitySet entitySet,
                          StructureType derivedType,
                          int format,
                          int version)

Return a data context for a specified entity set, data format and data version.

See Also:

DataFormat, DataVersion.

Parameters:

entitySet - Entity set for entity value to be parsed or formatted.

derivedType - (nullable) Derived type for query results.

format - Data format.

version - Data version.

Returns:

A data context for a specified entity set, data format and data version.

executeMethod

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

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.

Parameters:

method - Data method.

parameters - Method parameters.

headers - Request-specific headers.

options - Request-specific options.

Returns:

(nullable) The method result, or `null` if the method has no result.

executeQuery

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

Execute a data query to get data from the target system.

Parameters:

query - Data query specifying the information to be returned.

headers - Request-specific headers.

options - Request-specific options.

Returns:

The query result.

fetchMetadata

CsdlDocument fetchMetadata(HttpHeaders headers,
                           RequestOptions options)

Fetch latest service metadata and return it, but don't change the DataServiceProvider.metadata property.

See Also:

DataServiceProvider.loadMetadata.

Parameters:

headers - Optional request-specific headers.

options - Optional request-specific options.

Returns:

Latest service metadata.

getDataTransaction

DataTransaction getDataTransaction()

Return the current server transaction.

Returns:

The current server transaction.

getMetadata

CsdlDocument getMetadata()

Return service metadata.

See Also:

DataServiceProvider.loadMetadata.

Returns:

Service metadata.

getServiceName

java.lang.String getServiceName()

Return service name.

Returns:

Service name.

hasMetadata

boolean hasMetadata()

Return has service metadata been loaded.

See Also:

DataServiceProvider.loadMetadata.

Returns:

Has service metadata been loaded.

loadMetadata

void loadMetadata(HttpHeaders headers,
                  RequestOptions options)

Load service metadata (if not already loaded).

See Also:

DataServiceProvider.metadata, DataServiceProvider.hasMetadata.

Parameters:

headers - Optional request-specific headers.

options - Optional request-specific options.

metadataText

java.lang.String metadataText(int format)

Return metadata document text of the service.

See Also:

DataFormat.

Parameters:

format - Metadata format. Only XML is presently supported.

Returns:

Metadata document text of the service.

pingServer

void pingServer(HttpHeaders headers,
                RequestOptions options)

Ping the server.

Parameters:

headers - Optional request-specific headers.

options - Optional request-specific options.

processBatch

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

Execute a request batch in the target system.

Parameters:

batch - The request batch.

headers - Request-specific headers.

options - Request-specific options.

queryContext

DataContext queryContext(int version)

Return a data context for parsing a data query.

See Also:

DataVersion.

Parameters:

version - Data version.

Returns:

A data context for parsing a data query.

rollback

void rollback()

Rollback the current server transaction.

serviceDocument

java.lang.String serviceDocument(int format)

Return the service document, in XML or JSON format.

See Also:

DataFormat.

Parameters:

format - Data format (XML or JSON).

Returns:

The service document, in XML or JSON format.

setMetadata

void setMetadata(CsdlDocument value)

Set service metadata.

See Also:

DataServiceProvider.loadMetadata.

Parameters:

value - Service metadata.

unloadMetadata

void unloadMetadata()

Unload service metadata (if previously loaded).

See Also:

DataServiceProvider.metadata, DataServiceProvider.hasMetadata.

updateEntity

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

Update an entity in the target system.

Parameters:

entity - Entity to be updated.

headers - Request-specific headers.

options - Request-specific options.

updateLink

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

Update a link from a source entity to a target entity.

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.

uploadMedia

void uploadMedia(EntityValue entity,
                 StreamBase content,
                 HttpHeaders headers,
                 RequestOptions 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.

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.

uploadStream

void uploadStream(EntityValue entity,
                  StreamLink link,
                  StreamBase content,
                  HttpHeaders headers,
                  RequestOptions 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.

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.