JavaScript-Bibliothek common-MetaDb

Diese Bibliothek bietet Funktionen zum Schreiben / Lesen von Werten aus / in die MetaDB.

Verwendung

---

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let metadb = require('common/metadb');

Funktionen

---

read

Liest einen Bereich (Gruppe, Bundle oder Entry) aus der MetaDB aus.

• Das System gibt die Bereiche rekursiv mit allen Bundles und Entrys aus. 
• Ein Slash (/) am Ende des Pfads spielt keine Rolle.
• Das System kann den Pfad sowohl mit als auch ohne Gruppenname lesen.
• Sie erhalten als Ergebnis eine JSON-Struktur mit dem unveränderten Aufbau der Struktur.

Pfad zeig auf …	Beschreibung
Entry	Rückgabe ist immer ein Array mit Werten.
Bundle	Rückgabe sind alle Bundles und Entrys, die darin enthalten sind, in Form einer Map. Ist der value ein Entry: key: [ Array von values ] Ist der value ein Bundle: key: { bundle:{...} }
Gruppe	Rückgabe ist wie bei Bundle (Bundles und Entries gemischt). Wenn der Pfad nicht existiert oder der Entry leer ist, liefert das System ein leeres Objekt. Das System liefert die Daten „roh“, so wie sie in der MetaDB gespeichert sind.

Beispiel

Aufbau der MetaDB

MAIN_MODULE_MANAGEMENT/aguila/[ Gruppe1 ]/[ Gruppe2 ]/test_bundle:

• Bundle: test_bundle2
  • Entry: entry-B1
  • Entry: entry-B2
• Entry: entry-A1

Aufruf

metadb.read( 'MAIN_MODULE_MANAGEMENT/aguila/[ Gruppe1 ]/[ Gruppe2 ]/ test_bundle/test_bundle2');

metadb.read('MAIN_MODULE_MANAGEMENT/aguila/[ Gruppe1 ]/test_bundle');

metadb.read('MAIN_MODULE_MANAGEMENT/aguila/test_bundle/');

 

Ergebnis für alle Aufrufe

{
  "test_bundle2" : {
    "entry-B1" : [ "content-B1" ],
    "entry-B2" : [ "content-B2" ]
  },
  "entry-A1" : [ "test_content_string3" ]
}

write

Übergibt einen Pfad in der MetaDB und einen zu erzeugenden Wert.

• Falls der Pfad bisher nicht vorhanden ist, erstellt das System ihn und legt den Entry an.
• Wenn der Entry bereits vorhanden ist, aktualisiert das System ihn mit dem neuen Wert.
• Rückgabewerte existieren nicht. Im Fehlerfall wirft das Systemeine Exception mit ausführlicher Beschreibung.

writeEncrypted()

Speichert den Entry verschlüsselt ab.

• Encrypted wird nur schreibend unterstützt.
• Sinnvoll bei Passwörtern

Beispiele

Normalen Entry mit Wert anlegen

metadb.write('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/[ Group ]/bundle/entry', 'Wert in der MetaDb'); // STRING

Entrys mit mehreren Werten (Array) anlegen

metadb.write('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/[ group ]/bundle' + '/entryAsArray', [ '123', 'ABC', 'next']); // STRING_ARRAY

JSON-Struktur übergeben

Wenn Sie eine JSON-Struktur übergeben, legt das System nicht nur einen einzelnen Entry an, sondern die komplette Struktur (mit Bundles und Gruppen):

 let json = {
  "[ TestGroup ]": {
    "bundleName": {
      Entry1: 'content1',
      Entry2: 'content2',
    }
  }
};
// Aufruf
metadb.write('MAIN_MODULE_MANAGEMENT/aguila/control/widgets', json);

Entry oder Bundle löschen

Wenn Sie ein Entry oder komplettes Bundle löschen möchten, übergeben Sie der Funktion write als entryValue den Wert null.

