Backend Lieux

Vue d'ensemble

L'interface QPlaceManager, fournie aux clients pour leur permettre d'accéder aux informations sur les lieux, dépend directement d'une implémentation de QPlaceManagerEngine. Le moteur fournit les implémentations des fonctions dorsales qui sont appelées par le gestionnaire.

Un implémenteur de backend de lieux doit dériver de QPlaceManagerEngine et fournir des implémentations pour les fonctions virtuelles pertinentes pour son backend. La plupart de ces fonctions étant asynchrones, les implémenteurs devront également dériver les classes de réponse appropriées. Les objets de réponse sont responsables de la gestion d'une demande asynchrone ; ils sont utilisés pour notifier la fin d'une demande et conserver les résultats de cette demande. QPlaceManagerEngine fournit une implémentation par défaut pour toutes les fonctions virtuelles. Les implémentations par défaut des fonctions asynchrones renvoient une réponse qui émettra les signaux errorOccurred() et finished() à la prochaine itération de la boucle d'événements.

Mise en œuvre/héritage des objets de réponse

Un objet de réponse est hérité de la manière suivante :

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;
};

La mise en œuvre de QPlaceManagerEngine doit garantir que tous les signaux émis par les objets de réponse sont retardés jusqu'à ce que les fonctions de demande soient retournées et que le code de l'application ait la possibilité de connecter ces signaux à des emplacements. L'approche typique consiste à utiliser QMetaObject::invokeMethod() avec Qt::QueuedConnection pour émettre les signaux.

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);
}

Notez que les signaux finished doivent toujours être émis lorsqu'une réponse est complète, même si une erreur a été rencontrée, c'est-à-dire que s'il y a une erreur, les signaux error et finished doivent être émis, tandis que s'il n'y a pas d'erreur, seuls les signaux finished sont émis.

Les fonctions protégées de QPlaceSearchReply::setResults() et QPlaceSearchReply::setRequest() sont accessibles au public afin que le plugin puisse attribuer des résultats et des demandes. Comme ces fonctions ne sont pas exportées publiquement, l'accessibilité n'est pas vraiment un problème. Une autre solution aurait consisté à déclarer une classe amie dans SearchReply.

En règle générale, l'instance du moteur devient parent de la réponse. Si le développeur ne se débarrasse pas des réponses lorsqu'il a terminé, le moteur peut les nettoyer lors de leur destruction. En général, la réponse possède également un pointeur vers le moteur, qui peut être utilisé pour émettre les signaux QPlaceManagerEngine::finished() et QPlaceManagerEngine::error(). Ce n'est qu'une des nombreuses façons dont la réponse peut être implémentée.

URL des icônes

Les URL des icônes sont fournies par la fonction QPlaceManagerEngine::constructIconUrl(). Le comportement attendu est que le moteur utilise la fonction QPlaceIcon::parameters() pour construire une URL appropriée. Lorsqu'un objet QPlace est renvoyé par le gestionnaire à la suite d'une recherche ou d'une requête visant à obtenir des détails sur un lieu, le moteur doit remplir correctement les paramètres si nécessaire.

Le backend est libre de choisir la clé et les valeurs des paramètres, mais si un backend n'a jamais qu'une URL par icône, il est recommandé d'utiliser QPlaceIcon::SingleUrl comme clé.

Catégories

Les catégories d'un moteur de gestion sont des entités relativement statiques ; pour les moteurs qui accèdent à des bases de données de lieux distants, il peut être souhaitable de mettre en cache la structure des catégories plutôt que d'interroger un serveur à chaque fois que QPlaceManagerEngine::initializeCategories() est appelé. En fonction de la dynamique des catégories, il peut être plus approprié de toujours télécharger l'ensemble de catégories le plus récent.

Enregistrement de lieux dans le gestionnaire

Un lieu ne peut généralement pas être sauvegardé directement entre les gestionnaires, car il contient des données spécifiques au gestionnaire, telles que des icônes et des catégories. Afin de faciliter la sauvegarde dans son propre gestionnaire, les implémenteurs de moteurs doivent implémenter la fonction QPlaceManagerEngine::compatiblePlace(). Cette fonction renvoie une copie du lieu d'entrée dont les propriétés ont été élaguées ou modifiées si nécessaire, de sorte que la copie puisse être enregistrée dans le gestionnaire.

