Created blog file cloudant-with-open-liberty.adoc

posts/2024-11-25-cloudant-with-open-liberty.adoc

@@ -0,0 +1,225 @@
+---
+layout: post
+title: "Access Cloudant with Open Liberty using CDI"
+categories: blog
+author_picture: https://avatars3.githubusercontent.com/revijay
+author_github: https://github.com/revijay
+seo-title: Access Cloudant with Open Liberty using CDI - OpenLiberty.io
+seo-description: Using Cloudant with Open Liberty previously meant enabling the cloudant-1.0 feature and configuring several elements in server.xml. With CDI and MicroProfile Config, you can easily configure access to Cloudant with a CDI producer. The cloudant-1.0 feature was implemented using Java Cloudant Client library which is no longer supported, so in this demonstration we are using the new Cloudant SDK for Java.
+blog_description: "Using Cloudant with Open Liberty previously meant enabling the cloudant-1.0 feature and configuring several elements in server.xml. With CDI and MicroProfile Config, you can easily configure access to Cloudant with a CDI producer. The cloudant-1.0 feature was implemented using Java Cloudant Client library which is no longer supported, so in this demonstration we are using the new Cloudant SDK for Java."
+open-graph-image: https://openliberty.io/img/twitter_card.jpg
+open-graph-image-alt: Open Liberty Logo
+---
+= Access Cloudant client with Open Liberty using CDI
+Reshmi Vijayan <https://github.com/revijay>
+:imagesdir: /
+:url-prefix:
+:url-about: /
+
+Cloudant, an IBM-managed NoSQL database built on top of Apache CouchDB, provides a powerful solution for document-oriented storage with high availability and scalability. Cloudant provides a robust, flexible, and highly scalable NoSQL database solution that is tailor-made for cloud-native applications. Cloudant with Open Liberty offers a seamless way to build, deploy, and scale your Java applications with efficient, scalable data storage.
+
+Using Cloudant with Open Liberty previously meant enabling the `cloudant-1.0` feature and configuring several elements in ``server.xml``. With CDI and MicroProfile Config,  you can easily configure access to Cloudant with a CDI producer (for an introduction to using CDI producers, see the https://openliberty.io/guides/cdi-intro.html[Injecting Dependencies into Microservices guide]). The cloudant-1.0 feature was implemented using Java Cloudant Client library which is no longer supported, so in this demonstration we are using the new Cloudant SDK for Java.
+
+== A CDI producer for Cloudant
+With a CDI producer, you can easily provide a Cloudant client to your application by which you can inject the client into various parts of the application in a type-safe and flexible way, while leveraging the benefits of dependency injection (such as lifecycle management and configuration). Also, we are using link:{url-prefix}/guides/microprofile-config-intro.html[MicroProfile Config] to make the configuration of Cloudant driver simple. 
+This example demonstrates how to create a CDI producer to inject a Cloudant client:
+[source, java]
+----
+@ApplicationScoped
+public class CloudantProducer {
+
+    @Inject
+    @ConfigProperty(name = "cloudant.host", defaultValue = "localhost")
+    String host;
+
+    @Inject
+    @ConfigProperty(name = "cloudant.port", defaultValue = "5984")
+    String port;
+
+    @Inject
+    @ConfigProperty(name = "cloudant.username")
+    String username;
+
+    @Inject
+    @ConfigProperty(name = "cloudant.password")
+    String encodedPassword;
+
+    @Produces
+    public Cloudant createCloudant() {
+        String password = PasswordUtil.passwordDecode(encodedPassword);
+        BasicAuthenticator authenticator = new BasicAuthenticator.Builder()
+                .username(username)
+                .password(password)
+                .build();
+
+        Cloudant service = new Cloudant("cloudant", authenticator);
+        service.setServiceUrl("http://" + host + ":" + port);
+
+        return service;
+    }
+}
+----
+One of the advantages of using a CDI producer is that it can be tailored to your needs. For improved security,the createCloudant method uses Open Liberty's password decoding. This requires the following Maven dependency:
+[source,xml]
+----
+<dependency>
+    <groupId>com.ibm.websphere.appserver.api</groupId>
+    <artifactId>com.ibm.websphere.appserver.api.passwordUtil</artifactId>
+    <version>1.0.95</version>
+</dependency>
+----
+You also need to enable the feature in `server.xml`:
+[source, xml]
+----
+<feature>passwordUtilities-1.0</feature>
+----
+Now, by placing the following snippet in your ``microprofile-config.properties`` or `server.env` file, the values for user and password will be pulled into the CloudantProducer class:
+[source, text]
+----
+cloudant.user=admin
+cloudant.password={aes}AEEjCqvh7XAwDxrdYC6BUbqYlwqI8NAxRkWWWq7muxZu
+cloudant.dbname=testdb
+----
+
+Instead of using `BasicAuthentication` with a username and password, Cloudant also supports `IAM (Identity and Access Management)` authentication, which allows users and applications to authenticate using secure API keys or IAM tokens. By using IAM authentication, we can avoid the risks associated with managing passwords and ensure that only authorized entities can interact with Cloudant databases.
+Follow the https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-getting-started-with-cloudant&_ga=2.42518757.1165320250.1604321683-1614077795.1594908456[IBM Cloudant Setup] guide to create a Cloudant instance and API key for accessing it.
+
+The code snippet below shows how can we create a CDI Producer to inject a Cloudant client with IAM authentication.
+[source, java]
+----
+@ApplicationScoped
+public class CloudantProducer {
+
+    @Inject
+    @ConfigProperty(name = "cloudant.host", defaultValue = "localhost")
+    String host;
+
+    @Inject
+    @ConfigProperty(name = "cloudant.port", defaultValue = "5984")
+    String port;
+
+    @Inject
+    @ConfigProperty(name = "cloudant.apikey")
+    String apikey;
+
+    @Produces
+    public Cloudant createCloudant() {
+        IamAuthenticator authenticator = new IamAuthenticator.Builder()
+    		    .apikey("apikey")
+    		    .build();
+
+        Cloudant service = new Cloudant("cloudant", authenticator);
+        service.setServiceUrl("http://" + host + ":" + port);
+
+        return service;
+    }
+}
+----
+
+== Injecting the Cloudant client
+Here is an example of using the CDI producer to inject a Cloudant client in a JAX-RS application. 
+[source, java]
+----
+@Inject
+Cloudant client;
+
+@Inject
+@ConfigProperty(name = "cloudant.dbname")
+String dbname;
+
+@POST
+@Path("/add")
+@Consumes(MediaType.APPLICATION_JSON)
+public void add(CrewMember crewMember) {
+        Document newCrewMember = new Document();			 
+        newCrewMember.put("Name",crewMember.getName());
+        newCrewMember.put("Rank",crewMember.getRank());
+        newCrewMember.put("CrewID",crewMember.getCrewID());
+
+        PostDocumentOptions createDocumentOptions =
+                    new PostDocumentOptions.Builder()
+                        .db(dbname)
+                        .document(newCrewMember)
+                        .build();
+        DocumentResult createDocumentResponse = client
+                    	.postDocument(createDocumentOptions)
+                        .execute()
+                   	    .getResult();
+}
+----
+
+In the above code:
+
+* `@Inject` is used to inject the Cloudant client instance provided by the CDI producer.
+* The `PostDocumentOptions` is a builder class that allows you to specify various options when posting the document. You must provide the db name and the document content.
+* The `postDocument` is the main method that posts the document to the specified database. It returns a DocumentResult object which contains metadata about the inserted document (like its _id and _rev).
+
+Similarly, we can delete a document from Cloudant using its `id`.
+[source, java]
+----
+@DELETE
+@Path("/{id}")
+public String remove(@PathParam("id") String id) {
+	GetDocumentOptions documentInfoOptions =
+            new GetDocumentOptions.Builder()
+                .db(dbname)
+                .docId(id)
+                .build();
+
+    Document document = client
+                .getDocument(documentInfoOptions)
+                .execute()
+                .getResult();
+
+    DeleteDocumentOptions deleteDocumentOptions =
+                new DeleteDocumentOptions.Builder()
+                .db(dbname)
+                .docId(id)   
+                .rev(document.getRev())
+                .build();
+
+    DocumentResult deleteDocumentResponse = client
+                .deleteDocument(deleteDocumentOptions)
+                .execute()
+                .getResult();
+}
+----
+In the above example:
+
+* The `GetDocumentOptions` class is used to configure parameters for retrieving a document from a Cloudant database. It allows you to specify the database name, document ID, and optional parameters like the document revision, whether to include attachments, conflicts, or deleted information in the response. The class uses the builder pattern to set these options before making the request to Cloudant.
+* The `DeleteDocumentOptions` class is used to configure parameters for deleting a document from a Cloudant database. It allows you to specify the database name, the document ID, and the revision (_rev) of the document to ensure that the correct version is deleted (to prevent race conditions). This class uses the builder pattern to set options before sending the delete request to Cloudant.
+
+== No need for a Cloudant feature
+Previously, using Cloudant required enabling the `cloudant-1.0` feature.  Even if the Cloudant SDK for Java's API changes, simple updates to your CDI producer will allow it to continue to work. You should remove the `cloudant-1.0` feature from your `server.xml` when using the new Cloudant SDK for Java.
+
+The Cloudant SDK for Java should be bundled in your application. To do this with Maven you can use a dependency:
+
+[source, xml]
+----
+<dependency>
+    <groupId>com.ibm.cloud</groupId>
+    <artifactId>cloudant</artifactId>
+    <version>x.x.x</version>
+</dependency> 
+----
+If you have multiple applications accessing Cloudant, instead of bundling the Cloudant SDK for Java with each application, you can configure a shared library in your `server.xml` like this:
+[source, xml]
+----
+<library id="cloudantLib">
+  <file name="${shared.resource.dir}/cloudant-x.x.x.jar" />
+</library>
+
+<application contextRoot="/" location="app1.war">
+    <classloader sharedLibraryRef="cloudantLib"/>
+</application>
+
+<application contextRoot="/app2" location="app2.war">
+    <classloader sharedLibraryRef="cloudantLib"/>
+</application>
+----
+
+== Summary
+In this blog post, we explored how easy it is to create a CDI producer for Cloudant, and configure it with MicroProfile Config to help integrate Cloudant into an Open Liberty-based Java application, leveraging the power of Cloudant's NoSQL database with the flexibility of Open Liberty’s lightweight, cloud-native architecture.
+The full sample is available on GitHub here: link:https://github.com/OpenLiberty/sample-cloudant[https://github.com/OpenLiberty/sample-cloudant].
+
+By combining the strengths of Cloudant and Open Liberty, developers can create powerful, cloud-native applications that are both flexible and scalable, with minimal infrastructure management. This integration ensures real-time data access, robust data storage, and seamless scaling—all essential for modern, data-driven applications in the cloud.