Orte-Backend

Übersicht

Die Schnittstelle „ QPlaceManager “, die Clients den Zugriff auf Ortsinformationen ermöglicht, hängt direkt von einer Implementierung von „ QPlaceManagerEngine “ ab. Die Engine stellt die Backend-Funktionsimplementierungen bereit, die vom Manager aufgerufen werden.

Ein Implementierer des Orte-Backends muss von ` QPlaceManagerEngine ` ableiten und Implementierungen für die für sein Backend relevanten virtuellen Funktionen bereitstellen. Die meisten dieser Funktionen sind asynchron, daher müssen Implementierer auch die entsprechenden Antwortklassen ableiten. Die Antwortobjekte sind für die Verwaltung einer asynchronen Anfrage zuständig; sie dienen dazu, zu melden, wenn eine Anfrage abgeschlossen ist, und enthalten die Ergebnisse dieser Anfrage. ` QPlaceManagerEngine ` stellt eine Standardimplementierung für alle virtuellen Funktionen bereit. Die Standardimplementierungen für die asynchronen Funktionen geben eine Antwort zurück, die bei der nächsten Iteration durch die Ereignisschleife die Signale `errorOccurred()` und `finished()` auslöst.

Implementierung/Vererbung von Antwortobjekten

Ein Antwortobjekt würde wie folgt vererbt werden:

class SearchReply : public QPlaceSearchReply
{
public:
    explicit SearchReply(ManagerEngine *engine)
        : QPlaceSearchReply(engine), m_engine(engine){}

    ~SearchReply();
    void setResults(const QList<QPlaceSearchResult> &results);
    void setRequest(const QPlaceSearchRequest &request);
    ...
    void triggerDone(QPlaceReply::Error error = QPlaceReply::NoError,
                     const QString &errorString = QString());

    ManagerEngine *m_engine;
};

Die Implementierung eines ` QPlaceManagerEngine ` muss sicherstellen, dass alle von den Antwortobjekten ausgelösten Signale verzögert werden, bis die Anforderungsfunktionen zurückgekehrt sind und der Anwendungscode die Möglichkeit hat, diese Signale mit Slots zu verknüpfen. Der typische Ansatz besteht darin, ` QMetaObject::invokeMethod()` mit einem ` Qt::QueuedConnection ` zu verwenden, um die Signale auszulösen.

void SearchSuggestionReply::triggerDone(QPlaceReply::Error error,
                         const QString &errorString)
{
    if (error != QPlaceReply::NoError) {
        this->setError(error,errorString);
        QMetaObject::invokeMethod(m_engine, "errorOccurred", Qt::QueuedConnection,
                                  Q_ARG(QPlaceReply *,this),
                                  Q_ARG(QPlaceReply::Error, error),
                                  Q_ARG(QString, errorString));
        QMetaObject::invokeMethod(this, "errorOccurred", Qt::QueuedConnection,
                                  Q_ARG(QPlaceReply::Error, error),
                                  Q_ARG(QString, errorString));
    }

    this->setFinished(true);
    QMetaObject::invokeMethod(m_engine, "finished", Qt::QueuedConnection,
                              Q_ARG(QPlaceReply *,this));
    QMetaObject::invokeMethod(this, "finished", Qt::QueuedConnection);
}

Beachten Sie, dass die Signale „ finished “ immer dann ausgesendet werden sollten, wenn eine Antwort vollständig ist, selbst wenn ein Fehler aufgetreten ist; das heißt, im Falle eines Fehlers sollten sowohl das Signal „ error “ als auch das Signal „ finished “ ausgesendet werden, während bei fehlendem Fehler nur das Signal „ finished “ ausgesendet wird.

Die geschützten Funktionen „ QPlaceSearchReply::setResults()“ und „ QPlaceSearchReply::setRequest()“ werden öffentlich zugänglich gemacht, damit das Plugin Ergebnisse und Anfragen zuweisen kann. Da diese Funktionen nicht öffentlich exportiert werden, stellt der Zugriff kein großes Problem dar. Eine Alternative wäre gewesen, in „SearchReply“ eine „Friend“-Klasse zu deklarieren.

