JSONStore in Cordova-Anwendungen

Voraussetzungen

• Gehen Sie das übergeordnete Lernprogramm zu JSONStore durch.
• Stellen Sie sicher, dass das MobileFirst-Cordova-SDK zum Projekt hinzugefügt wurde. Folgen Sie dabei dem Lernprogramm SDK der Mobile Foundation zu Cordova-Anwendungen hinzufügen.

Fahren Sie mit folgenden Abschnitten fort:

• JSONStore hinzufügen
• Grundlegende Verwendung
• Erweiterte Verwendung
• Beispielanwendung

JSONStore hinzufügen

Gehen Sie wie folgt vor, um das JSONStore-Plug-in zu Ihrer Cordova-Anwendung hinzuzufügen:

1. Öffnen Sie ein Befehlszeilenfenster und navigieren Sie zu Ihrem Cordova-Projektordner.
2. Führen Sie den Befehl cordova plugin add cordova-plugin-mfp-jsonstore aus.

Grundlegende Verwendung

Initialisieren

Starten Sie mit init mindestens ene JSONStore-Sammlung.

Sammlungen zu starten oder bereitzustellen bedeutet, dass der persistente Speicher für die Sammlung und für Dokumente erstellt wird, wenn er nicht vorhanden ist. Wenn der Speicher verschlüsselt ist und das richtige Kennwort übergeben wird, werden die erforderlichen Sicherheitsprozeduren ausgeführt, um die Daten zugänglich zu machen.

var collections = {
    people : {
        searchFields: {name: 'string', age: 'integer'}
    }
};

WL.JSONStore.init(collections).then(function (collections) {
    // Erfolg behandeln - collection.people (Sammlung "people")
}).fail(function (error) {
    // Feler behandeln
});

Informationen zu optionalen Features, die Sie während der Initialisierung aktivieren können, finden Sie im zweiten Teil dieses Lernprogramms unter Sicherheit, Unterstützung für mehrere Benutzer und MobileFirst-Adapter integrieren.

Get

Mit get können Sie einen Mechanismus für den Zugriff auf die Sammlung erstellen. Sie müssen init aufrufen, bevor Sie “get” aufrufen. Andernfalls ist das Ergebnis von get undefiniert.

var collectionName = 'people';
var people = WL.JSONStore.get(collectionName);

Die Variable people kann jetzt verwendet werden, um Operationen für die Sammlung people auszuführen (z. B. add, find und replace).

Add

Verwenden Sie add, um Daten als Dokumente innerhalb einer Sammlung zu speichern.

var collectionName = 'people';
var options = {};
var data = {name: 'yoel', age: 23};

