Рубрики
Без рубрики

Введение в Couchbase SDK для Java

Быстрое и практичное введение в использование Java Couchbase SDK.

Автор оригинала: baeldung.

1. введение

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

2. Зависимости Maven

Если вы используете Maven, добавьте в свой pom.xml файл:


    com.couchbase.client
    java-client
    2.2.6

3. Начало работы

SDK предоставляет интерфейс CouchbaseEnvironment и класс реализации DefaultCouchbaseEnvironment , содержащий настройки по умолчанию для управления доступом к кластерам и ведрам. Параметры среды по умолчанию могут быть переопределены при необходимости, как мы увидим в разделе 3.2.

Важно: Официальная документация Couchbase SDK предупреждает пользователей о том, что в JVM активна только одна CouchbaseEnvironment , поскольку использование двух или более может привести к непредсказуемому поведению.

3.1. Подключение к Кластеру Со Средой по умолчанию

Чтобы SDK автоматически создал среду CouchbaseEnvironment с настройками по умолчанию и связал ее с нашим кластером, мы можем подключиться к кластеру, просто указав IP-адрес или имя хоста одного или нескольких узлов в кластере.

В этом примере мы подключаемся к кластеру с одним узлом на нашей локальной рабочей станции:

Cluster cluster = CouchbaseCluster.create("localhost");

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

Cluster cluster = CouchbaseCluster.create("192.168.4.1", "192.168.4.2");

Примечание: Нет необходимости указывать каждый узел в кластере при создании начального соединения. Среда CouchbaseEnvironment запросит кластер после установления соединения, чтобы обнаружить оставшиеся узлы (если таковые имеются).

3.2. Использование пользовательской среды

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

Вот пример, который подключается к кластеру с одним узлом, используя пользовательскую среду CouchbaseEnvironment с десятисекундным таймаутом подключения и трехсекундным таймаутом поиска значения ключа:

CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder()
  .connectTimeout(10000)
  .kvTimeout(3000)
  .build();
Cluster cluster = CouchbaseCluster.create(env, "localhost");

И для подключения к многоузловому кластеру с пользовательской средой:

Cluster cluster = CouchbaseCluster.create(env,
  "192.168.4.1", "192.168.4.2");

3.3. Открытие ведра

После подключения к кластеру Couchbase вы можете открыть одно или несколько ведер.

При первой настройке кластера Couchbase установочный пакет автоматически создает корзину с именем “по умолчанию” с пустым паролем.

Вот один из способов открыть ведро “по умолчанию” , когда у него пустой пароль:

Bucket bucket = cluster.openBucket();

Вы также можете указать имя корзины при ее открытии:

Bucket bucket = cluster.openBucket("default");

Для любого другого ведра с пустым паролем вы должны указать имя ведра:

Bucket myBucket = cluster.openBucket("myBucket");

Чтобы открыть корзину с непустым паролем, необходимо указать имя корзины и пароль:

Bucket bucket = cluster.openBucket("bucketName", "bucketPassword");

4. Операции сохранения

В этом разделе мы покажем, как выполнять операции CRUD в Couchbase. В наших примерах мы будем работать с простыми документами JSON, представляющими человека, как в этом примере документа:

{
  "name": "John Doe",
  "type": "Person",
  "email": "[email protected]",
  "homeTown": "Chicago"
}

Атрибут “тип” не требуется, однако обычно рекомендуется включать атрибут, указывающий тип документа, в случае, если вы решите хранить несколько типов в одном ведре.

4.1. Идентификаторы документов

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

Значения Document id должны быть строками UTF-8 размером 250 или менее байт.

Поскольку Couchbase не предоставляет механизма для автоматической генерации id при вставке, мы должны предоставить свой собственный.

Общие стратегии создания идентификаторов включают вывод ключей с использованием естественного ключа, такого как атрибут “email” , показанный в нашем примере документа, и использование строк UUID .

Для наших примеров мы будем генерировать случайные строки UUID .

4.2. Вставка документа

Прежде чем мы сможем вставить новый документ в нашу корзину, мы должны сначала создать экземпляр JSONObject , содержащий содержимое документа:

JsonObject content = JsonObject.empty()
  .put("name", "John Doe")
  .put("type", "Person")
  .put("email", "[email protected]")
  .put("homeTown", "Chicago");

Затем мы создаем JSON документ объект, состоящий из id значения и JSONObject :

