Documentation

Class: ClarityTransactionDispatcher

ClarityTransactionDispatcher

Class that organizes systems to respond to data transactions. The dispatcher manages the life-cycle of data entities. They can be added, updated, and removed. The dispatcher is not responsible for anything beyond this. It will notify the systems when any entity has been added, updated, and removed. This allows the dispatcher to remain unopinionated about tasks to run when a certain entity is added, updated, or removed.

The idea behind the dispatcher is to handle the complexity of the IoT. There are many systems, devices, and other technologies that need to communicate for a company to run smoothly. We believe that the answer to these needs is a data dispatcher which lets all independent systems know about data changes.

new ClarityTransactionDispatcher()

Create a Dispatcher.

Methods

addEntityAsync(entity)

Add an Entity to the datastore. The steps the dispatcher takes when saving an entity are.

  • Validate the entity with all systems. All systems have to validate to pass.
  • Save the entity to the datastore.
  • Notify the systems that an entity has been added.
Parameters:
Name Type Description
entity IEntity

The entity that you want to save to the datastore.
Returns:
Type
Promise.<Entity>

addServiceAsync(name, service)

Add a service for systems to use. Services could be HTTP services, or governance that needs to be shared acrossed systems.

Parameters:
Name Type Description
name string

The name by which the systems will request the service.
service object

The service.
Returns:
Type
Promise.<undefined>

addSystemAsync(system)

Add a system to the dispatcher. The systems are really where the work is done. They listen to the life-cycle of the entity and react based on the composition of components. The dispatcher does the following when adding a system.

  • Adds the system.
  • Invokes initializeAsync if the system hasn't been initialized before.
  • Invokes activatedAsync after initializeAsync is finished.

Required System Methods

  • getGuid()
  • getName()

Optional System Methods

  • activatedAsync(clarityTransactionDispatcher: ClarityTransactionDispatcher)
  • approveEntityRemovalAsync(entity: IEntity)
  • deactivatedAsync()
  • disposedAsync()
  • entityAddedAsync(entity: IEntity)
  • entityRemovedAsync(entity: IEntity)
  • entityRetrievedAsync(entity: IEntity)
  • entityUpdatedAsync(oldEntity: IEntity, updatedEntity: IEntity)
  • logError(error: { type?: string; message?: string; })
  • logMessage(message: { type?: string; message?: string; })
  • logWarning(warning: { type?: string; message?: string; })
  • initializeAsync(clarityTransactionDispatcher: ClarityTransactionDispatcher)
  • serviceRemovedAsync(name: string)
  • validateEntityAsync(entity: IEntity)
Parameters:
Name Type Description
system ISystem

The system to add.
Returns:
  • An undefined Promise.
Type
Promise

approveEntityRemovalAsync(entity)

Approves whether an entity can be removed. Systems can deny the ability to remove entities.

Parameters:
Name Type Description
entity object

The entity to be removed.

deactivateSystemAsync(system)

Deactivates a system and removes it from the systems being notified. To activate again use addSystemAsync. Think of this like a pause. The dispatcher calls deactivatedAsync on the system being removed.

Parameters:
Name Type Description
system ISystem

The system to be deactivate.
Returns:
  • Resolves when the system is deactivated.
Type
Promise.<undefined>

disposeSystemAsync(system)

Disposes a system and removes it from the systems being notified. Use when removing systems for good. This allows the system to clean up after itself if needed. The dispatcher calls disposeAsync on the system being removed.

Parameters:
Name Type Description
system ISystem

The system to be disposed.
Returns:
  • Resolves when the system is disposed.
Type
Promise.<undefined>

getEntitiesAsync(config)

Page through entities using the lastId from a previous query. Use null or undefined to begin at the beginning.

Parameters:
Name Type Description
config

The configuration of the query. It takes a lastId, pageSize, lastModifiedDate, and a lastCreatedDate.

getEntityByIdAsync(entityId)

Get an entity by its id.

Parameters:
Name Type Description
entityId string

The id of the desired entity.
Returns:
  • A Promise resolved with the entity or null.
Type
Promise.<Entity>

getEntityCountAsync()

Get count for all entities in collection.

getService(name)

Get a service by the name given.

Parameters:
Name Type Description
name string

The name of the desired service.
Returns:
  • Null or the desired service.
Type
object

getSystems()

Get all systems.

Returns:
Type
Array.<ISystems>

logError(error)

Notifies the systems about an error.

Parameters:
Name Type Description
error object

The error to be sent to the systems.
Returns:
Type
undefined

logMessage(message)

Notifies the systems about a message.

Parameters:
Name Type Description
message object

The message to be sent to the systems.
Returns:
Type
undefined

logWarning(warning)

Notifies the systems about a warning.

Parameters:
Name Type Description
warning object

The warning to be sent to the systems.
Returns:
Type
undefined

removeEntityAsync(entity)

Removes the entity to be removed and notifies the systems the entity has been removed.

Parameters:
Name Type Description
entity IEntity

The entity to be removed.
Returns:
Type
Promise.<undefined>

removeServiceAsync(name)

Removes a service by its name. The dispatcher will notify the systems that this service is being removed.

Parameters:
Name Type Description
name string

The name of the service to be removed.
Returns:
Type
undefined

updateEntityAsync(entity)

Update an entity. The dispatcher will perform the following actions when updating.

  • Validate the entity. All interested systems need to validate to pass.
  • Entity's updates are saved.
  • The systems are notified about the update.
Parameters:
Name Type Description
entity object

The updated entity.
Returns:
  • Resolves when the entity is saved.
Type
Promise.<undefined>

validateEntityAsync()

This allows systems to validate the entity being saved.

validateSystem(system)

Ensures the system has the required methods.

Parameters:
Name Type Description
system ISystem

The System to be validated.