WL.JSONStore.get(collectionName).add(data, options).then(function () {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

Find

• Verwenden Sie find, um mit einer Abfrage ein Dokument in einer Sammlung zu finden.
• Verwenden Sie findAll, um alle Dokumente aus einer Sammlung abzurufen.
• Verwenden Sie findById, um mit der eindeutigen Dokument-ID nach einem Dokument zu suchen.

Das Standardverhalten für “find” ist eine Suche nach grober Übereinstimmung.

var query = {name: 'yoel'};
var collectionName = 'people';
var options = {
  exact: false, // Standardwert
  limit: 10 // Rückgabe von maximal 10 Dokumenten. Standardeinstellung: Rückgabe aller Dokumente
};

WL.JSONStore.get(collectionName).find(query, options).then(function (results) {
    // Erfolg behandeln - results (Array der gefundenen Dokumente)
}).fail(function (error) {
    // Feler behandeln
});

var age = document.getElementById("findByAge").value || '';

if(age == "" || isNaN(age)){
  alert("Please enter a valid age to find");
}
else {
  query = {age: parseInt(age, 10)};
  var options = {
    exact: true,
    limit: 10 // Rückgabe von maximal 10 Dokumenten
  };
  WL.JSONStore.get(collectionName).find(query, options).then(function (res) {
    // Erfolg behandeln - results (Array der gefundenen Dokumente)
}).fail(function (errorObject) {
    // Fehler behandeln
  });
}

Replace

Verwenden Sie replace, um Dokumente in einer Sammlung zu modifizieren. Das Feld für die Ersetzung ist die eindeutige ID des Dokuments (_id).

var document = {
  _id: 1, json: {name: 'chevy', age: 23}
};
var collectionName = 'people';
var options = {};

WL.JSONStore.get(collectionName).replace(document, options).then(function (numberOfDocsReplaced) {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

In den vorliegenden Beispielen wird davon ausgegangen, dass das Dokument ({_id: 1, json: {name: 'yoel', age: 23} }) in der Sammlung enthalten ist.

Remove

Verwenden Sie remove, um ein Dokument aus einer Sammlung zu löschen.
Dokumente werden erst aus der Sammlung entfernt, wenn Sie “push” aufgerufen haben.

Weitere Informationen finden Sie im Abschnitt MobileFirst-Adapter integrieren weiter unten in diesem Lernprogramm.

var query = {_id: 1};
var collectionName = 'people';
var options = {exact: true};
WL.JSONStore.get(collectionName).remove(query, options).then(function (numberOfDocsRemoved) {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

removeCollection

Verwenden Sie removeCollection, um alle Dokumente aus einer Sammlung zu löschen. Diese Operation ist mit dem Löschen einer Datenbanktabelle vergleichbar.

var collectionName = 'people';
WL.JSONStore.get(collectionName).removeCollection().then(function (removeCollectionReturnCode) {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

Erweiterte Verwendung

Destroy

Mit destroy können Sie die folgenden Daten entfernen:

• Alle Dokumente
• Alle Sammlungen
• Alle Stores (siehe Unterstützung für mehrere Benutzer weiter unten in diesem Lernprogramm)
• Alle JSONStore-Metadaten und -Sicherheitsartefakte (siehe Sicherheit weiter unten in diesem Lernprogramm)

var collectionName = 'people';
WL.JSONStore.destroy().then(function () {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

Sicherheit

Sie können alle Sammlungen in einem Store schützen, indem Sie an die Funktion init ein Kennwort übergeben. Wenn kein Kennwort übergeben wird, wird keines der Dokumente in den Sammlungen des Store verschlüsselt.

Die Datenverschlüsselung ist nur in Android-, iOS-, Windows-8.1-Universal- und Windows-10-UWP-Umgebungen verfügbar.
Einige Sicherheitsmetadaten werden in der Keychain (iOS), in den Shared Preferences (Android) oder im *Schließfach für Anmeldeinformationen * (Windows 8.1) gespeichert.
Der Store wird mit einem 256-Bit-Schlüssel gemäß Advanced Encryption Standard (AES) verschlüsselt. Alle Schlüssel werden durch die Funktion PBKDF2 (Password-Based Key Derivation Function 2) verstärkt.

Verwenden Sie closeAll, um den Zugriff auf alle Sammlungen bis zum erneuten Aufruf von init zu sperren. Wenn Sie sich init als eine Art Anmeldefunktion vorstellen, wäre closeAll die entsprechende Abmeldefunktion. Verwenden Sie changePassword, um das Kennwort zu ändern.

var collections = {
  people: {
    searchFields: {name: 'string'}
  }
};
var options = {password: '123'};
WL.JSONStore.init(collections, options).then(function () {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

Verschlüsselung

Nur iOS: Standardmäßig ist das MobileFirst-Cordova-SDK für iOS für die Verschlüsselung auf iOS-APIs angewiesen. Wenn Sie lieber OpenSSL verwenden möchten, gehen Sie wie folgt vor:

1. Fügen Sie das Plug-in cordova-plugin-mfp-encrypt-utils hinzu: cordova plugin add cordova-plugin-mfp-encrypt-utils.
2. Verwenden Sie in der applikativen Logik WL.SecurityUtils.enableNativeEncryption(false), um die OpenSSL-Option zu aktivieren.

Unterstützung für mehrere Benutzer

Sie können mehrere Stores erstellen, die verschiedene Sammlungen in nur einer MobileFirst-Anwendung enthalten. Die Funktion init kann mit einem Optionsobjekt mit einem Benutzernamen verwendet werden. Wenn kein Benutzername angegeben wird, wird der Standardbenutzername jsonstore verwendet.

var collections = {
  people: {
    searchFields: {name: 'string'}
  }
};
var options = {username: 'yoel'};
WL.JSONStore.init(collections, options).then(function () {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

MobileFirst-Adapter integrieren

In diesem Abschnitt wird vorausgesetzt, dass Sie sich mit Adaptern auskennen.

Die Adapterintegration ist optional. Sie ermöglicht das Senden von Daten einer Sammlung an einen Adapter und das Abrufen von Daten eines Adapters in eine Sammlung.
Sie können diese Ziele mit WLResourceRequest erreichen oder mit jQuery.ajax, falls Sie mehr Flexibilität benötigen.

Adapterimplementierung

Erstellen Sie einen Adapter mit dem Namen JSONStoreAdapter.
Definieren Sie für den Adapter die Prozeduren addPerson, getPeople, pushPeople, removePerson und replacePerson.

function getPeople () {
var data = { peopleList : [{name: 'chevy', age: 23}, {name: 'yoel', age: 23}] };
	WL.Logger.debug('Adapter: people, procedure: getPeople called.');
	WL.Logger.debug('Sending data: ' + JSON.stringify(data));
	return data;
}
function pushPeople(data) {
	WL.Logger.debug('Adapter: people, procedure: pushPeople called.');
	WL.Logger.debug('Got data from JSONStore to ADD: ' + data);
	return;
}
function addPerson(data) {
	WL.Logger.debug('Adapter: people, procedure: addPerson called.');
	WL.Logger.debug('Got data from JSONStore to ADD: ' + data);
	return;
}
function removePerson(data) {
	WL.Logger.debug('Adapter: people, procedure: removePerson called.');
	WL.Logger.debug('Got data from JSONStore to REMOVE: ' + data);
	return;
}
function replacePerson(data) {
	WL.Logger.debug('Adapter: people, procedure: replacePerson called.');
	WL.Logger.debug('Got data from JSONStore to REPLACE: ' + data);
	return;
}

Daten von einem MobileFirst-Adapter laden

Verwenden Sie WLResourceRequest, um Daten von einem Adapter zu laden.

try {
      var resource = new WLResourceRequest("adapters/JSONStoreAdapter/getPeople", WLResourceRequest.GET);
     resource.send()
     .then(function (responseFromAdapter) {
var data = responseFromAdapter.responseJSON.peopleList;
     },function(err){
      	//handle failure
     });
} catch (e) {
    alert("Failed to load data from adapter " + e.Messages);
}

getPushRequired (vorläufige Dokumente)

Wenn Sie getPushRequired aufrufen, wird ein Array mit vorläufigen Dokumenten (dirty documents) zurückgegeben. Diese Dokumente enthalten lokale Modifikationen, die es auf dem Back-End-System noch nicht gibt. Diese Dokumente werden an den Adapter gesendet, wenn push aufgerufen wird.

var collectionName = 'people';
WL.JSONStore.get(collectionName).getPushRequired().then(function (dirtyDocuments) {
    // Erfolg behandeln
}).fail(function (error) {
    // Feler behandeln
});

Wenn Sie JSONStore daran hindern möchten, Dokumente als vorläufig zu markieren, übergeben Sie die Option {markDirty:false} an add, replace und remove.

Sie können auch die API getAllDirty verwenden, um die vorläufigen Dokumente abzurufen:

WL.JSONStore.get(collectionName).getAllDirty()
.then(function (dirtyDocuments) {
    // Erfolg behandeln
}).fail(function (errorObject) {
    // Feler behandeln
});

Änderungen mit Push übertragen

Wenn Sie Änderungen mit Push an einen Adapter senden möchten, rufen Sie getAllDirty auf, um eine Liste der Dokumente mit Modifikationen abzurufen. Verwnden Sie dann WLResourceRequest. Nach dem Senden der Daten und einer Bestätung des erfolgreichen Sendens müssen Sie markClean aufrufen.

try {
      var collectionName = "people";
     var dirtyDocs;

     WL.JSONStore.get(collectionName)
 
.getAllDirty()
 
.then(function (arrayOfDirtyDocuments) {
  dirtyDocs = arrayOfDirtyDocuments;
 
  var resource = new WLResourceRequest("adapters/JSONStoreAdapter/pushPeople", WLResourceRequest.POST);
        resource.setQueryParameter('params', [dirtyDocs]);
        return resource.send();
     }).then(function (responseFromAdapter) {
return WL.JSONStore.get(collectionName).markClean(dirtyDocs);
})
 
.then(function (res) {

  // Erfolg behandeln
}).fail(function (errorObject) {
    // Fehler behandeln
     });

} catch (e) {
    alert("Failed To Push Documents to Adapter");
}

Enhance

Verwenden Sie enhance, um die Kern-API an Ihre Anforderungen anzupassen, indem Sie Funktionen zu einem Sammlungsprototyp hinzufügen. Das folgende Beispiel (Code-Snippet) zeigt, wie mit enhance die Funktion getValue hinzugefügt wird, die für die Sammlung keyvalue ausgeführt wird. Sie wird mit einer Schlüsselzeichenfolge (key) als einzigem Parameter verwendet und gibt ein Einzelergebnis zurück.

var collectionName = 'keyvalue';
WL.JSONStore.get(collectionName).enhance('getValue', function (key) {
    var deferred = $.Deferred();
    var collection = this;
    // Exakte Suche nach dem Schüssel
    collection.find({key: key}, {exact:true, limit: 1}).then(deferred.resolve, deferred.reject);
    return deferred.promise();
});

// Syntax:
var key = 'myKey';
WL.JSONStore.get(collectionName).getValue(key).then(function (result) {
    // Erfolg behandeln
    // Das Ergebnis ist ein Array mit Dokumenten mit den Ergebnissen der Suche.
}).fail(function () {
    // Feler behandeln
});

Weitere Informationen zu JSONStore finden Sie in der Benutzerdokumentation.

Beispielanwendung

Das JSONStoreSwift-Projekt enthält eine Cordova-Anwendung, die die JSONStore-APIs verwendet.
Eingeschlossen ist ein JavaScript-Adapter-Maven-Projekt.

Klicken Sie hier, um das Cordova-Projekt herunterzuladen.
Klicken Sie hier, um das Adapter-Maven-Projekt herunterzuladen.

Verwendung des Beispiels

Anweisungen finden Sie in der Datei README.md zum Beispiel.