Places Backend

Обзор

Интерфейс QPlaceManager, предоставляемый клиентам для доступа к информации о местах, напрямую зависит от реализации QPlaceManagerEngine. Движок предоставляет реализации функций бэкэнда, которые вызываются менеджером.

Реализатор бэкэнда мест должен быть производным от QPlaceManagerEngine и предоставить реализации виртуальных функций, релевантных для их бэкэнда. Большинство этих функций асинхронны, поэтому реализаторы также должны будут реализовать соответствующие классы ответов. Объекты ответов отвечают за управление асинхронным запросом; они используются для уведомления о завершении запроса и содержат результаты этого запроса. QPlaceManagerEngine предоставляет реализацию по умолчанию для всех виртуальных функций. Реализации по умолчанию для асинхронных функций возвращают ответ, который будет излучать сигналы error() и finished() на следующей итерации цикла событий.

Реализация/наследование объектов ответов

Объект ответа был бы унаследован следующим образом:

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

Реализация QPlaceManagerEngine должна гарантировать, что все сигналы, излучаемые объектами ответов, отложены до тех пор, пока не вернутся функции запроса, и коду приложения представится возможность подключить эти сигналы к слотам. Типичный подход заключается в использовании QMetaObject::invokeMethod() с Qt::QueuedConnection для излучения сигналов.

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

Обратите внимание, что сигналы finished всегда должны излучаться при завершении ответа, даже если была обнаружена ошибка. То есть, если есть ошибка, должны излучаться как сигналы error , так и finished, а если ошибки нет, то только сигналы finished.

Защищенные функции QPlaceSearchReply::setResults() и QPlaceSearchReply::setRequest() сделаны общедоступными, чтобы плагин мог назначать результаты и запросы. Поскольку эти функции не являются общедоступными, вопрос доступности не так критичен. Альтернативой было бы объявить дружественный класс в SearchReply.

Обычно экземпляр движка является parent объекта ответа. Если разработчик не удаляет ответы при завершении, движок может очистить их при уничтожении. Как правило, ответ также содержит ссылку на движок, которая может использоваться для излучения сигналов QPlaceManagerEngine::finished() и QPlaceManagerEngine::error(). Это всего лишь один из многих способов реализации ответа.

URL иконок

URL иконок предоставляются через функцию QPlaceManagerEngine::constructIconUrl(). Ожидается, что движок будет использовать QPlaceIcon::parameters() для построения соответствующего URL. Когда объект QPlace возвращается менеджером, либо в результате поиска, либо в результате запроса получения подробностей о месте, ожидается, что движок корректно заполнит параметры, если необходимо.

Бэкенд свободен выбирать ключ и значения параметров, однако если бэкенд имеет только один URL на иконку, рекомендуется использовать QPlaceIcon::SingleUrl в качестве ключа.

Категории

Категории движка менеджера — это относительно статические сущности; для движков, получающих удаленные данные о местах, может быть желательно кэшировать структуру категорий, а не обращаться к серверу каждый раз, когда вызывается QPlaceManagerEngine::initializeCategories(). В зависимости от того, насколько динамичны категории, может быть более целесообразным всегда загружать самую свежую версию категорий.

Сохранение мест в менеджере

Место обычно не может быть сохранено напрямую между менеджерами, так как оно содержит специфичные для менеджера данные, такие как значки и категории. Для облегчения сохранения в собственном менеджере реализаторы движка должны реализовать функцию QPlaceManagerEngine::compatiblePlace(). Эта функция возвращает копию входного места с усеченными или измененными, по необходимости, свойствами, таким образом, чтобы копию можно было сохранить в менеджере.

Создание совместимого места может включать игнорирование определенных свойств из исходного места, например, если контактные данные не поддерживаются, они исключаются из совместимого места. В других случаях это может включать изменение определенных свойств, например, изменение параметров значка для облегчения копирования или загрузки значка исходного места в местоположение, к которому может получить доступ бэкенд.

Перекрестное ссылание мест между менеджерами

Иногда может возникнуть ситуация, когда необходимо перекрестно ссылаться и сопоставлять места между менеджерами. Такая ситуация может возникнуть, когда один менеджер предоставляет только чтение мест (исходный менеджер), а другой менеджер чтения/записи (целевой менеджер) используется для сохранения выбранных избранных элементов из первого. Во время поиска в исходном менеджере мы можем захотеть узнать, какие из них были «помечены как избранные» в целевом менеджере и, возможно, отобразить настраиваемое имя избранного элемента вместо исходного.

Перекрестное ссылание по альтернативному идентификатору

Для выполнения перекрестного ссылания необходима связь между исходным местом и помеченным как избранное местом, и это обычно обрабатывается с помощью атрибута альтернативного идентификатора. Избранное место содержит атрибут альтернативного идентификатора, который имеет идентификатор исходного места.

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

Для реализации перекрестного ссылания по альтернативному идентификатору необходимо выполнить три условия. Первое — исходный менеджер должен предоставить атрибут x_provider со значением, представляющим имя QGeoServiceProvider менеджера. Метка атрибута должна оставаться пустой, указывая, что атрибут не должен отображаться пользователям.

Примечание: Обычно ожидается, что все менеджеры должны установить атрибут x_provider.

Второе — QPlaceManager::compatiblePlace целевого менеджера должен использовать атрибут x_provider исходного места и установить атрибут альтернативного идентификатора места для сохранения. Ключ атрибута альтернативного идентификатора — x_id_<provider name>, а текстовое значение — идентификатор исходного места. Атрибут x_provider не должен передаваться совместимому месту. При сохранении x_provider сохраненного места считается целевым менеджером.

Третье — QPlaceManager::matchingPlaces целевого менеджера должен принимать QPlaceMatchRequest::AlternativeId в качестве параметра-ключа и ключ атрибута альтернативного идентификатора в качестве значения, в данном случае x_id_<provider name> ожидалось бы. Это указывает на то, что идентификаторы мест в QPlaceMatchRequest должны быть сопоставлены с атрибутами альтернативного идентификатора x_id_<provider name>.

Обратите внимание, что если целевой менеджер должен облегчить сохранение и перекрестное ссылание из любого произвольного менеджера, он внутренне должен поддерживать сохранение произвольных пар «ключ-значение», поскольку мы не можем заранее знать имена поставщиков, а также не можем знать, какой структурой будут идентификаторы.

Другие методы связывания

Если исходный менеджер не предоставляет идентификатор места, может потребоваться предоставить другие средства перекрестного ссылания/сопоставления. Один подход может состоять в том, чтобы сделать это с помощью координат места, если координаты места в исходном менеджере идентичны или близки к месту в целевом менеджере, то высокая вероятность того, что это одно и то же место. В этом случае менеджер может реализовать QPlaceManager::matchingPlaces() для приема QPlaceMatchRequest с ключом параметра «близость» и значением параметра — расстояния, на котором должны находиться два места, чтобы обнаружить совпадение. Например, если исходное и целевое места находятся на расстоянии 50 м друг от друга, их можно считать одним и тем же местом.

Однако, как правило, рекомендуется реализовать перекрестное ссылание с помощью альтернативных идентификаторов, как указано выше.

Атрибуты, читаемые и нечитаемые пользователями

Если атрибут не предназначен для чтения конечными пользователями, поле метки должно оставаться пустым в качестве индикатора этого факта.