Im folgenden Beispiel existiert das Bundle ac.testWidget. Das System löscht das darin enthaltene Entry script:

metadb.write('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/[ acGroup ]/ac.testWidget/script', null);

Datentypen

Die Funktion erkennt den Datentyp automatisch. Unterschieden wird zwischen:

• String
• Arrays, die nur Strings enthalten
• Content
• JSON

Typen wie boolean oder Zahlen (int, double) sind nicht erlaubt. Sie müssen sie vor dem Schreiben in einen String formatieren, damit der Benutzer beim Lesen und Schreiben den gewünschten Typ erhält.

• Schreiben Sie Arrays mit einem Element als normalen String, da dies eine Speicheroptimierung bedeutet.
• Die Bibliothek entscheidet selbstständig anhand der Länge eines Inhalts, ob der String als Content oder normaler String abgespeichert wird.

Gruppen

Das Anlegen von Entrys direkt in Gruppen ist möglich.

inc

Liest einen übergebenen MetaDB-Entry aus, erhöht dessen Zahl um 1 und speichert sie wieder zurück.

• Das System führt diese Aktion in einer einzigen Transaktion durch.
• Die Aktion ist per lock vor gleichzeitigen Zugriffen geschützt.
• Wenn ein gleichzeitiger Zugriff stattfindet, wartet einer der Zugriffe, bis der erste Zugriff seine Zahl gesichert und wieder freigegeben hat.
• Wenn der Entry nicht vorhanden ist, legt das System ihn an und initialisiert ihn mit 1.

Beispiel

metadb.inc('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/myCounterEntry'); 
// Rückgabe initial 1

Parameter „defaultValue“

Definiert den Startwert.

• Das System beginnt anstatt mit einer 0 mit der definierten Zahl.
• Sie können so etwa Nummernkreise definieren.

Beispiel

metadb.inc('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/myCounterEntry', 10000); 
// Rückgabe initial 10001

Rohdaten auslesen

---

listGroupsRaw, listBundlesRaw und listEntriesRaw

Liefert ein Array mit allen Gruppen (als Objekt) in diesem Pfad.

• Das System liest ausschließlich die angefragte Ebene aus.
• Übergebener Parameter ist der Pfad in der MetaDB.

Beispiel

Der Bundle widgets enthält die Gruppen:

• [ Standard ]
• [ Group1 ]

let data = MetaDb.listGroupsRaw('MAIN_MODULE_MANAGEMENT/aguila/control/widgets/');
 
data.map(b => b.name);      // Rückgabe [ "[ Standard ]", "[ Group1 ]" ]
data.length;                // Rückgabe: 2

listAllGroupsRaw

Liest alle Gruppen ab dem übergebenen Pfad rekursiv aus.

• Das System liefert JavaScript-Map.
• Jeder Key repräsentiert den Namen der Gruppe.
• Wenn eine Gruppe weitere Untergruppen besitzt, steht dies im value der Map, ansonsten null.

Beispiel

