Configuring advanced capabilities of the Cloudant driver

You can use the advanced capabilities of the Cloudant Java client on Liberty.

1. If your server is running with Java 2 security enabled, permissions must be granted to the cloudant client library.

   For example, in server.xml, you can specify:

   <javaPermission codebase="${shared.resource.dir}cloudant/cloudant-client-2.2.0.jar" className="java.security.AllPermission"/>

2. Create a default container authentication alias element in the server.xml file to provide a user name and password to be used to authenticate with the database.

   <cloudant ... containerAuthDataRef="cadr"/>
   <authData id="cadr" user="username" password="password"/>

   Tip: Instead of specifying a default container authentication alias, you can use the user name and password attributes of the cloudant element. For more information, see Liberty: The limits to protection through password encryption to learn about how to secure passwords in configuration files.
3. The application can specify a container managed authentication alias per resource reference in the bindings. The value that is specified as the authentication alias must be the ID of an authData element in the server configuration.

   For example, in ibm-web-bnd.xml, you can specify:

   <resource-ref name="java:module/env/cloudant/testDBRef" binding-name="cloudant/testDB">
     <authentication-alias name="cadr"/> 
   </resource-ref>

4. If you want to use unmanaged Cloudant resources in your application, the cloudant-1.0 feature does not need to be enabled, nor any cloudant or cloudantDatabase elements added in the server.xml.

   When you use unmanaged Cloudant, the Cloudant libraries might be packaged directly in the application, or a library can be configured in the server.xml:

   <library name="cloudantLib"> 
     <fileset dir="${shared.resource.dir}cloudant"
              includes="cloudant-client-2.2.0.jar commons-codec-1.6.jar commons-io-2.4.jar gson-2.2.4.jar"/>
   </library>
   <application ...> 
    <classloader commonLibraryRef="cloudantLib"/>
   </application>

5. If a JNDI name is specified on a cloudant configuration element, you can inject or lookup the ClientBuilder that you configured by using the cloudant configuration element.

   <cloudant id="builder" jndiName="cloudant/builder" ... />

   An example of an inject or lookup for a ClientBuilder that was configured by using the cloudant configuration element.

   import com.cloudant.client.api.*; 
   //...
            
   @Resource(lookup="cloudant/builder", name="cloudant/resRef")
   ClientBuilder builder; 
   
   public void useInjectedBuilder() {       
       CloudantClient client = builder.build(); 
       Database db = client.database("somedb", true);
       // use the db ... 
       // Shutdown the connection manager for this client when you are done with it 
       // note that this renders the CloudantClient instance unusable after this point       
       client.shutdown(); 
   } 
   
   public void useBuilderLookup() throws NamingException { 
       ClientBuilder builder = (ClientBuilder) new InitialContext().lookup("java:comp/env/cloudant/resRef");  
       CloudantClient client = builder.build();
       Database db = client.database("somedb",true);
       // use the db ... 
       // Shutdown the connection manager for this client when you are done with it
       // note that this renders the CloudantClient instance unusable after this point       
       client.shutdown(); 
   }