Transaction

Transactions are the unique way to apply a list of operations to the datacloud. A transaction can be merged into another transaction so that both are executed as a single set of operations.

All the operations for a transaction are executed atomically. Either all operations succeed, or none is applied.

There are 5 types of basic operations :

• Create instance: create a node in the database with specified properties.
• Update instance property: update an existing node in the database.
• Delete instance: delete a node from the database. Delete only works if all the relations are removed too. Cascade delete can be activated.
• Create relation: create a relation of a specific type between 2 existing node.
• Delete relation: remove the specified relation between 2 specified nodes.

In most cases, we apply the Transactions operations using the “execute()” method. The transaction size is limited but in real-time. It notifies observers of the data in real-time.

Larger transactions with big set of operations (batch updates) must be executed using “executeAsLarge()” method. However, no notification will be generated.

Callbacks can be registered on transaction using “afterExecution()” method. They are executed once the transaction is applied.

Example of transaction:

const tx = new Transaction(true);
const myNewInstanceTag = tx.create(<myModelTag>);
tx.update(myNewInstanceTag, <myPropertyTag>, <myPropertyValue>)
  .execute()
  .then(() => {
     // success tx case
  })
  .catch((err) => {
     // error during tx case
  })

Concurrency transactions do not guarantee their execution order.

Index

Constructors

• constructor

Methods

• afterExecution
• create
• createRelation
• delete
• deleteAllRelations
• deleteRelation
• execute
• executeAsLarge
• getId
• merge
• model
• multiUpdate
• persist
• persistInstance
• setSource
• update
• from
• process

Constructors

constructor

• new Transaction(persist?: boolean): Transaction

• Create a new transaction object.

  ---

  Parameters

  • optionalpersist: boolean

    if set to true, will persist to the data source the objects Transaction.create created in that transaction. (Default = true)

  Returns Transaction

Methods

afterExecution

• afterExecution(callback: (success: boolean, message?: string) => void): Transaction

• Set a callback to be executed after all the operations in the transaction were executed successfully

  ---

  Parameters

  • callback: (success: boolean, message?: string) => void

    the callback to be executed

  Returns Transaction

  this transaction

create

• create(model: InstanceOrTag, properties?: Map<InstanceOrTag, any>, source?: string, tag?: string): string

• Create a new instance.

  A custom map can specify property values for the instance.

  A source can be the orchestrator ({PredefinedDataSource.SERVER}), local ({PredefinedDataSource.SELF}) or an external data source (tag of DBConnector). The source is where the object is persisted and its true value outside local scopes.

  ---

  Parameters

  • model: InstanceOrTag

    tag of the model of the instance to be created

  • optionalproperties: Map<InstanceOrTag, any>

    custom map from tag to their value for properties of the instance to be created

  • optionalsource: string

    optional source of the instance

  • optionaltag: string

    optional tag of the instance to be created and must be unique

  Returns string

  the tag of the instance to be created

createRelation

• createRelation(relation: InstanceOrTag, from: InstanceOrTag, to: InstanceOrTag): Transaction

• Create relation between two instances

  ---

  Parameters

  • relation: InstanceOrTag

    tag of the relation to be created

  • from: InstanceOrTag

    tag of the ORIGIN instance of the relation

  • to: InstanceOrTag

    tag ofo the DESTINATION instance of the relation

  Returns Transaction

  this transaction with the create relation operation registered

delete

• delete(instance: InstanceOrTag): Transaction

• Delete an instance

  ---

  Parameters

  • instance: InstanceOrTag

    tag of the instance to be deleted

  Returns Transaction

  this transaction

deleteAllRelations

• deleteAllRelations(relation: Relation<any, any>, origin: InstanceOrTag): Transaction

• Delete any number of the relation starting from specified node.

  The specified node might be the origin or (exclusive) the destination of the relation.

  For the relations :

  - a - [rel1] -> b,
  - c - [inverseRel(rel1)] -> a,
  - a - [rel1] -> d,
  - a - [rel2] -> d

  tx.deleteAllRelation(rel1, a) will remove the first and third relations

  ---

  Parameters

  • relation: Relation<any, any>

    deleted relation, indicates relation tag and direction

  • origin: InstanceOrTag

    starting node

  Returns Transaction

deleteRelation

