Introdução ao SDK do Couchbase para Java
1. Introdução
Nesta introdução ao SDK do Couchbase para Java, demonstramos como interagir com um banco de dados de documentos do Couchbase, cobrindo conceitos básicos como criar um ambiente do Couchbase, conectar-se a um cluster, abrir baldes de dados, usar as operações básicas de persistência e trabalhar com documentos réplicas.
2. Dependências do Maven
Se você estiver usando o Maven, adicione o seguinte ao seu arquivo pom.xml:
com.couchbase.client
java-client
2.2.6
3. Começando
O SDK fornece a interfaceCouchbaseEnvironment e uma classe de implementaçãoDefaultCouchbaseEnvironment contendo configurações padrão para gerenciar o acesso a clusters e depósitos. As configurações do ambiente padrão podem ser substituídas, se necessário, como veremos na seção 3.2.
Important: A documentação oficial do Couchbase SDK alerta os usuários para garantir que apenas umCouchbaseEnvironment esteja ativo na JVM, já que o uso de dois ou mais pode resultar em um comportamento imprevisível.
3.1. Conectando-se a um cluster com um ambiente padrão
Para que o SDK crie automaticamente umCouchbaseEnvironment com configurações padrão e associe-o ao nosso cluster, podemos nos conectar ao cluster simplesmente fornecendo o endereço IP ou nome do host de um ou mais nós no cluster.
Neste exemplo, nos conectamos a um cluster de nó único em nossa estação de trabalho local:
Cluster cluster = CouchbaseCluster.create("localhost");Para conectar-se a um cluster de vários nós, especificamos pelo menos dois nós, caso um deles não esteja disponível quando o aplicativo tentar estabelecer a conexão:
Cluster cluster = CouchbaseCluster.create("192.168.4.1", "192.168.4.2");Note: Não é necessário especificar todos os nós do cluster ao criar a conexão inicial. OCouchbaseEnvironment consultará o cluster assim que a conexão for estabelecida para descobrir os nós restantes (se houver).
3.2. Usando um ambiente personalizado
Se seu aplicativo requer o ajuste fino de qualquer uma das configurações fornecidas porDefaultCouchbaseEnvironment, você pode criar um ambiente personalizado e, em seguida, usar esse ambiente ao se conectar ao seu cluster.
Aqui está um exemplo que se conecta a um cluster de nó único usando umCouchbaseEnvironment personalizado com um tempo limite de conexão de dez segundos e um tempo limite de pesquisa de valor-chave de três segundos:
CouchbaseEnvironment env = DefaultCouchbaseEnvironment.builder()
.connectTimeout(10000)
.kvTimeout(3000)
.build();
Cluster cluster = CouchbaseCluster.create(env, "localhost");E para conectar-se a um cluster de vários nós com o ambiente customizado:
Cluster cluster = CouchbaseCluster.create(env,
"192.168.4.1", "192.168.4.2");3.3. Abrindo um balde
Depois de se conectar ao cluster do Couchbase, você pode abrir um ou mais buckets.
Quando você configura pela primeira vez um cluster Couchbase, o pacote de instalação cria automaticamente um depósito denominado“default” com uma senha em branco.
Esta é uma maneira de abrir o balde“default” quando ele tem uma senha em branco:
Bucket bucket = cluster.openBucket();Você também pode especificar o nome do bloco ao abri-lo:
Bucket bucket = cluster.openBucket("default");Para qualquer outro intervalo com uma senha em branco, vocêmust fornece o nome do intervalo:
Bucket myBucket = cluster.openBucket("myBucket");Para abrir um intervalo que não tenha uma senha em branco, você deve fornecer a senhaand do nome do intervalo:
Bucket bucket = cluster.openBucket("bucketName", "bucketPassword");4. Operações de persistência
Nesta seção, mostramos como executar operações CRUD no Couchbase. Em nossos exemplos, trabalharemos com documentos JSON simples que representam uma pessoa, como neste documento de amostra:
{
"name": "John Doe",
"type": "Person",
"email": "[email protected]",
"homeTown": "Chicago"
}O atributo“type” não é obrigatório, no entanto, é prática comum incluir um atributo especificando o tipo de documento no caso de alguém decidir armazenar vários tipos no mesmo depósito.
4.1. IDs de documentos
Cada documento armazenado no Couchbase está associado a umid que é exclusivo para o depósito no qual o documento está sendo armazenado. O documentoid é análogo à coluna de chave primária em uma linha de banco de dados relacional tradicional.
Os valores deid do documento devem ser strings UTF-8 de 250 ou menos bytes.
Como o Couchbase não fornece um mecanismo para gerar automaticamenteid na inserção, devemos fornecer o nosso próprio.
Estratégias comuns para gerarids incluem derivação de chave usando uma chave natural, como o atributo“email” mostrado em nosso documento de exemplo, e o uso de stringsUUID.
Para nossos exemplos, geraremos stringsUUID aleatórias.
4.2. Inserindo um Documento
Antes de inserir um novo documento em nosso intervalo, devemos primeiro criar uma instância deJSONObject contendo o conteúdo do documento:
JsonObject content = JsonObject.empty()
.put("name", "John Doe")
.put("type", "Person")
.put("email", "[email protected]")
.put("homeTown", "Chicago");A seguir, criamos um objetoJSONDocument que consiste em um valoride oJSONObject:
String id = UUID.randomUUID().toString();
JsonDocument document = JsonDocument.create(id, content);Para adicionar um novo documento ao intervalo, usamos o métodoinsert:
JsonDocument inserted = bucket.insert(document);OJsonDocument retornado contém todas as propriedades do documento original, mais um valor conhecido como o valor“CAS” (comparar e trocar) que o Couchbase usa para rastreamento de versão.
Se um documento comid fornecido já existir no balde, o Couchbase lançará umDocumentAlreadyExistsException.
Também podemos usar o métodoupsert, que irá inserir o documento (seid não for encontrado) ou atualizar o documento (seid for encontrado):
JsonDocument upserted = bucket.upsert(document);4.3. Recuperando um Documento
Para recuperar um documento por seuid, usamos o métodoget:
JsonDocument retrieved = bucket.get(id);Se nenhum documento existir com oid fornecido, o método retornaránull.
4.4. Atualizando ou Substituindo um Documento
Podemos atualizar um documento existente usando o métodoupsert:
JsonObject content = document.content();
content.put("homeTown", "Kansas City");
JsonDocument upserted = bucket.upsert(document);Como mencionamos na seção 4.2,upsert terá êxito quer um documento com oid fornecido tenha sido encontrado ou não.
Se houver tempo suficiente entre o momento em que recuperamos o documento e nossa tentativa de elevar o documento revisado, é possível que o documento original tenha sido excluído do bucket por outro processo ou usuário.
Se precisarmos nos proteger contra esse cenário em nosso aplicativo, podemos usar o métodoreplace, que falha comDocumentDoesNotExistException se um documento com oid fornecido não for encontrado no Couchbase:
JsonDocument replaced = bucket.replace(document);4.5. Excluindo um Documento
Para excluir um documento Couchbase, usamos o métodoremove:
JsonDocument removed = bucket.remove(document);Você também pode remover porid:
JsonDocument removed = bucket.remove(id);O objetoJsonDocument retornado tem apenas as propriedadesideCAS definidas; todas as outras propriedades (incluindo o conteúdo JSON) são removidas do objeto retornado.
Se nenhum documento existir com oid fornecido, o Couchbase lançará umDocumentDoesNotExistException.
5. Trabalho com réplicas
Esta seção discute o balde virtual do Couchbase e a arquitetura de réplica e apresenta um mecanismo para recuperar uma réplica de um documento no caso de o nó primário do documento estar indisponível
5.1. Buckets e réplicas virtuais
O Couchbase distribui os documentos de um balde em uma coleção de 1024 baldes virtuais, ouvbuckets, usando um algoritmo de hash no documentoid para determinar ovbucket no qual armazenar cada documento.
Cada depósito Couchbase também pode ser configurado para manter um ou maisreplicas de cadavbucket. Sempre que um documento é inserido ou atualizado e gravado em seuvbucket, o Couchbase inicia um processo para replicar o documento novo ou atualizado em seureplica vbucket.
Em um cluster de vários nós, o Couchbase distribuivbucketsereplica vbuckets entre todos os nós de dados no cluster. Umvbucket e seureplica vbucket são mantidos em nós de dados separados para atingir uma certa medida de alta disponibilidade.
5.2. Recuperando um documento de uma réplica
Ao recuperar um documento por seuid, se o nó principal do documento estiver inativo ou de outra forma inacessível devido a um erro de rede, Couchbase lança uma exceção.
Você pode fazer seu aplicativo capturar a exceção e tentar recuperar uma ou mais réplicas do documento usando o métodogetFromReplica.
O código a seguir usaria a primeira réplica encontrada:
JsonDocument doc;
try{
doc = bucket.get(id);
}
catch(CouchbaseException e) {
List list = bucket.getFromReplica(id, ReplicaMode.FIRST);
if(!list.isEmpty()) {
doc = list.get(0);
}
} Observe que, ao gravar seu aplicativo, é possível bloquear as operações de gravação até que a persistência e a replicação sejam concluídas. No entanto, a prática mais comum, por razões de desempenho, é fazer com que o aplicativo retorne das gravações imediatamente após gravar na memória do nó primário de um documento, porque as gravações em disco são inerentemente mais lentas do que as gravações na memória.
Ao usar a última abordagem, se o nó primário de um documento atualizado recentemente falhar ou ficar offline antes que as atualizações tenham sido totalmente replicadas, as leituras de réplica podem ou não retornar a versão mais recente do documento.
Também é importante notar que o Couchbase recupera réplicas (se houver alguma) de forma assíncrona. Portanto, se seu bucket estiver configurado para várias réplicas, não há garantia quanto à ordem em que o SDK as devolve e convém percorrer todas as réplicas encontradas para garantir que seu aplicativo tenha a versão de réplica mais recente disponível:
long maxCasValue = -1;
for(JsonDocument replica : bucket.getFromReplica(id, ReplicaMode.ALL)) {
if(replica.cas() > maxCasValue) {
doc = replica;
maxCasValue = replica.cas();
}
}6. Conclusão
Introduzimos alguns cenários básicos de uso necessários para iniciar o SDK do Couchbase.
Os trechos de código apresentados neste tutorial podem ser encontrados emGitHub project.
Você pode aprender mais sobre o SDK noCouchbase SDK developer documentation site oficial.