String id = UUID.randomUUID().toString();
JsonDocument document = JsonDocument.create(id, content);

Чтобы добавить новый документ в корзину, мы используем метод insert :

JsonDocument inserted = bucket.insert(document);

Возвращаемый документ Json содержит все свойства исходного документа, а также значение, известное как значение “CAS” (сравнение и замена), которое Couchbase использует для отслеживания версий.

Если документ с предоставленным id уже существует в корзине, Couchbase выдает исключение DocumentAlreadyExistsException .

Мы также можем использовать метод upsert , который либо вставит документ (если id не найден), либо обновит документ (если id найден):

JsonDocument upserted = bucket.upsert(document);

4.3. Получение документа

Чтобы получить документ по его id , мы используем метод get :

JsonDocument retrieved = bucket.get(id);

Если не существует документа с заданным id , метод возвращает null .

4.4. Обновление или замена документа

Мы можем обновить существующий документ с помощью метода upsert :

JsonObject content = document.content();
content.put("homeTown", "Kansas City");
JsonDocument upserted = bucket.upsert(document);

Как мы уже упоминали в разделе 4.2, upsert будет успешным независимо от того, был ли найден документ с заданным id или нет.

Если прошло достаточно времени между тем, как мы первоначально извлекли документ, и нашей попыткой вставить пересмотренный документ, существует вероятность того, что исходный документ будет удален из корзины другим процессом или пользователем.

Если нам нужно защититься от этого сценария в нашем приложении, мы можем вместо этого использовать метод replace , который завершается ошибкой с DocumentDoesNotExistException , если документ с заданным id не найден в Couchbase:

JsonDocument replaced = bucket.replace(document);

4.5. Удаление документа

Чтобы удалить документ Couchbase, мы используем метод remove :

JsonDocument removed = bucket.remove(document);

Вы также можете удалить по id :

JsonDocument removed = bucket.remove(id);

Возвращаемый объект Json Document имеет только набор свойств id и CSS ; все остальные свойства (включая содержимое JSON) удаляются из возвращаемого объекта.

Если не существует документа с заданным id , Couchbase выдает исключение DocumentDoesNotExistException .

5. Работа С Репликами

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

5.1. Виртуальные ведра и Реплики

Couchbase распределяет документы ведра по коллекции из 1024 виртуальных ведер или vbuckets , используя алгоритм хэширования документа id

Каждое ведро Couchbase также может быть сконфигурировано для обслуживания одной или нескольких реплик каждого vbucket . Всякий раз , когда документ вставляется или обновляется и записывается в его корзину , Couchbase инициирует процесс репликации нового или обновленного документа в его реплику vbucket .

В кластере с несколькими узлами Couchbase распределяет ведра и реплики vbuckets между всеми узлами данных в кластере. A vbucket и его реплика vbucket хранятся на отдельных узлах данных для достижения определенной степени высокой доступности.

5.2. Извлечение Документа Из Реплики

При извлечении документа по его id , если основной узел документа не работает или иным образом недоступен из-за сетевой ошибки, Couchbase выдает исключение.

Приложение может перехватить исключение и попытаться получить одну или несколько реплик документа с помощью метода getFromReplica .

Следующий код будет использовать первую найденную реплику:

JsonDocument doc;
try{
    doc = bucket.get(id);
}
catch(CouchbaseException e) {
    List list = bucket.getFromReplica(id, ReplicaMode.FIRST);
    if(!list.isEmpty()) {
        doc = list.get(0);
     }
}

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

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

Также стоит отметить, что Couchbase извлекает реплики (если таковые найдены) асинхронно. Поэтому, если ваша корзина настроена для нескольких реплик, нет никакой гарантии относительно порядка, в котором SDK возвращает их, и вы можете просмотреть все найденные реплики, чтобы убедиться, что ваше приложение имеет последнюю доступную версию реплики:

long maxCasValue = -1;
for(JsonDocument replica : bucket.getFromReplica(id, ReplicaMode.ALL)) {
    if(replica.cas() > maxCasValue) {
        doc = replica;
        maxCasValue = replica.cas();
    }
}

6. Заключение

Мы представили некоторые основные сценарии использования, которые вам понадобятся, чтобы начать работу с Couchbase SDK.

Фрагменты кода, представленные в этом руководстве, можно найти в проекте GitHub .

Вы можете узнать больше о SDK на официальном сайте документации разработчика |/Couchbase SDK .