metadb.listAllGroupsRaw('MAIN_MODULE_MANAGEMENT/aguila/control/widgets); 
/* Rückgabe ist:
{
  "[ Standard ]": null,
  "[ Group1 ]": {
    "[ Group c ]": null,
    "[ Group b ]": null,
    "[ Group a ]": null
  }
}
*/

Verschlüsselte Werte verwenden

---

decrypt

Entschlüsselt den übergebenen String mit dem MetaDB-Schlüssel des Systems, um etwa Werte zu entschlüsseln, die Sie etwa per read() gelesen haben.

Beispiel

let metadb = require('common/metadb');

let secret = metadb.decrypt(metadb.read('MAIN_MODULE_MANAGEMENT/customers/test/secret')[0]);

Werte beim Auslesen konvertieren

---

readArray

Liest den angegebenen MetaDB-Schlüssel aus und liefert ihn als Array.

Wenn der Schlüssel nicht existiert, liefert das System stattdessen ein leeres Array.

Beispiel

let metadb = require('common/metadb');

metadb.readArray('MAIN_MODULE_MANAGEMENT/my/test/key').join('\n');

readString

Liest den angegebenen MetaDB-Schlüssel aus und liefert ihn als String.

Wenn der Schlüssel nicht existiert, liefert das System stattdessen undefined.

Beispiel

let metadb = require('common/metadb');

metadb.readString('MAIN_MODULE_MANAGEMENT/my/test/key');

readNumber

Liest den angegebenen MetaDB-Schlüssel aus und liefert ihn als Number.

Wenn der Schlüssel nicht existiert, liefert das System stattdessen null.

Beispiel

let metadb = require('common/metadb');

metadb.readNumber('MAIN_MODULE_MANAGEMENT/my/test/key');

readBoolean

Liest den angegebenen MetaDB-Schlüssel aus und liefert ihn als Boolean.

Das System interpretiert einen String-Wert von true als true, alles andere (auch ein fehlender Schlüssel) als false.

Beispiel

let metadb = require('common/metadb');

metadb.readBoolean('MAIN_MODULE_MANAGEMENT/my/test/key');

getParameter

Liefert Parameter, die einerseits übergeben (Standardwerte) und andererseits aus der MetaDB geholt werden, wenn diese dort vorhanden sind.

Beispiel

let metadb = require('common/metadb');

// metadb.getParameter(name, parameters, path, fallback, dataType);
metadb.getParameter('parameterName1', {
  parameterName1: 'Wert 1'
}, 'MAIN_MODULE_MANAGEMENT/my/test', 'Wert Fallback', 'string');

• Das System prüft im Beispiel zuerst, ob der Wert für parameterName1 in den übergebenen Parametern vorhanden ist.
• Wenn nicht, prüft das System, ob der Parameter parameterName1 in der MetaDB unterhalb des Bundles MAIN_MODULE_MANAGEMENT/my/test existiert.
• Findet das System auch hier keinen Wert, liefert es den Fallback-Wert.
• Das System erwartet als Wert einen String als Datentyp.

Die Datentypen-Angabe wandelt den gelesenen Wert in den gewünschten Datentyp um.

Mögliche Datentypen:

• string
• boolean
• array
• number
• json

Die Funktion können Sie etwa in JavaScript-DataHandlern verwenden, um Parameter entweder in den dataSourceParameters mitzugeben oder diese Parameter in einem MetaDB-Schlüssel (dort, wo der DataHandler registriert ist) zu überladen. So können Sie die Standardwerte eines DataHandlers in seiner MetaDB-Konfiguration definieren und das Verhalten eines DataHandlers konfigurieren.

Beispiel für einen DataHandler, der „getParameters“ verwendet

/* global sc, sca, query, parameters, command, path */
let mc = require('/agorum/roi/customers/agorum.metadata.collection/js/metadata-collection');
let i18n = require('common/i18n');
let metaDb = require('common/metadb');

if (command !== 'read') {
  throw new Error('this datahandler only supports read');
}


let result = [];

if (parameters.lookup) {
  if (query) {
    let collection = mc.get(query, metaDb.getParameter('usage', parameters, path));
    if (collection) {
      result.push({
        text: i18n.translate(collection.displayName || query)  + ' (' + query + ')',
        value: query
      });
    }
  }
}
else {
  let collections = mc.get(null, metaDb.getParameter('usage', parameters, path));
  for (let name in collections) {
    let collection = collections[name];
    result.push({
      text: i18n.translate(collection.displayName || name) + ' (' + name + ')',
      value: name
    });
  }

  result = result.filter(entry => {
    return !query || entry.text.toLowerCase().indexOf(query.toLowerCase()) !== -1 || entry.value.toLowerCase().indexOf(query.toLowerCase()) !== -1;
  });  
  
  result = result.sort((a, b) => {
    return a.text.localeCompare(b.text);
  });
}

result;