2.3.2

Learn the Basics

Data model

The data model is described in the Adsum REST API documentation

Repositories

The repositories are responsible for storing entities, each repository being responsible for one entity class.

You can retrieve the repositories associated to the entityManager by doing

const repositories = entityManager.getRepositories();

If you need to get a specific repository, you can get it by name

const categoryRepository = entityManager.getRepository('Category');

Here is the list of all repositories

  • CategoryRepository named Category responsible for Category entities
  • CustomObjectRepository named CustomObject responsible for CustomObject entities and all sub-classes
  • DeviceRepository named Device responsible for Device entities and all sub-classes
  • FeatureRepository named Feature responsible for Feature entities
  • FeatureValueRepository named FeatureValue responsible for FeatureValue entities
  • FileRepository named File responsible for File entities
  • FloorCalibrationRepository named FloorCalibration responsible for FloorCalibration entities
  • MapFileRepository named MapFile responsible for MapFile entities and all sub-classes
  • MediaRepository named Media responsible for Media entities and all sub-classes
  • PlaceRepository named Place responsible for Place entities
  • PlaylistRepository named Playlist responsible for Playlist entities
  • PoiRepository named Poi responsible for Poi entities and all sub-classes
  • SiteRepository named Site responsible for Site entities
  • SiteCalibrationRepository named SiteCalibration responsible for SiteCalibration entities
  • TagRepository named Tag responsible for Tag entities

Load

You can load the data by doing

entityManager.load().then(
  () => {
    console.log('Data is loaded');
  },
  (error) => {
    console.error('Log failed', error);
  }
)

If you want to load a subset of the data, you can also load some repositories

Promise.all([
  entityManager.getRepository('Category').load(),
  entityManager.getRepository('Poi').load(),
]).then(
    () => {
      console.log('Data is loaded');
    },
    (error) => {
      console.error('Log failed', error);
    }
  )

Retrieve entities

You can get all the entities of a repository by doing

const entities = repository.getAll();

You can get one specific entity by id (if not found, it will return null)

const entity = repository.get(42);

You can get a list of entities (if an id is not found, it will be null in the returned array)

const entities = repository.getList([42, 44, 100]);

The SiteRepository get an additional method called getCurrent which will returns the site

const site = entityManager.getRepository('Site').getCurrent();

Associations

In order to allow independent loading of the repositories, i.e. being able to load subset of the data.

As a consequence, the relations are managed using a Reference to the associated entity.

We add 3 structures for relations:

  • Reference: It is basically a representation of an entity. Internally it just knows the entity's id and the repository that it belongs to.
  • Collection: It is an array like Reference
  • OrderedCollection: It is similar to the Collection excepted that all entities are ordered using a position attribute.

Reference

A reference is just an object containing information to be able to identify uniquely a target entity.

Reference has two properties:

  • value (int|symbol|null): This represents the target entity id, which can be either an integer or a symbol (please read the ...). When the value is null this is simply represents a null reference.
  • classOf (string): This contains the type of the target entity, i.e. the corresponding repository name.

Reference Usage

The Repositories are aware of the Reference, you can safely use them as a parameter to get & getList

We know that Category is associated to 0..1 File.

// Get the logo from the FileRepository
// logo will be an instance of File or null if the reference is a null reference.
const logo = em.getRepository("File").get(category.logo);

// You can also use them as a list
const logos = em.getRepository('File').getList([category1.logo, category2.logo]);

Using references is safer than using the id, because the repository will throw an error if it's used on the wrong repository

// Will throw TypeError('Expected a Reference<Category> but got Reference<File>')
em.getRepository('Category').get(category.logo);

You can also use the Reference#classOf property to retrieve the matching repository

em.getRepository(category.logo.classOf).get(category.logo);

Reference Comparison

As references are objects, you cannot do

// Invalid
const areEquals = logo === category.logo;

You can use the Reference#is method to compare references

// category1.logo is a reference to the logo 42
const category1 = entityManager.getRepository('Category').get(1);
const category2 = entityManager.getRepository('Category').get(2);

const logo42 = entityManager.getRepository('File').get(42);
const logo100 = entityManager.getRepository('File').get(100);

console.log(category1.logo.is(logo42)); // True
console.log(category1.logo.is(logo42.id)); // True

console.log(category1.logo.is(null)); // False

console.log(category1.logo.is(logo100)); // False
console.log(category1.logo.is(logo100.id)); // False
console.log(category1.logo.is(category2.logo)); // False

Collection

A collection is just an object containing information to be able to uniquely identify a list of target entities. It's basically a Set of Reference.

Collection has two properties:

  • values (Set): This is simply a Set of Reference
  • classOf (string): This contains the type of the target entity, i.e. the corresponding repository name.

Important: None of the references will be null as there is no point to add a null reference in the Collection. A Collection with no reference will just be empty.

Collection Usage

The Repositories are aware of the Collection, you can safely use them as a parameter to getList

We know that Category is associated to 0..N Poi.

// Get the pois from the PoiRepository
const pois = em.getRepository("Poi").getList(category.pois);

Using collection if safer than using a list of ids, because the repository will throw an error if it's used on the wrong repository

// Will throw TypeError('Expected a Reference<Category> but got Reference<Poi>')
em.getRepository('Category').getList(category.pois);

You can also use the Collection#classOf property to retrieve the matching repository

em.getRepository(category.pois.classOf).getList(category.pois);

You can access the reference by index using Collection#at method and get the size of the collection using Collection#size property.

Note that Collection#size is a getter, so it highly recommended to prevent calling this in a loop

const pois = [];
const size = category.pois.size;
for(let i=0; i< size; i++) {
  const poiReference = category.pois.at(i);
  pois.push(em.getRepository("Poi").get(poiReference));
}

You can also use the Collection#forEach method to loop through all the references

const pois = [];
category.pois.forEach((poiReference) => {
  pois.push(em.getRepository("Poi").get(poiReference));
});

Collection also implement the iteration protocol

const pois = [];
for(const poiReference of category.pois) {
  pois.push(em.getRepository("Poi").get(poiReference));
}

If you want to find the index of an reference you can use Collection#indexOf

// If not found index will be equals to -1
const index = category.pois.indexOf(42);

const poi = category.pois.at(index);

Collection Comparison

You can use the Collection#has method to check if an element is included in the Collection. This will use behind the scene the Reference#is method.

// category1.pois is a collection of pois 42, 43, 44
const category1 = entityManager.getRepository('Category').get(1);
const category2 = entityManager.getRepository('Category').get(2);

const poi42 = entityManager.getRepository('Poi').get(42);
const poi100 = entityManager.getRepository('Poi').get(100);

console.log(category1.pois.has(poi42)); // True
console.log(category1.pois.has(43)); // True

console.log(category1.pois.has(null)); // False and WILL ALWAYS BE !

console.log(category1.pois.has(poi100)); // False
console.log(category1.pois.has(poi100.id)); // False
console.log(category1.pois.has(category2.pois.at(0))); // False

OrderedCollection

An ordered collection is just an object containing information to be able to identify uniquely an ordered list of target entities. This is basically an array of Reference (Set doesn't have order).

Collection has two properties:

  • values (Array): This is simply an Array of Reference ordered
  • classOf (string): This contains the type of the target entity, i.e. the corresponding repository name.

Important: None of the references will be null as there is no point to add a null reference in the OrderedCollection. A OrderedCollection with no reference will just be empty.

OrderedCollection Usage

The usage is very similar to Collection Usage

OrderedCollection Comparison

The comparison is very similar to Collection Comparison

← PreviousNext →