-
Notifications
You must be signed in to change notification settings - Fork 72
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4153 from OpenLiberty/cloudant_4152
Created cloudant-with-open-liberty.adoc
- Loading branch information
Showing
1 changed file
with
170 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,170 @@ | ||
| --- | ||
| layout: post | ||
| title: "Access Cloudant client with Open Liberty using CDI" | ||
| categories: blog | ||
| author_picture: https://avatars3.githubusercontent.com/revijay | ||
| author_github: https://github.com/revijay | ||
| seo-title: Access Cloudant client 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. Now, with improvements in CDI and the introduction of MicroProfile Config, you can easily configure access to Cloudant with a CDI producer. Earlier cloudant-1.0 feature was implemented using Java Cloudant Client library which is not under active development now, so in this demonstration we are using Cloudant Java SDK library. | ||
| blog_description: "Using Cloudant with Open Liberty previously meant enabling the cloudant-1.0 feature and configuring several elements in server.xml. Now, with improvements in CDI and the introduction of MicroProfile Config, you can easily configure access to Cloudant with a CDI producer. Earlier cloudant-1.0 feature was implemented using Java Cloudant Client library which is not under active development now, so in this demonstration we are using Cloudant Java SDK library." | ||
| 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: / | ||
|
|
||
| Using Cloudant with Open Liberty previously meant enabling the `cloudant-1.0` feature and configuring several elements in ``server.xml``. Now, with improvements in CDI and the introduction of 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]). Earlier cloudant-1.0 feature was implemented using Java Cloudant Client library which is not under active development now, so in this demonstration we are using Cloudant Java SDK library. | ||
|
|
||
| == 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).This example demonstrates how to create a CDI producer to inject a Cloudant client: | ||
| [source, java] | ||
| ---- | ||
| @ApplicationScoped | ||
| public class CloudantProducer { | ||
| @Produces | ||
| public Cloudant createCloudant() { | ||
| return new Cloudant(“cloudant”, new BasicAuthenticator.Builder().build()); | ||
| } | ||
| } | ||
| ---- | ||
|
|
||
| Here is an example of using the CDI producer to inject a Cloudant client in a JAX-RS application. | ||
| [source, java] | ||
| ---- | ||
| @Inject | ||
| Cloudant client; | ||
| @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 `postDocument` method demonstrates how to create and post a document in the cloudant database using the injected CloudantClient. | ||
|
|
||
| == Enhancing the CDI producer | ||
| One of the advantages of using a CDI producer is that it can be tailored to your needs. For improved security,the `createCloudant` method can be enhanced to include authentication with a user name and password: | ||
|
|
||
| [source,java] | ||
| ---- | ||
| @Produces | ||
| public Cloudant createCloudant() { | ||
| String password = PasswordUtil.passwordDecode(encodedPassword); | ||
| BasicAuthenticator authenticator = new BasicAuthenticator.Builder() | ||
| .username(username) | ||
| .password(password) | ||
| .build(); | ||
| return new Cloudant("cloudant", authenticator); | ||
| } | ||
| ---- | ||
| This requires `passwordUtilities-1.0`, available as a Maven dependency: | ||
| [source,xml] | ||
| ---- | ||
| <dependency> | ||
| <groupId>io.openliberty.features</groupId> | ||
| <artifactId>passwordUtilities-1.0</artifactId> | ||
| <version>18.0.0.4</version> | ||
| </dependency> | ||
| ---- | ||
|
|
||
| You also need to enable the feature in `server.xml`: | ||
| [source, xml] | ||
| ---- | ||
| <feature>passwordUtilities-1.0</feature> | ||
| ---- | ||
|
|
||
| By default, Cloudant communication occurs over HTTPS (SSL). However, if you're working with a custom Cloudant instance or self-signed certificates, you may need to configure your Open Liberty application to trust the custom certificate. | ||
|
|
||
| You can configure SSL by modifying the server.xml to use your custom SSL certificates: | ||
| [source, xml] | ||
| ---- | ||
| <sslRegistry id="defaultSSLConfig"> | ||
| <keyStore file="path/to/keystore.jks" password="password"/> | ||
| <trustStore file="path/to/truststore.jks" password="password"/> | ||
| </sslRegistry> | ||
| <httpEndpoint host="*" httpPort="9080" httpsPort="9443" sslConfigRef="defaultSSLConfig"/> | ||
| ---- | ||
|
|
||
| == Configure with MicroProfile Config | ||
| Now that you have a more advanced CDI producer, it would be nice to add configurability to some of the variables, like the user and password. Using link:{url-prefix}/guides/microprofile-config-intro.html[MicroProfile Config] makes configuring the Cloudant driver simple. You can add the following to your CDI producer to add configuration: | ||
| [source, java] | ||
| ---- | ||
| @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 password; | ||
| @Inject | ||
| @ConfigProperty(name = "cloudant.dbname") | ||
| String dbname; | ||
| ---- | ||
| 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 | ||
| ---- | ||
| == No need for a Cloudant feature | ||
| Previously, using Cloudant required enabling the `cloudant-1.0` feature. Even if the Cloudant Java Driver 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 newer versions of Cloudant with a CDI producer. | ||
|
|
||
| The Cloudant client 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 client library, 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> | ||
| ---- | ||
|
|
||
| This illustrates how easy it is to create a CDI producer for Cloudant, and configure it with MicroProfile Config that help you to 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] |