• deleteRelation(relation: InstanceOrTag, from: InstanceOrTag, to: InstanceOrTag): Transaction

• Delete a relation between two specified instances.

  The relation is only deleted for the relation parameter direction.

  ---

  Parameters

  • relation: InstanceOrTag

    tag of the relation to be deleted

  • from: InstanceOrTag

    origin instance tag

  • to: InstanceOrTag

    destination instance tag

  Returns Transaction

  this transaction

execute

• execute(): Promise<TransactionResult>

• Execute atomically the transaction at the data sources. Return the transaction result if succeeds.

  ---

  Returns Promise<TransactionResult>

  promise resolving with the corresponding TransactionResult if the transaction succeeds, rejecting if the transaction fails

executeAsLarge

• executeAsLarge(): Promise<TransactionResult>

• Execute atomically a transaction at the data source and returns the transaction result if succeeds. The large mode sends the transaction over HTTP, this has the following incidence:

  • Quicker processing of transaction
  • Allows transactions with no limit of size
  • Cannot be used when logged as Guest

  ---

  Returns Promise<TransactionResult>

  promise resolving with the corresponding TransactionResult if the transaction succeeds, rejecting if the transaction fails.

getId

• getId(): string

• Get the transaction id attached to this transaction

  ---

  Returns string

  this transaction id

merge

• merge(otherTransaction: Transaction): Transaction

• Add all operations of another transaction into this transaction

  ---

  Parameters

  • otherTransaction: Transaction

    the other transaction to add operations from

  Returns Transaction

  this transaction

model

• model(tag: InstanceOrTag): string

• Retrieve the tag of the model of the instance tag from the created instances in this transaction or from the local database.

  ---

  Parameters

  • tag: InstanceOrTag

    the instance to find the model of

  Returns string

  the tag of the model of the given instance

multiUpdate

• multiUpdate(instance: InstanceOrTag, properties: Map<InstanceOrTag, any>): Transaction

• Update multiple properties of a single instance

  ---

  Parameters

  • instance: InstanceOrTag

    tag of the instance to be updated

  • properties: Map<InstanceOrTag, any>

    map of properties to update

  Returns Transaction

  this transaction

persist

• persist(instance: InstanceOrTag, persist?: boolean): Transaction

• Set the specified instance to be persisted or not in this transaction. Default value of persist is true.

  ---

  Parameters

  • instance: InstanceOrTag

    the instance to be persisted

  • optionalpersist: boolean

    determine if the specified instance should be persisted or not (true by default).

  Returns Transaction

  this transaction

persistInstance

• persistInstance(instance: InstanceOrTag, persist?: boolean): Transaction

• Change the persistence mode for a single instance in this transaction

  @deprecated

  use Transaction.persist instead

  ---

  Parameters

  • instance: InstanceOrTag

    the instance to be persisted

  • optionalpersist: boolean

    the persisting mode

  Returns Transaction

  this transaction

setSource

• setSource(source: string): Transaction

• Change the source of all instances created in this transaction

  source can be specified as :

  1. a predefined source type {PredefinedDataSource}
  2. an external data source (Tag of a DBConnector)

  The source of a data object is where the object is persisted.

  By default, the source is the default source configured in the project.

  ---

  Parameters

  • source: string

    the new source for instances

  Returns Transaction

  this transaction

update

• update<T>(instance: InstanceOrTag, property?: Property<T>, value?: T): Transaction

• Update the property of an instance

  ---

  Type parameters

  • T

  Parameters

  • instance: InstanceOrTag

    tag of the instance to be updated

  • optionalproperty: Property<T>

    the property to be updated

  • optionalvalue: T

    the value of the property to be updated to

  Returns Transaction

  this transaction

staticfrom

• from($: BrickContext): Transaction

• Start a transaction using an existing transaction in the provided context or a new one if there is none.

  ---

  Parameters

  • $: BrickContext

    context in which the transaction executes

  Returns Transaction

  transaction

staticprocess

• process($: BrickContext, transaction: Transaction): Promise<boolean>

• Execute a given transaction if there is no open transaction in the context.

  ---

  Parameters

  • $: BrickContext

    context

  • transaction: Transaction

    transaction to process

  Returns Promise<boolean>

  boolean indicating if the argument transaction has been processed