In der Regel wird die Engine-Instanz zum „ parent “ der Antwort gemacht. Falls der Entwickler vergisst, die Antworten nach Abschluss zu verwerfen, kann die Engine diese bei ihrer Zerstörung bereinigen. Häufig verfügt die Antwort auch über einen Zeiger, der zurück zur Engine verweist; dieser kann verwendet werden, um die Signale „ QPlaceManagerEngine::finished()“ und „QPlaceManagerEngine::error()“ auszulösen. Dies ist nur eine von vielen Möglichkeiten, wie die Antwort implementiert werden könnte.

Icon-URLs

Icon-URLs werden über die Funktion ` QPlaceManagerEngine::constructIconUrl()` bereitgestellt. Es wird erwartet, dass die Engine die Funktion ` QPlaceIcon::parameters()` verwendet, um eine geeignete URL zu erstellen. Wenn vom Manager ein ` QPlace `-Objekt zurückgegeben wird – sei es aufgrund einer Suche oder einer Abfrage zur Ermittlung von Ortsdetails –, wird erwartet, dass die Engine die Parameter entsprechend korrekt ausfüllt.

Das Backend kann die Parameterschlüssel und -werte frei wählen. Wenn ein Backend jedoch immer nur eine URL pro Symbol hat, wird empfohlen, „ QPlaceIcon::SingleUrl “ als Schlüssel zu verwenden.

Kategorien

Die Kategorien einer Manager-Engine sind relativ statische Entitäten; für Engines, die auf entfernte Ortsdatenspeicher zugreifen, kann es sinnvoll sein, die Kategoriestruktur zwischenzuspeichern, anstatt bei jedem Aufruf von ` QPlaceManagerEngine::initializeCategories()` einen Server abzufragen. Je nachdem, wie dynamisch die Kategorien sind, kann es angemessener sein, stets den aktuellsten Satz an Kategorien herunterzuladen.

Speichern von Orten im Manager

Ein Ort kann in der Regel nicht direkt zwischen Managern gespeichert werden, da er managerspezifische Daten wie Symbole und Kategorien enthält. Um das Speichern im eigenen Manager zu ermöglichen, sollten Engine-Implementierer die Funktion ` QPlaceManagerEngine::compatiblePlace()` implementieren. Diese Funktion gibt eine Kopie des eingegebenen Ortes zurück, deren Eigenschaften bei Bedarf bereinigt oder geändert werden, sodass die Kopie im Manager gespeichert werden kann.

Die Erstellung eines kompatiblen Ortes kann bedeuten, dass bestimmte Eigenschaften des ursprünglichen Ortes ignoriert werden; werden beispielsweise Kontaktdaten nicht unterstützt, werden diese im kompatiblen Ort weggelassen. In anderen Fällen kann es erforderlich sein, bestimmte Eigenschaften anzupassen, beispielsweise die Symbolparameter zu ändern, um das Kopieren oder Herunterladen des Symbols des ursprünglichen Ortes an einen Ort zu erleichtern, auf den das Backend zugreifen kann.

Querverweise zwischen Managern

Manchmal kann eine Situation auftreten, in der wir Orte zwischen Managern miteinander verknüpfen und abgleichen möchten. Eine solche Situation kann entstehen, wenn ein Manager Lesezugriff auf Orte gewährt (Ursprungsmanager), während ein zweiter Lese-/Schreib-Manager (Zielmanager) verwendet wird, um ausgewählte Favoriten aus dem ersten zu speichern. Bei einer Suche im Ursprungsmanager möchten wir möglicherweise wissen, welche Orte im Zielmanager als „Favoriten“ gespeichert wurden, und vielleicht den benutzerdefinierten Favoritennamen anstelle des ursprünglichen Namens anzeigen.

Querverweise über alternative Identifikatoren

