Assets, Entities and Inventories Pub

Support for entities and inventories

The diesel domain modelling supports modelling of entities and their relationships. Entities (or assets) have a default JSON representation, they belong to a class and have a key and are persisted and managed by an inventory or domain plugin. These inventories can be defined in a few ways:

• built-in diesel inventories, like diesel.db.inmem
• rules based - the most common, where you define a set of rules that implement your inventory, for example diesel.db.elk which resolves down to HTTP calls
• code based - some inventories require specific code and you develop them to the scala API and are embedded in the server (when hosted in your docker), for example diesel.db.postgres

You can define classes part of Domain Modelling and bind them to inventories. After that, you can simply use these as entities in flows with CRUD messages, browse them with the built-in diesel browsers etc

Client messages when using the entity support:

• diesel.inv.register use this to register a new inventory to manage some classes
• diesel.inv.connect create a new connection for an inventory. If you don't need to manage multiple connections per inventory, leave empty "" or use "default" as the connection name.
• diesel.inv.testConnection just to test a given connection

Entity CRUD:

• diesel.inv.listAll to list all entities of a class
• diesel.inv.query to query entities of a class
• diesel.inv.findByRef to find an entity by reference/key
• diesel.inv.find to find a specifi entity
• diesel.inv.upsert to create or update an entity
• diesel.inv.upsert.bulk to create or update a batch of entities (more efficient with some implementations)
• diesel.inv.delete to delete a specific entity

Example (see more in diesel-inv-story):

$send diesel.inv.upsert (class="TestClass1", entity=tc1)
$send diesel.inv.find   (class="TestClass1", key="1234")
$send diesel.inv.delete (class="TestClass1", key="1234")

also with type-aware objects:

$send diesel.inv.upsert (entity = new Student {name: "Joe"} )

or:

$val x = students map x => diesel.inv.upsert (entity = x as Student) // the type of array is lost atm, known issue

If the class can be inferred, it can be left out when calling diesel.inv.upsert (for instance the entity knows it's class - see creating new Student above).

The query and listAll return a structure with two fields:

• total number of results
• data - an array of results

Registration and connection

To use inventories, you need to make sure we know which classes are going to which inventory and that inventory uses which connection (in case there's multiple connections).

A connection is how an inventory connects to a specific database or storage system / API etc. Each inventory is responsible for managing its connections.

The first step is to connect an inventory you created or one built (other than the built-in inventories):

$send diesel.inv.connect(inventory="diesel", connection="default")

After that, you can register in many places all the classes you want to use that inventory:

$send diesel.inv.register(inventory="diesel", classes="TestClass1")

or by annotating the class:

$anno (inventory = "diesel")
$class TestClass1 ()

These are normally done in the Environment settings, which are executed when loading your app. The sequence should be:

1. connect an inventory
2. register classes to it

Multiple environments

You can only have one connection per inventory per env. See about multiple environment support in Environment settings.

$send diesel.inv.connect(inventory="diesel", connection="default", env="local")

The way this normally works is that when connecting, a connection will require connection information. This information is configured per environment, in Environment settings before the connection is created, with the diesel.setEnv message.

Rules based inventories

See the rules-based inventory implementations in diesel-inv-spec for examples of implementing rules-based inventories.

For instance, you will implement a rule like diesel.inv.impl.upsert where the inventoriy matvhes the one you're implementing:

$when diesel.inv.impl.upsert(inventory == "my.inventory", className, table, key, assetRef, entity)
=> (k = key || assetRef.key)
=> (e=entity + {"assetRef":assetRef})
=> ... implement the creation in storage
=> (payload=entity)

You can use these to extend and implement your own repositories.

Supported inventories

These are built-in.

• No connection required:
  • diesel.db.inmem - in memory, per user
  • diesel.db.memshared - in memory, per app
  • diesel.db.col - persisted in the built-in MongoDB, available for paid accounts, depending on volumes
• Connection required:
  • diesel.db.postgres - persisted in a Postgres DB that you need to provide
  • diesel.db.elk - persisted in an Elastic DB that you need to provide

You need to log in to post a comment!