La construction d'un lieu compatible peut impliquer d'ignorer certaines propriétés du lieu d'origine, par exemple si les coordonnées ne sont pas prises en charge, elles sont laissées de côté dans le lieu compatible. Dans d'autres cas, il peut s'agir de modifier certaines propriétés, par exemple les paramètres de l'icône pour faciliter la copie ou le téléchargement de l'icône du lieu d'origine à un emplacement auquel le backend peut accéder.

Référencement croisé des lieux entre gestionnaires

Il peut arriver que nous souhaitions faire des références croisées et faire correspondre des lieux entre gestionnaires. Une telle situation peut se produire lorsqu'un gestionnaire fournit un accès en lecture seule aux lieux (gestionnaire d'origine), tandis qu'un second gestionnaire en lecture seule (gestionnaire de destination) est utilisé pour sauvegarder les favoris sélectionnés dans le premier. Lors d'une recherche dans le gestionnaire d'origine, on peut vouloir savoir quels lieux ont été "favorisés" dans le gestionnaire de destination et éventuellement afficher le nom personnalisé du favori plutôt que le nom d'origine.

Référencement croisé des identificateurs alternatifs

Pour réaliser un référencement croisé, il faut qu'il y ait un lien entre le lieu d'origine et le lieu favorisé, ce qui se fait généralement par l'intermédiaire d'un attribut d'identifiant alternatif. Le lieu favorisé contient un attribut d'identifiant alternatif qui contient l'identifiant du lieu d'origine.

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

Il existe trois conditions préalables à la mise en œuvre de la référence croisée par identifiant alternatif. La première est que le gestionnaire d'origine doit fournir l'attribut x_provider dont la valeur est le nom du gestionnaire QGeoServiceProvider. L'étiquette de l'attribut doit rester vide, ce qui indique que l'attribut ne doit pas être affiché aux utilisateurs.

Deuxièmement, QPlaceManager::compatiblePlace() du gestionnaire de destination utilise l'attribut x_provider du lieu initial et définit un autre attribut d'identification du lieu à sauvegarder. La clé de l'attribut d'identifiant alternatif est x_id_<provider name> et la valeur textuelle est l'identifiant du lieu initial. L'attribut x_provider ne doit pas être transmis au lieu compatible. Lorsqu'il est sauvegardé, le x_provider du lieu sauvegardé est considéré comme le gestionnaire de destination.

Troisièmement, QPlaceManager::matchingPlaces() du gestionnaire de destination accepte QPlaceMatchRequest::AlternativeId comme clé de paramètre et la clé d'attribut de l'identificateur alternatif comme valeur ; dans ce cas, x_id_<provider name> serait la valeur attendue. Cela indique que les identificateurs de lieux dans le site QPlaceMatchRequest doivent être comparés aux attributs d'identificateurs alternatifs x_id_<provider name>.

Il convient de noter que si le gestionnaire de destination doit faciliter l'enregistrement et les références croisées à partir de n'importe quel gestionnaire arbitraire, il doit permettre en interne l'enregistrement de paires clé-valeur arbitraires, puisque nous ne pouvons pas connaître à l'avance les noms des fournisseurs, ni savoir quelle sera la structure des identifiants.

Autres méthodes de liaison

Si un gestionnaire d'origine ne fournit pas d'identifiant de lieu, il peut s'avérer nécessaire de fournir d'autres moyens d'établir des références croisées ou des correspondances. Si les coordonnées d'un lieu dans le gestionnaire d'origine sont identiques ou proches de celles d'un lieu dans le gestionnaire de destination, il est fort probable qu'il s'agisse du même lieu. Dans ce cas, le gestionnaire peut implémenter QPlaceManager::matchingPlaces() pour accepter un QPlaceMatchRequest avec une clé de paramètre "proximity" et une valeur de paramètre de la distance entre les deux lieux pour détecter une correspondance. Par exemple, si un lieu d'origine et un lieu de destination sont à moins de 50 m l'un de l'autre, ils peuvent être considérés comme le même lieu.

En règle générale, il est toutefois recommandé de mettre en œuvre le référencement croisé par le biais d'identifiants alternatifs, comme indiqué ci-dessus.

Attributs étendus lisibles par l'utilisateur ou non lisibles par l'utilisateur

Si un attribut n'est pas destiné à être lu par les utilisateurs finaux, le champ de l'étiquette doit rester vide pour indiquer ce fait.