Um eine Querverweisung zu ermöglichen, muss eine Verbindung zwischen dem ursprünglichen Ort und dem als Favorit gespeicherten Ort bestehen; dies wird in der Regel über ein Attribut für alternative Kennungen geregelt. Der als Favorit gespeicherte Ort enthält ein Attribut für alternative Kennungen, das die Kennung des ursprünglichen Ortes enthält.

origin R/O manager(here)       destination R/W manager (places_jsondb)
                        Save
Place id: ae246         --->    Place id: 0001
Attribute type: x_provider      Attribute type: x_id_here
Attribute value: here           Attribute text value: ae246

Es gibt drei Voraussetzungen für die Implementierung von Querverweisen mittels alternativer Kennungen. Die erste ist, dass der Ursprungsmanager das Attribut „x_provider“ bereitstellen muss, dessen Wert der Name des Managers unter QGeoServiceProvider lautet. Die Attributbezeichnung sollte leer bleiben, was darauf hinweist, dass das Attribut den Benutzern nicht angezeigt werden soll.

Zweitens muss der Zielmanager „ QPlaceManager::compatiblePlace()“ das Attribut „ x_provider “ des ursprünglichen Ortes verwenden und ein Attribut für den alternativen Bezeichner des zu speichernden Ortes festlegen. Der Schlüssel des Attributs „alternative identifier“ lautet „ x_id_<provider name>“, und der Textwert ist die Kennung des ursprünglichen Ortes. Das Attribut „ x_provider “ sollte nicht an den kompatiblen Ort übergeben werden. Beim Speichern gilt der „x_provider“ des gespeicherten Ortes als Zielmanager.

Drittens akzeptiert die Funktion „ QPlaceManager::matchingPlaces()“ des Zielmanagers „ QPlaceMatchRequest::AlternativeId “ als Parameterschlüssel und den Schlüssel des alternativen Identifikatorattributs als Wert; in diesem Fall wäre „ x_id_<provider name>“ der erwartete Wert. Dies bedeutet, dass die Identifikatoren der Orte in „ QPlaceMatchRequest “ mit den alternativen Identifikatorattributen „ x_id_<provider name>“ abgeglichen werden sollten.

Beachten Sie, dass der Zielmanager, wenn er das Speichern und Verweisen von beliebigen Managern aus ermöglichen soll, intern das Speichern beliebiger Schlüssel-Wert-Paare unterstützen muss, da wir weder die Namen der Anbieter im Voraus kennen noch wissen können, welche Struktur die IDs haben werden.

Andere Methoden der Verknüpfung

Wenn ein Ursprungsmanager keine Orts-ID bereitstellt, kann es erforderlich sein, andere Mittel für Querverweise bzw. den Abgleich bereitzustellen. Ein Ansatz könnte darin bestehen, dies über die Ortskoordinaten zu tun: Sind die Koordinaten eines Ortes im Ursprungsmanager identisch mit oder nahe an denen eines Ortes im Zielmanager, besteht eine hohe Wahrscheinlichkeit, dass es sich um denselben Ort handelt. In diesem Fall könnte der Manager die Methode ` QPlaceManager::matchingPlaces()` implementieren, um einen ` QPlaceMatchRequest ` mit dem Parameterschlüssel „proximity“ und einem Parameterwert für den Abstand zu akzeptieren, den zwei Orte voneinander haben müssen, damit eine Übereinstimmung erkannt wird. Wenn beispielsweise ein Ausgangsort und ein Zielort weniger als 50 m voneinander entfernt sind, können sie als derselbe Ort betrachtet werden.

Im Allgemeinen wird jedoch empfohlen, Querverweise wie oben erwähnt über alternative Identifikatoren zu implementieren.

Für Benutzer lesbare vs. nicht lesbare erweiterte Attribute

Wenn ein Attribut nicht für Endnutzer lesbar sein soll, sollte das Feld „label“ als Hinweis darauf leer gelassen werden.