Введение в Couchbase SDK для Java
1. Вступление
В этом введении в Couchbase SDK для Java мы покажем, как взаимодействовать с базой данных документов Couchbase, включая базовые концепции, такие как создание среды Couchbase, подключение к кластеру, открытие сегментов данных, использование основных операций сохранения и работа с документом. реплики.
2. Maven Зависимости
Если вы используете Maven, добавьте следующее в ваш файл pom.xml:
com.couchbase.client
java-client
2.2.6
3. Начиная
SDK предоставляет интерфейсCouchbaseEnvironment и класс реализацииDefaultCouchbaseEnvironment, содержащий настройки по умолчанию для управления доступом к кластерам и сегментам. Настройки среды по умолчанию могут быть переопределены при необходимости, как мы увидим в разделе 3.2.
Important: Официальная документация 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");Note: Нет необходимости указывать каждый узел в кластере при создании начального соединения. 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, установочный пакет автоматически создает корзину с именем“default” с пустым паролем.
Вот один из способов открыть корзину“default” с пустым паролем:
Bucket bucket = cluster.openBucket();Вы также можете указать название корзины при ее открытии:
Bucket bucket = cluster.openBucket("default");Для любой другой корзины с пустым паролем вы указываетеmust имя корзины:
Bucket myBucket = cluster.openBucket("myBucket");Чтобы открыть сегмент с непустым паролем, необходимо указать имя сегментаand password:
Bucket bucket = cluster.openBucket("bucketName", "bucketPassword");4. Постоянство Операции
В этом разделе мы покажем, как выполнять операции CRUD в Couchbase. В наших примерах мы будем работать с простыми документами JSON, представляющими человека, как в этом примере документа:
{
"name": "John Doe",
"type": "Person",
"email": "[email protected]",
"homeTown": "Chicago"
}Атрибут“type” не требуется, однако обычно включают атрибут, определяющий тип документа, на случай, если кто-то решит хранить несколько типов в одной корзине.
4.1. ID документов
Каждый документ, хранящийся в Couchbase, связан сid, уникальным для сегмента, в котором хранится документ. Документid аналогичен столбцу первичного ключа в строке традиционной реляционной базы данных.
Значения документаid должны быть строками UTF-8 размером 250 или меньше байтов.
Поскольку Couchbase не предоставляет механизма для автоматической генерацииid при вставке, мы должны предоставить свои собственные.
Общие стратегии генерацииids включают создание ключа с использованием естественного ключа, такого как атрибут“email”, показанный в нашем образце документа, и использование строкUUID.
В наших примерах мы будем генерировать случайные строкиUUID.
4.2. Вставка документа
Прежде чем мы сможем вставить новый документ в нашу корзину, мы должны сначала создать экземплярJSONObject, содержащий содержимое документа:
JsonObject content = JsonObject.empty()
.put("name", "John Doe")
.put("type", "Person")
.put("email", "[email protected]")
.put("homeTown", "Chicago");Затем мы создаем объектJSONDocument, состоящий из значенияid иJSONObject:
String id = UUID.randomUUID().toString();
JsonDocument document = JsonDocument.create(id, content);Чтобы добавить новый документ в корзину, мы используем методinsert:
JsonDocument inserted = bucket.insert(document);ВозвращаемыйJsonDocument содержит все свойства исходного документа, а также значение, известное как значение“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);У возвращенного объектаJsonDocument установлены только свойстваid иCAS; все остальные свойства (включая содержимое JSON) удаляются из возвращаемого объекта.
Если нет документа с заданнымid, Couchbase выдаетDocumentDoesNotExistException.
5. Работа с репликами
В этом разделе обсуждается виртуальная корзина и архитектура реплик Couchbase, а также вводится механизм для получения реплики документа в случае, если основной узел документа недоступен.
5.1. Виртуальные корзины и реплики
Couchbase распределяет документы корзины по коллекции из 1024 виртуальных корзин, илиvbuckets, используя алгоритм хеширования для документаid, чтобы определитьvbucket для хранения каждого документа.
Каждую корзину Couchbase также можно настроить для поддержания одного или несколькихreplicas каждогоvbucket. Всякий раз, когда документ вставляется или обновляется и записывается в егоvbucket, Couchbase инициирует процесс репликации нового или обновленного документа в егоreplica vbucket.
В многоузловом кластере Couchbase распределяетvbuckets иreplica vbuckets среди всех узлов данных в кластере. vbucket и егоreplica 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 project.
Вы можете узнать больше о SDK на официальном сайтеCouchbase SDK developer documentation site.