El equipo de Experiencia para Desarrolladores de Couchbase se dedica a proporcionar a los usuarios de Couchbase un rico ecosistema de código abierto para sus clústeres. Recientemente, hemos estado trabajando para actualizar la integración de Alpakka Couchbase con soporte para las últimas funciones de Couchbase Server.
La integración actualizada de Couchbase está disponible como parte de la versión 10.0.1 de Alpakka. En esta publicación, revisaremos un proyecto sencillo que utiliza el conjunto de datos “travel-sample” para ofrecer una descripción general del uso básico de la integración y sus componentes.
La información más completa sobre la integración y su API, incluidos ejemplos de uso adicionales, se puede encontrar en la documentación de Alpakka: https://doc.akka.io/libraries/alpakka/current/couchbase.html
Requisitos previos
- Clúster Couchbase con cubeta travel-sample
- CLI de Akka
- Java 21, Eclipse Adoptium recomendado por los desarrolladores de Akka
- Apache Maven versión 3.9 o posterior
- rizo herramienta de línea de comandos
- Git o GitHub Desktop
Nota: Las dependencias de Akka están disponibles en el repositorio seguro de bibliotecas de Akka. Para acceder a ellas, es necesario utilizar una URL segura y tokenizada, tal y como se especifica en https://account.akka.io/token.
Para demostrar el uso de Couchbase en Alpakka, el proyecto utiliza el conjunto de datos travel-sample, que se puede añadir a cualquier clúster de Couchbase desde su configuración. Se puede encontrar más información al respecto en la documentación de Couchbase: https://docs.couchbase.com/java-sdk/current/ref/travel-app-data-model.html
El proyecto de ejemplo implementa dos puntos finales. Uno de ellos nos permite buscar aeropuertos por ciudad, país, nombre del aeropuerto o sus códigos internacionales, y el otro devuelve información completa sobre un aeropuerto por su identificador.
El código fuente de nuestro proyecto de ejemplo se puede encontrar en esta URL: https://github.com/couchbaselabs/alpakka-example
El siguiente comando se puede utilizar para clonarlo con git:
clonar git https://github.com/couchbaselabs/alpakka-example.git
Descripción general de Alpakka
En Proyecto Alpakka es una iniciativa para implementar canalizaciones de integración reactivas y sensibles al flujo para Java y Scala. Se basa en Akka Streams, y ha sido diseñado desde cero para comprender el streaming de forma nativa y proporcionar un DSL para la programación reactiva y orientada al streaming, con soporte integrado para la contrapresión.
Akka Streams se estructura en torno a tres componentes principales: Source, Sink y Flow. Una Source emite datos, una Sink los consume y un Flow transforma los datos a medida que se mueven a través del flujo, lo que permite un procesamiento eficiente y asíncrono.
Nuestra integración proporciona los tres tipos de componentes:
- El componente CouchbaseSource realiza consultas Couchbase SQL++ y utiliza los resultados como fuente de datos en un flujo.
- CouchbaseFlow recupera documentos por sus identificadores, y también los actualiza, reemplaza y elimina.
- CouchbaseSink proporciona conjuntos de operaciones CouchbaseFlow similares que se pueden utilizar como último paso en un flujo.
Configuración de Alpakka-Couchbase
El código fuente del proyecto contiene el archivo src/main/recursos/aplicación.conf con la siguiente configuración de Couchbase:
|
1 2 3 4 5 6 7 |
alpakka.couchbase { session { nodes = ["localhost"] username = "Administrator" password = "password" } } |
Esta configuración debería funcionar con un clúster de desarrolladores de un solo nodo que utilice la configuración predeterminada y se ejecute en la misma máquina que la aplicación Alpakka. También se puede modificar con las credenciales de un clúster alojado en la nube de Couchbase Capella. Para obtener más información sobre las credenciales y la conexión a Couchbase, consulte Couchbase Capella (https://docs.couchbase.com/cloud/get-started/connect.html) y Couchbase Server (https://docs.couchbase.com/server/current/guides/connect.html#connecting-via-client) documentación.
Controlador de aeropuerto
El código de ejemplo que interactúa con una conexión Couchbase configurada se puede encontrar en el Controlador de Aeropuerto clase, ubicada en src/main/java/travelsample/api/Controlador del Aeropuerto.java.La integración de Alpakka-Couchbase utiliza Configuración de sesión de Couchbase objetos para hacer referencia a conexiones Couchbase específicas. El objeto de configuración de sesión se puede reutilizar entre diferentes puntos finales y actores, por lo que se crea en el constructor del controlador y se almacena en un campo:
|
1 2 3 4 |
public AirportController(ActorSystem system) { sessionSettings = CouchbaseSessionSettings.create(system) .withEnrichAsyncCs(DiscoverySupport.getNodes(system)); } |
En buscarAeropuerto El método de esta clase implementa el /search?query= punto final y muestra el uso de SQL++ con argumentos posicionales en Alpakka:
|
1 2 3 4 5 6 7 |
String searchTerm = requestContext().queryParams().getString("query").orElseThrow(); return CouchbaseSource.fromQuery( sessionSettings, "travel-sample", "SELECT * FROM inventory.airport where airportname LIKE '%' $1 '%' OR faa = $1 or icao = $1 or city LIKE '%' $1 '%'", QueryOptions.queryOptions().parameters(JsonArray.from(searchTerm) )).runWith(Sink.seq(), system).toCompletableFuture().get(TIMEOUT, TimeUnit.SECONDS); |
Para realizar una consulta SQL++, primero creamos una instancia de Fuente: Couchbase y configúrela con la información necesaria para conectarse al clúster (sessionSettings), la consulta que queremos ejecutar y los argumentos para esa consulta pasados como un objeto QueryOptions. Se admiten tanto argumentos posicionales como nombrados, según la documentación del SDK de Java de Couchbase para el Opciones de consulta clase.
A continuación, utilizamos Alpakka's runSink método en la fuente creada para ejecutar la consulta y extraer sus resultados como un flujo de objetos.
El segundo método del controlador, getById, implementa el /porId/{id} Punto final, que toma un identificador de aeropuerto y devuelve información sobre un aeropuerto almacenada en un documento con ese identificador.
|
1 2 3 4 5 6 7 8 9 10 11 |
return Source.from(Collections.singletonList(id)) .via(CouchbaseFlow.fromId( sessionSettings, "travel-sample", "inventory", "Airport" )) .runWith(Sink.seq(), system) .thenApply(List::getFirst) .thenApply(CouchbaseDocument::getDocument) .toCompletableFuture().get(TIMEOUT, TimeUnit.SECONDS); |
Podemos usar Alpakka's Fuente: de método con una lista única que contiene el identificador solicitado para crear una instancia de origen.
Luego utilizamos el Fuente: vía método para enrutar la fuente de flujo Akka (en este caso, un único identificador) a través de un CouchbaseFlow objeto que está configurado de manera similar al Fuente: Couchbase clase en el buscarAeropuerto método. La instancia de CouchbaseFlow aceptará el identificador solicitado del flujo, obtendrá el documento correspondiente de la colección configurada y lo devolverá al flujo, sustituyendo el identificador por una instancia de Documento Couchbase objeto, que contiene tanto el identificador como el documento asociado.
Combinación de CouchbaseSink, CouchbaseFlow, y otros objetos Couchbase documentados como pasos en los flujos Akka junto con actores de otros componentes Alpakka, permiten crear canalizaciones que pueden utilizar Couchbase para almacenar y recuperar información, así como utilizar sus potentes funciones de análisis y búsqueda.
Documentación y seguimiento de incidencias
La documentación de Alpakka (https://doc.akka.io/libraries/alpakka/current/couchbase.html) contiene más información sobre cómo utilizar esta integración, incluyendo upserting, modificar y borrar documentos en un clúster de Couchbase.
Cualquier sugerencia sobre la integración o cualquier problema relacionado con ella puede compartirse a través de la Página de problemas de Alpakka en GitHub.
