public class SQLDatabaseProvider extends java.lang.Object implements DataServiceProvider
An implementation of DataServiceProvider
using a SQL database.
Tested (in Java runtime) with H2, PostgreSQL, SAP HANA, SAP ASE, and SAP SQL Anywhere.
Constructor and Description |
---|
SQLDatabaseProvider(java.lang.String serviceName)
|
SQLDatabaseProvider(java.lang.String serviceName,
java.lang.String databaseURL)
Constructs a SQL database provider.
|
Modifier and Type | Method and Description |
---|---|
void |
applyChanges(ChangeSet changes)
|
void |
applyChanges(ChangeSet changes,
HttpHeaders headers)
|
void |
applyChanges(ChangeSet changes,
HttpHeaders headers,
RequestOptions options)
Apply the changes from a change set to the target system.
|
void |
beginTransaction()
Begin a new transaction, or begin a nested transaction if a transaction is already active for this provider in the current thread.
|
void |
bindEntities(EntityValue entity)
|
void |
bindEntities(EntityValue entity,
Property bindingProperty)
|
void |
bindEntities(EntityValue entity,
Property bindingProperty,
boolean afterCreate)
|
void |
bindEntities(EntityValue entity,
Property bindingProperty,
boolean afterCreate,
boolean afterUpdate)
This function may be used in the implementation of entity binding calls, e.g.
|
void |
bindEntitiesAfterCreate(EntityValue entity)
|
void |
bindEntitiesAfterCreate(EntityValue entity,
Property bindingProperty)
This function may be used in the implementation of entity binding calls after the main create action of
SQLDatabaseProvider.createEntity . |
void |
bindEntitiesAfterUpdate(EntityValue entity)
|
void |
bindEntitiesAfterUpdate(EntityValue entity,
Property bindingProperty)
This function may be used in the implementation of entity binding calls after the main update action of
SQLDatabaseProvider.updateEntity . |
void |
closeAllConnections()
Close connections to this database from all threads.
|
void |
closeConnection()
If the current thread is connected to this database, then disconnect it.
|
void |
commit()
Commit the current transaction.
|
void |
createChildren(EntityValue entity)
|
void |
createChildren(EntityValue entity,
Property childProperty)
This function may be used in the implementation of "deep insert" calls, e.g.
|
void |
createClientExpiry(EntityValue registration)
Arrange for client expiry after a client registration has been created.
|
void |
createEntity(EntityValue entity)
|
void |
createEntity(EntityValue entity,
HttpHeaders headers)
|
void |
createEntity(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Create an entity in the target system.
|
java.lang.RuntimeException |
createEntityReturningError(EntityValue entity)
|
java.lang.RuntimeException |
createEntityReturningError(EntityValue entity,
HttpHeaders headers)
|
java.lang.RuntimeException |
createEntityReturningError(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Call
SQLDatabaseProvider.createEntity but catch any excepion it throws (non-logged) and return it. |
void |
createLink(EntityValue from,
Property property,
EntityValue to)
|
void |
createLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers)
|
void |
createLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers,
RequestOptions options)
Create a link from a source entity to a target entity.
|
void |
createLinkUsingForeignKeys(EntityValue source,
Property sourceProperty,
EntityValue target)
Default implementation of 'createLink' using foreign keys from referential constraints in service metadata.
|
void |
createMedia(EntityValue entity,
StreamBase content)
|
void |
createMedia(EntityValue entity,
StreamBase content,
HttpHeaders headers)
|
void |
createMedia(EntityValue entity,
StreamBase content,
HttpHeaders headers,
RequestOptions options)
Create a media entity with the specified content in the target system.
|
void |
createParents(EntityValue entity)
|
void |
createParents(EntityValue entity,
Property parentProperty)
This function may be used in the implementation of "deep insert" calls, e.g.
|
void |
createSchema()
Create (if non-existent) the database schema artifacts (e.g.
|
void |
createSchemaForTenant()
Create (if non-existent) the database artifacts (e.g.
|
void |
createSchemaWithRetryLoop()
Create (if non-existent) the database schema artifacts (e.g.
|
GlobalDateTime |
currentLDT()
Return the current local date/time according to the database server.
|
GlobalDateTime |
currentUTC()
Return the current global time (UTC) according to the database server.
|
void |
deleteByQuery(DataQuery query)
|
void |
deleteByQuery(DataQuery query,
HttpHeaders headers)
|
void |
deleteByQuery(DataQuery query,
HttpHeaders headers,
RequestOptions options)
Execute query to delete data from the target system.
|
void |
deleteChildren(EntityValue entity)
|
void |
deleteChildren(EntityValue entity,
Property childProperty)
This function may be used in the implementation of "on delete" actions, e.g.
|
void |
deleteEntity(EntityValue entity)
|
void |
deleteEntity(EntityValue entity,
HttpHeaders headers)
|
void |
deleteEntity(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Delete an entity from the target system.
|
java.lang.RuntimeException |
deleteEntityReturningError(EntityValue entity)
|
java.lang.RuntimeException |
deleteEntityReturningError(EntityValue entity,
HttpHeaders headers)
|
java.lang.RuntimeException |
deleteEntityReturningError(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Call
SQLDatabaseProvider.deleteEntity but catch any excepion it throws (non-logged) and return it. |
void |
deleteLink(EntityValue from,
Property property,
EntityValue to)
|
void |
deleteLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers)
|
void |
deleteLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers,
RequestOptions options)
Delete a link from a source entity to a target entity.
|
void |
deleteLinkUsingForeignKeys(EntityValue source,
Property sourceProperty,
EntityValue target)
Default implementation of 'deleteLink' using foreign keys from referential constraints in service metadata.
|
void |
deleteSchema()
Delete (if existing) the database schema artifacts (e.g.
|
void |
deleteSchemaForTenant()
Delete (if existing) the database artifacts (e.g.
|
void |
deleteStream(EntityValue entity,
StreamLink link)
|
void |
deleteStream(EntityValue entity,
StreamLink link,
HttpHeaders headers)
|
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)
|
ByteStream |
downloadMedia(EntityValue entity,
HttpHeaders headers)
|
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)
|
ByteStream |
downloadStream(EntityValue entity,
StreamLink link,
HttpHeaders headers)
|
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.
|
void |
executeBatch()
If the current thread's connection has batched statements, execute them now.
|
DataValue |
executeMethod(DataMethod method,
ParameterList parameters)
|
DataValue |
executeMethod(DataMethod method,
ParameterList parameters,
HttpHeaders headers)
|
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)
|
QueryResult |
executeQuery(DataQuery query,
HttpHeaders headers)
|
QueryResult |
executeQuery(DataQuery query,
HttpHeaders headers,
RequestOptions options)
Execute a data query to get data from the target system.
|
void |
expandItem(EntityValue entity,
ExpandItem item)
Override this function to implement item expansion for this service.
|
void |
expandItems(DataQuery query,
DataValue result)
|
CsdlDocument |
fetchMetadata(HttpHeaders headers,
RequestOptions options)
Fetch latest service metadata and return it, but don't change the
SQLDatabaseProvider.metadata property. |
boolean |
getAllowNonUtcTimeZone()
Return can the database clock be configured with a time zone other than UTC? Defaults to
false . |
boolean |
getAutoBindEntities()
Return should this provider automatically bind entities in
SQLDatabaseProvider.createEntity or SQLDatabaseProvider.updateEntity , if bound entities are provided by the client. |
boolean |
getAutoCreateChildren()
Return should this provider automatically create children in
SQLDatabaseProvider.createEntity ("deep insert" calls), if nested children are provided by the client. |
boolean |
getAutoCreateParents()
Return should this provider automatically create parents in
SQLDatabaseProvider.createEntity ("deep insert" calls), if nested parents are provided by the client. |
boolean |
getAutoDeleteChildren()
Return should this provider automatically delete children in
SQLDatabaseProvider.deleteEntity ("on delete" actions), if specified with OnDelete in the service metadata. |
boolean |
getAutoExpandItems()
Return should this provider automatically expand itemns in
SQLDatabaseProvider.executeQuery , if requested in the client's query. |
boolean |
getAutoGenerateKeys()
Return should this provider automatically generate primary keys? Defaults to
true . |
boolean |
getAutoUnbindEntities()
Return should this provider automatically unbind entities in
SQLDatabaseProvider.createEntity or SQLDatabaseProvider.updateEntity , if unbound entities are provided by the client. |
int |
getCacheOldestTransactionForSeconds()
Return when determining the start time of the oldest active database transaction for change tracking queries, how long can a cached transaction time be used for? Defaults to
5 . |
boolean |
getCanModifySchema()
Return is this provider permitted to modify the database schema, e.g.
|
DayTimeDuration |
getClientExpiryInterval()
Return if
SQLDatabaseProvider.startClientExpiryThread is called, how often should it perform cleanup activity? Defaults to one hour. |
void |
getConnection()
If the current thread is not connected to this database, then connect it.
|
DataTransaction |
getDataTransaction()
Return the current server transaction.
|
boolean |
getDebugConnections()
Return should all connections (opening/closing) to this SQL database service be logged? Defaults to
false . |
DayTimeDuration |
getDeltaCleanupInterval()
Return if
SQLDatabaseProvider.startDeltaCleanupThread is called, how often should it perform cleanup activity? Defaults to one hour. |
int |
getDownloadBeforeOldestTransaction()
Return when determining the next "last download" time for delta downloads, how many seconds should it be prior to the start time of the oldest active database transaction? Defaults to
5 . |
boolean |
getEnableChangeTracking()
Return should this provider be enabled for change tracking? Defaults to
false . |
boolean |
getEnableKeyTracking()
Return should this provider use key tracking for determining when "delete" is required in delta responses? Defaults to
false . |
boolean |
getEnableRowVersioning()
Return should this provider be enabled for row versioning? Defaults to
false . |
boolean |
getFlattenComplexProperties()
Return should complex properties be flattened into separate columns for database storage? Defaults to
false . |
boolean |
getGenerateForeignKeyConstraints()
Return should the provider generate
foreign key constraints when it creates database tables? Defaults to false . |
boolean |
getGenerateUniqueConstraints()
Return should the provider generate
unique constraints when it creates database tables? Defaults to false . |
boolean |
getLogExceptions()
Return should all database exceptions be logged?
|
boolean |
getMaintainTrackingColumns()
Return should this provider maintain delta-tracking columns? Defaults to
false . |
boolean |
getMaintainVersionColumns()
Return should this provider maintain the row version column? Defaults to
false . |
CsdlDocument |
getMetadata()
Return service metadata.
|
boolean |
getOldestTransactionForAllDatabases()
Return when determining the start time of the oldest active database transaction for change tracking queries, should the oldest active transaction time for all databases be used?
Defaults to
false , so that only the current database (or current schema, if applicable) is considered. |
DayTimeDuration |
getRetainDeletionsFor()
Return if change tracking is enabled, how long should logically deleted rows be retained to support subsequent delta queries? Defaults to 50 days.
|
boolean |
getSelectAfterCreate()
Return should entities be reselected after
SQLDatabaseProvider.createEntity (SQL insert)? Defaults to true . |
boolean |
getSelectAfterUpdate()
Return should entities be reselected after
SQLDatabaseProvider.updateEntity (SQL update)? Defaults to true . |
java.lang.String |
getServiceName()
Return service name.
|
int |
getStatementBatchSize()
Return batch size to be used for statement batching with this provider.
|
StorageOptions |
getStorageOptions()
Return options for database storage.
|
boolean |
getSupportsMultitenancy()
Return is this provider multi-tenant-aware? Defaults to
false . |
java.lang.String |
getThreadLocalTenant()
Return (nullable) ID of the current thread's tenant, if applicable.
|
boolean |
getTraceRequests()
Return should all requests for this SQL database service be traced? Defaults to
false . |
boolean |
getTraceWithData()
Return if
SQLDatabaseProvider.traceRequests is also true , should all requests for this SQL database be traced with data? Defaults to false . |
boolean |
getUseClientProvidedKeys()
Return should
SQLDatabaseProvider.createEntity use client-provided keys (when available), in preference to server-generated keys? Defaults to false . |
boolean |
hasMetadata()
Return has service metadata been loaded.
|
boolean |
isCacheDatabase()
Return is this database a cache (staging) database for a backend system? Defaults to
false . |
boolean |
isMetricProvider()
Return is this provider used for data metrics?
|
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 |
openSchema()
Open the database schema for this provider.
|
void |
openSchemaWithRetryLoop()
Open the database schema for this provider.
|
void |
pingServer(HttpHeaders headers,
RequestOptions options)
Ping the server.
|
void |
prepareData(com.sap.cloud.server.odata.core.Action0 work)
Execute
work within a transaction. |
void |
prepareDataForTenant(com.sap.cloud.server.odata.core.Action0 work)
Execute a transaction to prepare data for the current tenant.
|
void |
processBatch(RequestBatch batch,
HttpHeaders headers,
RequestOptions options)
Execute a request batch in the target system.
|
void |
purgeAllDeletions()
Purge any logically-deleted rows (rows that were marked as deleted for change tracking), even those whose time of deletion does not exceed the
SQLDatabaseProvider.retainDeletionsFor period. |
void |
purgeDeletionsForTenant()
Purge any logically-deleted rows for the current tenant (rows that were marked as deleted for change tracking), even those whose time of deletion does not exceed the
SQLDatabaseProvider.retainDeletionsFor period. |
void |
purgeExpiredDeletions()
Purge any logically-deleted rows (rows that were marked as deleted for change tracking) whose time of deletion exceeds the
SQLDatabaseProvider.retainDeletionsFor period. |
DataContext |
queryContext(int version)
Return a data context for parsing a data query.
|
void |
rollback()
Rollback the current transaction.
|
boolean |
schemaExists()
Return
true if the database schema artifacts (e.g. |
boolean |
schemaExistsForTenant()
Return
true if the database artifacts (e.g. |
EntityValue |
selectEntity(EntityValue entity)
Return newly loaded copy of
entity with all structural properties selected. |
java.lang.String |
serviceDocument(int format)
Return the service document, in XML or JSON format.
|
void |
setAllowNonUtcTimeZone(boolean value)
Set can the database clock be configured with a time zone other than UTC? Defaults to
false . |
void |
setAutoBindEntities(boolean value)
Set should this provider automatically bind entities in
SQLDatabaseProvider.createEntity or SQLDatabaseProvider.updateEntity , if bound entities are provided by the client. |
void |
setAutoCreateChildren(boolean value)
Set should this provider automatically create children in
SQLDatabaseProvider.createEntity ("deep insert" calls), if nested children are provided by the client. |
void |
setAutoCreateParents(boolean value)
Set should this provider automatically create parents in
SQLDatabaseProvider.createEntity ("deep insert" calls), if nested parents are provided by the client. |
void |
setAutoDeleteChildren(boolean value)
Set should this provider automatically delete children in
SQLDatabaseProvider.deleteEntity ("on delete" actions), if specified with OnDelete in the service metadata. |
void |
setAutoExpandItems(boolean value)
Set should this provider automatically expand itemns in
SQLDatabaseProvider.executeQuery , if requested in the client's query. |
void |
setAutoGenerateKeys(boolean value)
Set should this provider automatically generate primary keys? Defaults to
true . |
void |
setAutoUnbindEntities(boolean value)
Set should this provider automatically unbind entities in
SQLDatabaseProvider.createEntity or SQLDatabaseProvider.updateEntity , if unbound entities are provided by the client. |
void |
setCacheDatabase(boolean value)
Set is this database a cache (staging) database for a backend system? Defaults to
false . |
void |
setCacheOldestTransactionForSeconds(int value)
Set when determining the start time of the oldest active database transaction for change tracking queries, how long can a cached transaction time be used for? Defaults to
5 . |
void |
setCanModifySchema(boolean value)
Set is this provider permitted to modify the database schema, e.g.
|
void |
setClientExpiryInterval(DayTimeDuration value)
Set if
SQLDatabaseProvider.startClientExpiryThread is called, how often should it perform cleanup activity? Defaults to one hour. |
void |
setDebugConnections(boolean value)
Set should all connections (opening/closing) to this SQL database service be logged? Defaults to
false . |
void |
setDeltaCleanupInterval(DayTimeDuration value)
Set if
SQLDatabaseProvider.startDeltaCleanupThread is called, how often should it perform cleanup activity? Defaults to one hour. |
void |
setDownloadBeforeOldestTransaction(int value)
Set when determining the next "last download" time for delta downloads, how many seconds should it be prior to the start time of the oldest active database transaction? Defaults to
5 . |
void |
setEnableChangeTracking(boolean value)
Set should this provider be enabled for change tracking? Defaults to
false . |
void |
setEnableKeyTracking(boolean value)
Set should this provider use key tracking for determining when "delete" is required in delta responses? Defaults to
false . |
void |
setEnableRowVersioning(boolean value)
Set should this provider be enabled for row versioning? Defaults to
false . |
void |
setFlattenComplexProperties(boolean value)
Set should complex properties be flattened into separate columns for database storage? Defaults to
false . |
void |
setGenerateForeignKeyConstraints(boolean value)
Set should the provider generate
foreign key constraints when it creates database tables? Defaults to false . |
void |
setGenerateUniqueConstraints(boolean value)
Set should the provider generate
unique constraints when it creates database tables? Defaults to false . |
void |
setInitialDataLoader(com.sap.cloud.server.odata.core.Action0 loader)
Register a callback handler which will be used for loading initial data into the database.
|
void |
setLogExceptions(boolean value)
Set should all database exceptions be logged?
|
void |
setMaintainTrackingColumns(boolean value)
Set should this provider maintain delta-tracking columns? Defaults to
false . |
void |
setMaintainVersionColumns(boolean value)
Set should this provider maintain the row version column? Defaults to
false . |
void |
setMetadata(CsdlDocument value)
Set service metadata.
|
void |
setMetricProvider(boolean value)
Set is this provider used for data metrics?
|
void |
setOldestTransactionForAllDatabases(boolean value)
Set when determining the start time of the oldest active database transaction for change tracking queries, should the oldest active transaction time for all databases be used?
Defaults to
false , so that only the current database (or current schema, if applicable) is considered. |
void |
setRetainDeletionsFor(DayTimeDuration value)
Set if change tracking is enabled, how long should logically deleted rows be retained to support subsequent delta queries? Defaults to 50 days.
|
void |
setSelectAfterCreate(boolean value)
Set should entities be reselected after
SQLDatabaseProvider.createEntity (SQL insert)? Defaults to true . |
void |
setSelectAfterUpdate(boolean value)
Set should entities be reselected after
SQLDatabaseProvider.updateEntity (SQL update)? Defaults to true . |
void |
setStatementBatchSize(int value)
Set batch size to be used for statement batching with this provider.
|
void |
setSupportsMultitenancy(boolean value)
Set is this provider multi-tenant-aware? Defaults to
false . |
void |
setThreadLocalTenant(java.lang.String value)
Set ID of the current thread's tenant, if applicable.
|
void |
setTraceRequests(boolean value)
Set should all requests for this SQL database service be traced? Defaults to
false . |
void |
setTraceWithData(boolean value)
Set if
SQLDatabaseProvider.traceRequests is also true , should all requests for this SQL database be traced with data? Defaults to false . |
void |
setUseClientProvidedKeys(boolean value)
Set should
SQLDatabaseProvider.createEntity use client-provided keys (when available), in preference to server-generated keys? Defaults to false . |
void |
startClientExpiryThread(com.sap.cloud.server.odata.core.ThreadShutdown shutdown)
Start a thread which will periodically delete expired clients and related client-specific data.
|
void |
startDeltaCleanupThread(com.sap.cloud.server.odata.core.ThreadShutdown shutdown)
Start a thread which will periodically purge expired deletions.
|
DataMethod |
storedProcedure(java.lang.String name)
Return a data method for use in the execution of a database stored procedure.
|
void |
transaction(com.sap.cloud.server.odata.core.Action0 work)
Perform some work within a database transaction.
|
void |
unbindEntities(EntityValue entity)
|
void |
unbindEntities(EntityValue entity,
Property bindingProperty)
This function may be used in the implementation of entity binding calls, e.g.
|
void |
unloadMetadata()
Unload service metadata (if previously loaded).
|
void |
updateClientExpiry(EntityValue registration)
Arrange for client expiry after a client registration has been created.
|
void |
updateEntity(EntityValue entity)
|
void |
updateEntity(EntityValue entity,
HttpHeaders headers)
|
void |
updateEntity(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Update an entity in the target system.
|
java.lang.RuntimeException |
updateEntityReturningError(EntityValue entity)
|
java.lang.RuntimeException |
updateEntityReturningError(EntityValue entity,
HttpHeaders headers)
|
java.lang.RuntimeException |
updateEntityReturningError(EntityValue entity,
HttpHeaders headers,
RequestOptions options)
Call
SQLDatabaseProvider.createEntity but catch any excepion it throws (non-logged) and return it. |
void |
updateLink(EntityValue from,
Property property,
EntityValue to)
|
void |
updateLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers)
|
void |
updateLink(EntityValue from,
Property property,
EntityValue to,
HttpHeaders headers,
RequestOptions options)
Update a link from a source entity to a target entity.
|
void |
updateLinkUsingForeignKeys(EntityValue source,
Property sourceProperty,
EntityValue target)
Default implementation of 'updateLink' using foreign keys from referential constraints in service metadata.
|
void |
uploadMedia(EntityValue entity,
StreamBase content)
|
void |
uploadMedia(EntityValue entity,
StreamBase content,
HttpHeaders headers)
|
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)
|
void |
uploadStream(EntityValue entity,
StreamLink link,
StreamBase content,
HttpHeaders headers)
|
void |
uploadStream(EntityValue entity,
StreamLink link,
StreamBase content,
HttpHeaders headers,
RequestOptions options)
Upload content for a stream property to the target system.
|
SQLDatabaseProvider |
withDataSource(javax.sql.DataSource dataSource)
Initialises the JDBC data source within storageOptions.
|
public SQLDatabaseProvider(java.lang.String serviceName)
serviceName
- ServiceName parameter.public SQLDatabaseProvider(java.lang.String serviceName, java.lang.String databaseURL)
Constructs a SQL database provider.
serviceName
- Service name.databaseURL
- (nullable) Database URL.public SQLDatabaseProvider withDataSource(javax.sql.DataSource dataSource)
Initialises the JDBC data source within storageOptions.
dataSource
- JDBC data source.public void applyChanges(ChangeSet changes)
changes
- Changes parameter.public void applyChanges(ChangeSet changes, HttpHeaders headers)
changes
- Changes parameter.headers
- Headers parameter.public void applyChanges(ChangeSet changes, HttpHeaders headers, RequestOptions options)
Apply the changes from a change set to the target system.
changes
- The change set.headers
- Optional request-specific headers.options
- Optional request-specific options.public void beginTransaction()
Begin a new transaction, or begin a nested transaction if a transaction is already active for this provider in the current thread.
beginTransaction
in interface DataServiceProvider
public void bindEntities(EntityValue entity)
entity
- Entity parameter.public void bindEntities(EntityValue entity, Property bindingProperty)
entity
- Entity parameter.bindingProperty
- BindingProperty parameter.public void bindEntities(EntityValue entity, Property bindingProperty, boolean afterCreate)
entity
- Entity parameter.bindingProperty
- BindingProperty parameter.afterCreate
- AfterCreate parameter.public void bindEntities(EntityValue entity, Property bindingProperty, boolean afterCreate, boolean afterUpdate)
This function may be used in the implementation of entity binding calls, e.g. by EntityValue.bindEntity
.
It relies on the existence of appropriate referential constraints in the service metadata, or an appropriately set join entity set.
entity
- Source entity, which may contain inline bindings for the binding property.bindingProperty
- (nullable) Binding property. If null
, then all of the source's navigation properties are considered.afterCreate
- Is this call for binding after createEntity has created entity
? Defaults to false.afterUpdate
- Is this call for binding after updateEntity has updated entity
? Defaults to false.public void bindEntitiesAfterCreate(EntityValue entity)
entity
- Entity parameter.public void bindEntitiesAfterCreate(EntityValue entity, Property bindingProperty)
This function may be used in the implementation of entity binding calls after the main create action of SQLDatabaseProvider.createEntity
.
It relies on the existence of appropriate referential constraints in the service metadata.
entity
- Source entity, which may contain inline bindings for the binding property.bindingProperty
- (nullable) Binding property. If null
, then all of the source's navigation properties are considered.public void bindEntitiesAfterUpdate(EntityValue entity)
entity
- Entity parameter.public void bindEntitiesAfterUpdate(EntityValue entity, Property bindingProperty)
This function may be used in the implementation of entity binding calls after the main update action of SQLDatabaseProvider.updateEntity
.
It relies on the existence of appropriate referential constraints in the service metadata.
entity
- Source entity, which may contain inline bindings for the binding property.bindingProperty
- (nullable) Binding property. If null
, then all of the source's navigation properties are considered.public void closeAllConnections()
Close connections to this database from all threads. Note: in some environments (e.g. an application server with contained-managed connection pooling), this might not have any effect on pooled connections.
public void closeConnection()
If the current thread is connected to this database, then disconnect it.
public void commit()
Commit the current transaction. If the current transaction is a nested transaction, then decrease the nesting level.
commit
in interface DataServiceProvider
public void createChildren(EntityValue entity)
entity
- Entity parameter.public void createChildren(EntityValue entity, Property childProperty)
This function may be used in the implementation of "deep insert" calls, e.g. by SQLDatabaseProvider.createEntity
.
This function will execute "deep insert" if the parent-child entity relationship is fulfilled through join set.
entity
- Parent entity, which may contain inline children for the child property.childProperty
- (nullable) Child property. If null
, then all of the parent's navigation properties are considered.public void createClientExpiry(EntityValue registration)
Arrange for client expiry after a client registration has been created.
SQLDatabaseProvider.retainDeletionsFor
, which also determines how long inactive client registrations will be retained.
registration
- Client registration.public void createEntity(EntityValue entity)
entity
- Entity parameter.public void createEntity(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public 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.
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.
createEntity
in interface DataServiceProvider
entity
- Entity to be created.headers
- Request-specific headers.options
- Request-specific options.public java.lang.RuntimeException createEntityReturningError(EntityValue entity)
entity
- Entity parameter.public java.lang.RuntimeException createEntityReturningError(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public java.lang.RuntimeException createEntityReturningError(EntityValue entity, HttpHeaders headers, RequestOptions options)
Call SQLDatabaseProvider.createEntity
but catch any excepion it throws (non-logged) and return it.
entity
- Entity to be created.headers
- Request-specific headers.options
- Request-specific options.public void createLink(EntityValue from, Property property, EntityValue to)
from
- From parameter.property
- Property parameter.to
- To parameter.public void createLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers)
from
- From parameter.property
- Property parameter.to
- To parameter.headers
- Headers parameter.public void createLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Create a link from a source entity to a target entity.
createLink
in interface DataServiceProvider
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.public void createLinkUsingForeignKeys(EntityValue source, Property sourceProperty, EntityValue target)
Default implementation of 'createLink' using foreign keys from referential constraints in service metadata.
source
- Source entity for the link to be created.sourceProperty
- Source navigation property for the link to be created. This may be a one-to-one or one-to-many navigation property.target
- Target entity for the link to be created.public void createMedia(EntityValue entity, StreamBase content)
entity
- Entity parameter.content
- Content parameter.public void createMedia(EntityValue entity, StreamBase content, HttpHeaders headers)
entity
- Entity parameter.content
- Content parameter.headers
- Headers parameter.public 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.
createMedia
in interface DataServiceProvider
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.public void createParents(EntityValue entity)
entity
- Entity parameter.public void createParents(EntityValue entity, Property parentProperty)
This function may be used in the implementation of "deep insert" calls, e.g. by SQLDatabaseProvider.createEntity
.
This function will not execute "deep insert" if the parent-child entity relationship is fulfilled through join set.
entity
- Child entity, which may contain inline parent(s) via the parent property.parentProperty
- (nullable) Child property. If null
, then all of the parent's navigation properties are considered.public void createSchema()
Create (if non-existent) the database schema artifacts (e.g. tables) for this provider.
public void createSchemaForTenant()
Create (if non-existent) the database artifacts (e.g. rows) in this database for the current tenant.
public void createSchemaWithRetryLoop()
Create (if non-existent) the database schema artifacts (e.g. tables) for this provider. If creation fails, then retry (potentially forever) with a one minute delay between retries.
public GlobalDateTime currentLDT()
Return the current local date/time according to the database server.
public GlobalDateTime currentUTC()
Return the current global time (UTC) according to the database server.
public void deleteByQuery(DataQuery query)
query
- Query parameter.public void deleteByQuery(DataQuery query, HttpHeaders headers)
query
- Query parameter.headers
- Headers parameter.public void deleteByQuery(DataQuery query, HttpHeaders headers, RequestOptions options)
Execute query to delete data from the target system.
deleteByQuery
in interface DataServiceProvider
query
- Data query specifying the information to be deleted.headers
- Request-specific headers.options
- Request-specific options.public void deleteChildren(EntityValue entity)
entity
- Entity parameter.public void deleteChildren(EntityValue entity, Property childProperty)
This function may be used in the implementation of "on delete" actions, e.g. by SQLDatabaseProvider.deleteEntity
.
entity
- Parent entity.childProperty
- (nullable) Child property. If `null`, then all of the parent's navigation properties are considered.public void deleteEntity(EntityValue entity)
entity
- Entity parameter.public void deleteEntity(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public void deleteEntity(EntityValue entity, HttpHeaders headers, RequestOptions options)
Delete an entity from the target system.
deleteEntity
in interface DataServiceProvider
entity
- Entity to be deleted.headers
- Request-specific headers.options
- Request-specific options.public java.lang.RuntimeException deleteEntityReturningError(EntityValue entity)
entity
- Entity parameter.public java.lang.RuntimeException deleteEntityReturningError(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public java.lang.RuntimeException deleteEntityReturningError(EntityValue entity, HttpHeaders headers, RequestOptions options)
Call SQLDatabaseProvider.deleteEntity
but catch any excepion it throws (non-logged) and return it.
entity
- Entity to be deleted.headers
- Request-specific headers.options
- Request-specific options.public void deleteLink(EntityValue from, Property property, EntityValue to)
from
- From parameter.property
- Property parameter.to
- To parameter.public void deleteLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers)
from
- From parameter.property
- Property parameter.to
- To parameter.headers
- Headers parameter.public void deleteLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Delete a link from a source entity to a target entity.
deleteLink
in interface DataServiceProvider
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.public void deleteLinkUsingForeignKeys(EntityValue source, Property sourceProperty, EntityValue target)
Default implementation of 'deleteLink' using foreign keys from referential constraints in service metadata.
source
- Source entity for the link to be created.sourceProperty
- Source navigation property for the link to be created. This may be a one-to-one or one-to-many navigation property.target
- Target entity for the link to be created.public void deleteSchema()
Delete (if existing) the database schema artifacts (e.g. tables) for this provider.
public void deleteSchemaForTenant()
Delete (if existing) the database artifacts (e.g. rows) in this database for the current tenant.
public void deleteStream(EntityValue entity, StreamLink link)
entity
- Entity parameter.link
- Link parameter.public void deleteStream(EntityValue entity, StreamLink link, HttpHeaders headers)
entity
- Entity parameter.link
- Link parameter.headers
- Headers parameter.public void deleteStream(EntityValue entity, StreamLink link, HttpHeaders headers, RequestOptions options)
Delete the content of a stream property from the target system.
deleteStream
in interface DataServiceProvider
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.public ByteStream downloadMedia(EntityValue entity)
entity
- Entity parameter.public ByteStream downloadMedia(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public 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.
downloadMedia
in interface DataServiceProvider
entity
- Entity whose content is to be downloaded.headers
- Request-specific headers.options
- Request-specific options.public ByteStream downloadStream(EntityValue entity, StreamLink link)
entity
- Entity parameter.link
- Link parameter.public ByteStream downloadStream(EntityValue entity, StreamLink link, HttpHeaders headers)
entity
- Entity parameter.link
- Link parameter.headers
- Headers parameter.public 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.
downloadStream
in interface DataServiceProvider
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.public DataContext entityContext(EntitySet entitySet, StructureType derivedType, int format, int version)
Return a data context for a specified entity set, data format and data version.
entityContext
in interface DataServiceProvider
entitySet
- Entity set for entity value to be parsed or formatted.derivedType
- (nullable) Derived type for query results.format
- Data format.version
- Data version.public void executeBatch()
If the current thread's connection has batched statements, execute them now.
public DataValue executeMethod(DataMethod method, ParameterList parameters)
method
- Method parameter.parameters
- Parameters parameter.public DataValue executeMethod(DataMethod method, ParameterList parameters, HttpHeaders headers)
method
- Method parameter.parameters
- Parameters parameter.headers
- Headers parameter.public 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.
DataServiceException
or DataNetworkException
if an error occurs during action invocation.
executeMethod
in interface DataServiceProvider
method
- Data method.parameters
- Method parameters.headers
- Request-specific headers.options
- Request-specific options.public QueryResult executeQuery(DataQuery query)
query
- Query parameter.public QueryResult executeQuery(DataQuery query, HttpHeaders headers)
query
- Query parameter.headers
- Headers parameter.public QueryResult executeQuery(DataQuery query, HttpHeaders headers, RequestOptions options)
Execute a data query to get data from the target system.
executeQuery
in interface DataServiceProvider
query
- Data query specifying the information to be returned.headers
- Request-specific headers.options
- Request-specific options.public void expandItem(EntityValue entity, ExpandItem item)
Override this function to implement item expansion for this service. If not overridden, referential constraints are used to implement automatic expansion.
entity
- Entity whose item is to be expanded.item
- Item to be expanded.public void expandItems(DataQuery query, DataValue result)
If query
contains any DataQuery.expandItems
, apply them to result
.
query
- Query which may optionally contain expand items.result
- (nullable) Query result, to which item expansion may be applied (if not null
, the result should be an entity value or entity list).public CsdlDocument fetchMetadata(HttpHeaders headers, RequestOptions options)
Fetch latest service metadata and return it, but don't change the SQLDatabaseProvider.metadata
property.
fetchMetadata
in interface DataServiceProvider
headers
- Optional request-specific headers.options
- Optional request-specific options.public boolean getAllowNonUtcTimeZone()
Return can the database clock be configured with a time zone other than UTC? Defaults to false
.
false
.public boolean getAutoBindEntities()
Return should this provider automatically bind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if bound entities are provided by the client. Defaults to true
.
SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if bound entities are provided by the client. Defaults to true
.public boolean getAutoCreateChildren()
Return should this provider automatically create children in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested children are provided by the client. Defaults to true
.
SQLDatabaseProvider.createEntity
("deep insert" calls), if nested children are provided by the client. Defaults to true
.public boolean getAutoCreateParents()
Return should this provider automatically create parents in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested parents are provided by the client. Defaults to true
.
SQLDatabaseProvider.createEntity
("deep insert" calls), if nested parents are provided by the client. Defaults to true
.public boolean getAutoDeleteChildren()
Return should this provider automatically delete children in SQLDatabaseProvider.deleteEntity
("on delete" actions), if specified with OnDelete in the service metadata. Defaults to true
.
SQLDatabaseProvider.deleteEntity
("on delete" actions), if specified with OnDelete in the service metadata. Defaults to true
.public boolean getAutoExpandItems()
Return should this provider automatically expand itemns in SQLDatabaseProvider.executeQuery
, if requested in the client's query. Defaults to true
.
SQLDatabaseProvider.executeQuery
, if requested in the client's query. Defaults to true
.public boolean getAutoGenerateKeys()
Return should this provider automatically generate primary keys? Defaults to true
.
If the provider doesn't generate keys, then the client will have to provide them.
public boolean getAutoUnbindEntities()
Return should this provider automatically unbind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if unbound entities are provided by the client. Defaults to true
.
SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if unbound entities are provided by the client. Defaults to true
.public int getCacheOldestTransactionForSeconds()
Return when determining the start time of the oldest active database transaction for change tracking queries, how long can a cached transaction time be used for? Defaults to 5
.
Setting this value too high can result in clients downloading the same changes repeatedly (if the interval between client downloads is smaller than the caching interval).
Setting this value too low can result in frequent database interactions to determine the start time of the oldest active transaction.
Setting this value to zero (or negative) will disable caching of the start time of the oldest active transaction.
5
.public boolean getCanModifySchema()
Return is this provider permitted to modify the database schema, e.g. by adding required tables? Defaults to true
.
If not enabled, then schema changes will need to be managed by the database administrator.
true
.public DayTimeDuration getClientExpiryInterval()
Return if SQLDatabaseProvider.startClientExpiryThread
is called, how often should it perform cleanup activity? Defaults to one hour.
Intervals of less than one minute will be treated as one minute.
SQLDatabaseProvider.startClientExpiryThread
is called, how often should it perform cleanup activity? Defaults to one hour.public void getConnection()
If the current thread is not connected to this database, then connect it.
public DataTransaction getDataTransaction()
Return the current server transaction.
getDataTransaction
in interface DataServiceProvider
public boolean getDebugConnections()
Return should all connections (opening/closing) to this SQL database service be logged? Defaults to false
.
false
.public DayTimeDuration getDeltaCleanupInterval()
Return if SQLDatabaseProvider.startDeltaCleanupThread
is called, how often should it perform cleanup activity? Defaults to one hour.
Intervals of less than one minute will be treated as one minute.
SQLDatabaseProvider.startDeltaCleanupThread
is called, how often should it perform cleanup activity? Defaults to one hour.public int getDownloadBeforeOldestTransaction()
Return when determining the next "last download" time for delta downloads, how many seconds should it be prior to the start time of the oldest active database transaction? Defaults to 5
.
It is assumed that if the database server is clustered, the cluster nodes will be time-synchronized to within this interval.
public boolean getEnableChangeTracking()
Return should this provider be enabled for change tracking? Defaults to false
.
public boolean getEnableKeyTracking()
Return should this provider use key tracking for determining when "delete" is required in delta responses? Defaults to false
.
false
.public boolean getEnableRowVersioning()
Return should this provider be enabled for row versioning? Defaults to false
.
When row versioning is enabled, each table row contains a version number that is incremented by one for each update.
All updates apply optimistic concurrency control to check that the pre-update row version matches the version known to the client.
public boolean getFlattenComplexProperties()
Return should complex properties be flattened into separate columns for database storage? Defaults to false
.
false
.public boolean getGenerateForeignKeyConstraints()
Return should the provider generate foreign key
constraints when it creates database tables? Defaults to false
.
Foreign key constraints ensure that related rows do in fact exist.
Foreign key constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).
foreign key
constraints when it creates database tables? Defaults to false
.public boolean getGenerateUniqueConstraints()
Return should the provider generate unique
constraints when it creates database tables? Defaults to false
.
Unique constraints ensure the integrity of one-to-one relationships (i.e. that we do not have many related rows).
Unique constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).
unique
constraints when it creates database tables? Defaults to false
.public boolean getLogExceptions()
Return should all database exceptions be logged?
public boolean getMaintainTrackingColumns()
Return should this provider maintain delta-tracking columns? Defaults to false
.
Only applicable if SQLDatabaseProvider.enableChangeTracking
is true
.
By default, a database is assumed to maintain tracking columns itself (e.g. using triggers).
public boolean getMaintainVersionColumns()
Return should this provider maintain the row version column? Defaults to false
.
Only applicable if SQLDatabaseProvider.enableRowVersioning
is true
.
By default, a database is assumed to maintain the row version itself (e.g. using triggers).
public CsdlDocument getMetadata()
Return service metadata.
getMetadata
in interface DataServiceProvider
public boolean getOldestTransactionForAllDatabases()
Return when determining the start time of the oldest active database transaction for change tracking queries, should the oldest active transaction time for all databases be used?
Defaults to false
, so that only the current database (or current schema, if applicable) is considered.
public DayTimeDuration getRetainDeletionsFor()
Return if change tracking is enabled, how long should logically deleted rows be retained to support subsequent delta queries? Defaults to 50 days.
public boolean getSelectAfterCreate()
Return should entities be reselected after SQLDatabaseProvider.createEntity
(SQL insert)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.
Setting this property to false
will result in better createEntity performance, but database-generated values will not be available in the entity
parameter.
Database-generated primary keys (see SQLDatabaseProvider.autoGenerateKeys
) will still be available without setting selectAfterCreate
as they are obtained without reselecting the entity.
Note: if SQLDatabaseProvider.enableRowVersioning
is true
and SQLDatabaseProvider.maintainVersionColumns
is false
, then entities will be automatically reselected after SQLDatabaseProvider.createEntity
even if selectAfterCreate
is false
.
SQLDatabaseProvider.createEntity
(SQL insert)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.public boolean getSelectAfterUpdate()
Return should entities be reselected after SQLDatabaseProvider.updateEntity
(SQL update)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.
Setting this property to false
will result in better SQLDatabaseProvider.updateEntity
performance, but database-generated values will not be available in the entity
parameter.
Database-generated primary keys (see SQLDatabaseProvider.autoGenerateKeys
) will still be available without setting selectAfterUpdate
as they are obtained without reselecting the entity.
Note: if SQLDatabaseProvider.enableRowVersioning
is true
and SQLDatabaseProvider.maintainVersionColumns
is false
, then entities will be automatically reselected after SQLDatabaseProvider.createEntity
even if selectAfterUpdate
is false
.
SQLDatabaseProvider.updateEntity
(SQL update)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.public java.lang.String getServiceName()
Return service name.
getServiceName
in interface DataServiceProvider
public int getStatementBatchSize()
Return batch size to be used for statement batching with this provider. Defaults to 100
.
100
.public StorageOptions getStorageOptions()
Return options for database storage.
public boolean getSupportsMultitenancy()
Return is this provider multi-tenant-aware? Defaults to false
.
public java.lang.String getThreadLocalTenant()
Return (nullable) ID of the current thread's tenant, if applicable.
public boolean getTraceRequests()
Return should all requests for this SQL database service be traced? Defaults to false
.
false
.public boolean getTraceWithData()
Return if SQLDatabaseProvider.traceRequests
is also true
, should all requests for this SQL database 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.
SQLDatabaseProvider.traceRequests
is also true
, should all requests for this SQL database be traced with data? Defaults to false
.public boolean getUseClientProvidedKeys()
Return should SQLDatabaseProvider.createEntity
use client-provided keys (when available), in preference to server-generated keys? Defaults to false
.
SQLDatabaseProvider.createEntity
use client-provided keys (when available), in preference to server-generated keys? Defaults to false
.public boolean hasMetadata()
Return has service metadata been loaded.
hasMetadata
in interface DataServiceProvider
public boolean isCacheDatabase()
Return is this database a cache (staging) database for a backend system? Defaults to false
.
false
.public boolean isMetricProvider()
Return is this provider used for data metrics?
public void loadMetadata(HttpHeaders headers, RequestOptions options)
Load service metadata (if not already loaded).
loadMetadata
in interface DataServiceProvider
headers
- Optional request-specific headers.options
- Optional request-specific options.public java.lang.String metadataText(int format)
Return metadata document text of the service.
metadataText
in interface DataServiceProvider
format
- Metadata format. Only XML is presently supported.public void openSchema()
Open the database schema for this provider. Ensures that database connectivity is available and that (in principle) database operations can proceed.
public void openSchemaWithRetryLoop()
Open the database schema for this provider. Ensures that database connectivity is available and that (in principle) database operations can proceed. If opening fails, then retry (potentially forever) with a one minute delay between retries.
public void pingServer(HttpHeaders headers, RequestOptions options)
Ping the server.
pingServer
in interface DataServiceProvider
headers
- Optional request-specific headers.options
- Optional request-specific options.public void prepareData(com.sap.cloud.server.odata.core.Action0 work)
Execute work
within a transaction.
work
- Work to be executed within a transaction.public void prepareDataForTenant(com.sap.cloud.server.odata.core.Action0 work)
Execute a transaction to prepare data for the current tenant.
work
- Function to do the transaction work.public void processBatch(RequestBatch batch, HttpHeaders headers, RequestOptions options)
Execute a request batch in the target system.
processBatch
in interface DataServiceProvider
batch
- The request batch.headers
- Request-specific headers.options
- Request-specific options.public void purgeAllDeletions()
Purge any logically-deleted rows (rows that were marked as deleted for change tracking), even those whose time of deletion does not exceed the SQLDatabaseProvider.retainDeletionsFor
period.
public void purgeDeletionsForTenant()
Purge any logically-deleted rows for the current tenant (rows that were marked as deleted for change tracking), even those whose time of deletion does not exceed the SQLDatabaseProvider.retainDeletionsFor
period.
public void purgeExpiredDeletions()
Purge any logically-deleted rows (rows that were marked as deleted for change tracking) whose time of deletion exceeds the SQLDatabaseProvider.retainDeletionsFor
period.
public DataContext queryContext(int version)
Return a data context for parsing a data query.
queryContext
in interface DataServiceProvider
version
- Data version.public void rollback()
Rollback the current transaction. If the current transaction is a nested transaction, then decrease the nesting level, and mark the outermost (non-nested) transaction for eventual rollback.
rollback
in interface DataServiceProvider
public boolean schemaExists()
Return true
if the database schema artifacts (e.g. tables) exist for this provider.
true
if the database schema artifacts (e.g. tables) exist for this provider.public boolean schemaExistsForTenant()
Return true
if the database artifacts (e.g. tables) exist in this database for the current tenant?
public EntityValue selectEntity(EntityValue entity)
Return newly loaded copy of entity
with all structural properties selected.
entity
- Entity value.entity
with all structural properties selected.public java.lang.String serviceDocument(int format)
Return the service document, in XML or JSON format.
serviceDocument
in interface DataServiceProvider
format
- Data format (XML or JSON).public void setAllowNonUtcTimeZone(boolean value)
Set can the database clock be configured with a time zone other than UTC? Defaults to false
.
value
- Can the database clock be configured with a time zone other than UTC? Defaults to false
.public void setAutoBindEntities(boolean value)
Set should this provider automatically bind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if bound entities are provided by the client. Defaults to true
.
value
- Should this provider automatically bind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if bound entities are provided by the client. Defaults to true
.public void setAutoCreateChildren(boolean value)
Set should this provider automatically create children in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested children are provided by the client. Defaults to true
.
value
- Should this provider automatically create children in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested children are provided by the client. Defaults to true
.public void setAutoCreateParents(boolean value)
Set should this provider automatically create parents in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested parents are provided by the client. Defaults to true
.
value
- Should this provider automatically create parents in SQLDatabaseProvider.createEntity
("deep insert" calls), if nested parents are provided by the client. Defaults to true
.public void setAutoDeleteChildren(boolean value)
Set should this provider automatically delete children in SQLDatabaseProvider.deleteEntity
("on delete" actions), if specified with OnDelete in the service metadata. Defaults to true
.
value
- Should this provider automatically delete children in SQLDatabaseProvider.deleteEntity
("on delete" actions), if specified with OnDelete in the service metadata. Defaults to true
.public void setAutoExpandItems(boolean value)
Set should this provider automatically expand itemns in SQLDatabaseProvider.executeQuery
, if requested in the client's query. Defaults to true
.
value
- Should this provider automatically expand itemns in SQLDatabaseProvider.executeQuery
, if requested in the client's query. Defaults to true
.public void setAutoGenerateKeys(boolean value)
Set should this provider automatically generate primary keys? Defaults to true
.
If the provider doesn't generate keys, then the client will have to provide them.
value
- Should this provider automatically generate primary keys? Defaults to `true`.public void setAutoUnbindEntities(boolean value)
Set should this provider automatically unbind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if unbound entities are provided by the client. Defaults to true
.
value
- Should this provider automatically unbind entities in SQLDatabaseProvider.createEntity
or SQLDatabaseProvider.updateEntity
, if unbound entities are provided by the client. Defaults to true
.public void setCacheDatabase(boolean value)
Set is this database a cache (staging) database for a backend system? Defaults to false
.
value
- Is this database a cache (staging) database for a backend system? Defaults to false
.public void setCacheOldestTransactionForSeconds(int value)
Set when determining the start time of the oldest active database transaction for change tracking queries, how long can a cached transaction time be used for? Defaults to 5
.
Setting this value too high can result in clients downloading the same changes repeatedly (if the interval between client downloads is smaller than the caching interval).
Setting this value too low can result in frequent database interactions to determine the start time of the oldest active transaction.
Setting this value to zero (or negative) will disable caching of the start time of the oldest active transaction.
value
- When determining the start time of the oldest active database transaction for change tracking queries, how long can a cached transaction time be used for? Defaults to 5
.public void setCanModifySchema(boolean value)
Set is this provider permitted to modify the database schema, e.g. by adding required tables? Defaults to true
.
If not enabled, then schema changes will need to be managed by the database administrator.
value
- Is this provider permitted to modify the database schema, e.g. by adding required tables? Defaults to true
.public void setClientExpiryInterval(DayTimeDuration value)
Set if SQLDatabaseProvider.startClientExpiryThread
is called, how often should it perform cleanup activity? Defaults to one hour.
Intervals of less than one minute will be treated as one minute.
value
- If SQLDatabaseProvider.startClientExpiryThread
is called, how often should it perform cleanup activity? Defaults to one hour.public void setDebugConnections(boolean value)
Set should all connections (opening/closing) to this SQL database service be logged? Defaults to false
.
value
- Should all connections (opening/closing) to this SQL database service be logged? Defaults to false
.public void setDeltaCleanupInterval(DayTimeDuration value)
Set if SQLDatabaseProvider.startDeltaCleanupThread
is called, how often should it perform cleanup activity? Defaults to one hour.
Intervals of less than one minute will be treated as one minute.
value
- If SQLDatabaseProvider.startDeltaCleanupThread
is called, how often should it perform cleanup activity? Defaults to one hour.public void setDownloadBeforeOldestTransaction(int value)
Set when determining the next "last download" time for delta downloads, how many seconds should it be prior to the start time of the oldest active database transaction? Defaults to 5
.
It is assumed that if the database server is clustered, the cluster nodes will be time-synchronized to within this interval.
value
- When determining the next "last download" time for delta downloads, how many seconds should it be prior to the start time of the oldest active database transaction? Defaults to `5`.public void setEnableChangeTracking(boolean value)
Set should this provider be enabled for change tracking? Defaults to false
.
value
- Should this provider be enabled for change tracking? Defaults to `false`.public void setEnableKeyTracking(boolean value)
Set should this provider use key tracking for determining when "delete" is required in delta responses? Defaults to false
.
value
- Should this provider use key tracking for determining when "delete" is required in delta responses? Defaults to false
.public void setEnableRowVersioning(boolean value)
Set should this provider be enabled for row versioning? Defaults to false
.
When row versioning is enabled, each table row contains a version number that is incremented by one for each update.
All updates apply optimistic concurrency control to check that the pre-update row version matches the version known to the client.
value
- Should this provider be enabled for row versioning? Defaults to `false`.public void setFlattenComplexProperties(boolean value)
Set should complex properties be flattened into separate columns for database storage? Defaults to false
.
value
- Should complex properties be flattened into separate columns for database storage? Defaults to false
.public void setGenerateForeignKeyConstraints(boolean value)
Set should the provider generate foreign key
constraints when it creates database tables? Defaults to false
.
Foreign key constraints ensure that related rows do in fact exist.
Foreign key constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).
value
- Should the provider generate foreign key
constraints when it creates database tables? Defaults to false
.public void setGenerateUniqueConstraints(boolean value)
Set should the provider generate unique
constraints when it creates database tables? Defaults to false
.
Unique constraints ensure the integrity of one-to-one relationships (i.e. that we do not have many related rows).
Unique constraints should not be used for tables with inline isDeleted / lastModified columns (for change tracking).
value
- Should the provider generate unique
constraints when it creates database tables? Defaults to false
.public void setInitialDataLoader(com.sap.cloud.server.odata.core.Action0 loader)
Register a callback handler which will be used for loading initial data into the database.
loader
- Initial data Loader.public void setLogExceptions(boolean value)
Set should all database exceptions be logged?
value
- Should all database exceptions be logged?public void setMaintainTrackingColumns(boolean value)
Set should this provider maintain delta-tracking columns? Defaults to false
.
Only applicable if SQLDatabaseProvider.enableChangeTracking
is true
.
By default, a database is assumed to maintain tracking columns itself (e.g. using triggers).
value
- Should this provider maintain delta-tracking columns? Defaults to `false`.public void setMaintainVersionColumns(boolean value)
Set should this provider maintain the row version column? Defaults to false
.
Only applicable if SQLDatabaseProvider.enableRowVersioning
is true
.
By default, a database is assumed to maintain the row version itself (e.g. using triggers).
value
- Should this provider maintain the row version column? Defaults to `false`.public void setMetadata(CsdlDocument value)
Set service metadata.
setMetadata
in interface DataServiceProvider
value
- Service metadata.public void setMetricProvider(boolean value)
Set is this provider used for data metrics?
value
- Is this provider used for data metrics?public void setOldestTransactionForAllDatabases(boolean value)
Set when determining the start time of the oldest active database transaction for change tracking queries, should the oldest active transaction time for all databases be used?
Defaults to false
, so that only the current database (or current schema, if applicable) is considered.
value
- When determining the start time of the oldest active database transaction for change tracking queries, should the oldest active transaction time for all databases be used?public void setRetainDeletionsFor(DayTimeDuration value)
Set if change tracking is enabled, how long should logically deleted rows be retained to support subsequent delta queries? Defaults to 50 days.
value
- If change tracking is enabled, how long should logically deleted rows be retained to support subsequent delta queries? Defaults to 50 days.public void setSelectAfterCreate(boolean value)
Set should entities be reselected after SQLDatabaseProvider.createEntity
(SQL insert)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.
Setting this property to false
will result in better createEntity performance, but database-generated values will not be available in the entity
parameter.
Database-generated primary keys (see SQLDatabaseProvider.autoGenerateKeys
) will still be available without setting selectAfterCreate
as they are obtained without reselecting the entity.
Note: if SQLDatabaseProvider.enableRowVersioning
is true
and SQLDatabaseProvider.maintainVersionColumns
is false
, then entities will be automatically reselected after SQLDatabaseProvider.createEntity
even if selectAfterCreate
is false
.
value
- Should entities be reselected after SQLDatabaseProvider.createEntity
(SQL insert)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.public void setSelectAfterUpdate(boolean value)
Set should entities be reselected after SQLDatabaseProvider.updateEntity
(SQL update)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.
Setting this property to false
will result in better SQLDatabaseProvider.updateEntity
performance, but database-generated values will not be available in the entity
parameter.
Database-generated primary keys (see SQLDatabaseProvider.autoGenerateKeys
) will still be available without setting selectAfterUpdate
as they are obtained without reselecting the entity.
Note: if SQLDatabaseProvider.enableRowVersioning
is true
and SQLDatabaseProvider.maintainVersionColumns
is false
, then entities will be automatically reselected after SQLDatabaseProvider.createEntity
even if selectAfterUpdate
is false
.
value
- Should entities be reselected after SQLDatabaseProvider.updateEntity
(SQL update)? Defaults to true
. This ensures that database-generated column values will be available in the entity
parameter.public void setStatementBatchSize(int value)
Set batch size to be used for statement batching with this provider. Defaults to 100
.
value
- Batch size to be used for statement batching with this provider. Defaults to 100
.public void setSupportsMultitenancy(boolean value)
Set is this provider multi-tenant-aware? Defaults to false
.
value
- Is this provider multi-tenant-aware? Defaults to `false`.public void setThreadLocalTenant(java.lang.String value)
Set ID of the current thread's tenant, if applicable.
value
- ID of the current thread's tenant, if applicable.public void setTraceRequests(boolean value)
Set should all requests for this SQL database service be traced? Defaults to false
.
value
- Should all requests for this SQL database service be traced? Defaults to false
.public void setTraceWithData(boolean value)
Set if SQLDatabaseProvider.traceRequests
is also true
, should all requests for this SQL database 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.
value
- If SQLDatabaseProvider.traceRequests
is also true
, should all requests for this SQL database be traced with data? Defaults to false
.public void setUseClientProvidedKeys(boolean value)
Set should SQLDatabaseProvider.createEntity
use client-provided keys (when available), in preference to server-generated keys? Defaults to false
.
value
- Should SQLDatabaseProvider.createEntity
use client-provided keys (when available), in preference to server-generated keys? Defaults to false
.public void startClientExpiryThread(com.sap.cloud.server.odata.core.ThreadShutdown shutdown)
Start a thread which will periodically delete expired clients and related client-specific data.
shutdown
- Signal for shutting down the started thread.public void startDeltaCleanupThread(com.sap.cloud.server.odata.core.ThreadShutdown shutdown)
Start a thread which will periodically purge expired deletions.
shutdown
- Signal for shutting down the started thread.public DataMethod storedProcedure(java.lang.String name)
Return a data method for use in the execution of a database stored procedure.
name
- Stored procedure name.public void transaction(com.sap.cloud.server.odata.core.Action0 work)
Perform some work within a database transaction. If a transaction is already active, then the work will be performed within a nested transaction.
work
- Work to be executed within a transaction.public void unbindEntities(EntityValue entity)
entity
- Entity parameter.public void unbindEntities(EntityValue entity, Property bindingProperty)
This function may be used in the implementation of entity binding calls, e.g. by EntityValue.unbindEntity
.
It relies on the existence of appropriate referential constraints in the service metadata.
entity
- Source entity, which may contain inline bindings for the binding property.bindingProperty
- (nullable) Binding property. If null
, then all of the source's navigation properties are considered.public void unloadMetadata()
Unload service metadata (if previously loaded).
unloadMetadata
in interface DataServiceProvider
public void updateClientExpiry(EntityValue registration)
Arrange for client expiry after a client registration has been created.
SQLDatabaseProvider.retainDeletionsFor
, which also determines how long inactive client registrations will be retained.
registration
- Client registration.public void updateEntity(EntityValue entity)
entity
- Entity parameter.public void updateEntity(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public void updateEntity(EntityValue entity, HttpHeaders headers, RequestOptions options)
Update an entity in the target system.
updateEntity
in interface DataServiceProvider
entity
- Entity to be updated.headers
- Request-specific headers.options
- Request-specific options.public java.lang.RuntimeException updateEntityReturningError(EntityValue entity)
entity
- Entity parameter.public java.lang.RuntimeException updateEntityReturningError(EntityValue entity, HttpHeaders headers)
entity
- Entity parameter.headers
- Headers parameter.public java.lang.RuntimeException updateEntityReturningError(EntityValue entity, HttpHeaders headers, RequestOptions options)
Call SQLDatabaseProvider.createEntity
but catch any excepion it throws (non-logged) and return it.
entity
- Entity to be updated.headers
- Request-specific headers.options
- Request-specific options.public void updateLink(EntityValue from, Property property, EntityValue to)
from
- From parameter.property
- Property parameter.to
- To parameter.public void updateLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers)
from
- From parameter.property
- Property parameter.to
- To parameter.headers
- Headers parameter.public void updateLink(EntityValue from, Property property, EntityValue to, HttpHeaders headers, RequestOptions options)
Update a link from a source entity to a target entity.
updateLink
in interface DataServiceProvider
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.public void updateLinkUsingForeignKeys(EntityValue source, Property sourceProperty, EntityValue target)
Default implementation of 'updateLink' using foreign keys from referential constraints in service metadata.
source
- Source entity for the link to be created.sourceProperty
- Source navigation property for the link to be created. This may be a one-to-one or one-to-many navigation property.target
- Target entity for the link to be created.public void uploadMedia(EntityValue entity, StreamBase content)
entity
- Entity parameter.content
- Content parameter.public void uploadMedia(EntityValue entity, StreamBase content, HttpHeaders headers)
entity
- Entity parameter.content
- Content parameter.headers
- Headers parameter.public 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
.
uploadMedia
in interface DataServiceProvider
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.public void uploadStream(EntityValue entity, StreamLink link, StreamBase content)
entity
- Entity parameter.link
- Link parameter.content
- Content parameter.public void uploadStream(EntityValue entity, StreamLink link, StreamBase content, HttpHeaders headers)
entity
- Entity parameter.link
- Link parameter.content
- Content parameter.headers
- Headers parameter.public 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.
uploadStream
in interface DataServiceProvider
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.