Class: DBOFactory

x2node-dbos~ DBOFactory

Database operations (DBO) factory.

new DBOFactory(dbDriver, recordTypes)

Note: The constructor is not accessible from the client code. Instances are created using module's createDBOFactory() function.
Parameters:
Name Type Description
dbDriver module:x2node-dbos.DBDriver Database driver to use.
recordTypes module:x2node-records~RecordTypesLibrary Record types library to build DBOs against.

Members


<readonly> dbDriver :module:x2node-dbos.DBDriver

The database driver.
Type:

<readonly> recordCollectionsMonitor :module:x2node-dbos.RecordCollectionsMonitor

Record collections monitor assigned to the factory.
Type:

<readonly> recordTypes :module:x2node-records~RecordTypesLibrary

Record types library associated with the factory.
Type:

Methods


adaptDataSource(source)

Create standardized data source object for the database driver associated with the DBO factory.
Parameters:
Name Type Description
source * Driver-specific data source object.
Returns:
The data source.
Type
module:x2node-dbos.DataSource

buildDelete(recordTypeName [, filter])

Build a database delete operarion, which deletes records with DELETE statements. Once built, the DBO can be executed multiple times with different filter parameters.
Parameters:
Name Type Argument Description
recordTypeName string Name of the record type to delete.
filter Array.<Array> <optional>
The filter specification. If unspecified, all records of the type are deleted.
Throws:
If record type is unknown or provided filter specification is invalid.
Type
module:x2node-common.X2UsageError
Returns:
The DBO object.
Type
module:x2node-dbos~DeleteDBO

buildFetch(recordTypeName [, querySpec])

Build a database fetch operation, which queries the database with SELECT statements and returns the results. Once built, the DBO can be executed multiple times with different filter parameters.
Parameters:
Name Type Argument Description
recordTypeName string Name of the top record type to fetch.
querySpec Object <optional>
Query specification. If unspecified (same as an empty object), all records are fetched with all properties that are fetched by default and the records are returned in no particular order.
Properties
Name Type Argument Description
props Array.<string> <optional>
Record properties to include. If unspecified, all properties that are fetched by default are included (equivalent to ['*']). Note, that record id property is always included. To include super-properties, the super-property name is included among the patterns starting with a dot. Records are not fetched if only super-properties are provided. To include records as well, a "*" can be added.
filter Array.<Array> <optional>
The filter specification. If unspecified, all records are included.
order Array.<string> <optional>
The records order specification. If unspecified, the records are returned in no particular order.
range Array.<number> <optional>
The range specification, which is a two-element array where the first element is the first record index starting from zero and the second element is the maximum number of records to return. If the range is not specified, all matching records are returned.
lock string <optional>
Either "shared" or "exclusive". If "shared", all involved records will become protected against modification until the end of the transaction. If "exclusive", the matched records of the record type being fetched are protected from reading by other transactions until this transaction completes. Any participating records of referred record types get locked in "shared" more and are protected against modification until the end of the transaction. If lock is not specified, the DBO does not make any effort to lock the records.
Throws:
Returns:
The DBO object.
Type
module:x2node-dbos~FetchDBO

buildInsert(recordTypeName, record)

Build a database insert operation, which creates new records with INSERT statements.
Parameters:
Name Type Description
recordTypeName string Name of the record type to insert.
record Object Record template to insert.
Throws:
If the provided record data is invalid or the record type is unknown.
Type
module:x2node-common.X2UsageError
Returns:
The DBO object.
Type
module:x2node-dbos~InsertDBO

buildUpdate(recordTypeName, patch [, filterOrFetcher])

Build a database update operarion, which updates records with UPDATE (and potentially INSERT and DELETE for collection properties) statements. Once built, the DBO can be executed multiple times with different filter parameters.

Note: The DBO is not intended for bulk updates that include large numbers of records. It loads and locks all matching records (only the properties it needs) into memory and then updates each record one by one all within the same transaction. The most common use-case for the DBO is to update a single record matched by its id.

Also note how the "test" patch operation is handled: When a "test" operation fails for a record, no changes for that record are made in the database. This does not affect other records in the matched set, neither it affects the transaction. Whether there were any records that were not patched because of a failed "test" operation is reported back in the operation result object (see the testFailed flag and failedRecordIds array).

Parameters:
Name Type Argument Description
recordTypeName string Name of the record type to update.
patch module:x2node-patches~RecordPatch | Array The patch. If array, assumed to be a RFC 6902 JSON Patch specification.
filterOrFetcher Array.<Array> | module:x2node-dbos~UpdateDBO~recordsFetcher <optional>
Either, filter specification or function that provides the DBO with records, on which to perform the update. If fetcher function is provided, the DBO will not* perform the initial fetch and lock for the records. If neither filter nor fetcher function is specified, all records of the type are fetched, locked and updated (should be exceptionally rare case).
Throws:
Returns:
The DBO object.
Type
module:x2node-dbos~UpdateDBO

createTxFactory(ds)

Create transaction factory compatible with the DBOs built by this DBO factory and using the provided database connections source.
Parameters:
Name Type Description
ds module:x2node-dbos.DataSource The data source (see adaptDataSource()).
Returns:
Transactions factory.
Type
module:x2node-dbos~TxFactory

newTransaction(connection)

Get new transaction handler. The transaction has not been started.
Parameters:
Name Type Description
connection * The database connection compatible with the database driver.
Deprecated:
  • Use [createTxFactory()]{module:x2node-dbos~DBOFactory#createTxFactory} instead.
Returns:
The transaction handler.
Type
module:x2node-dbos~Transaction

setRecordCollectionsMonitor(monitor)

Assign record collections monitor to the factory. Every DBO created by the factory will report record collection updates to this monitor.
Parameters:
Name Type Description
monitor module:x2node-dbos.RecordCollectionsMonitor The monitor.
Returns:
This factory.
Type
module:x2node-dbos~DBOFactory