Creating a Java-Liberty App with Watson AlchemyAPI, CloudantDB and D3js


  • Git
  • Github account
  • Java
  • Eclipse for J2EE
  • WebSphere Liberty with JavaEE7
  • WebSphere Liberty plugin for Eclipse
  • Add * to the WepSphere Liberty Profile (wlp) server’s Java Key Store (JKS)
  • Optional: WAS AdminCenter 1.0
  • Optional: Maven


  1. Create the StarterApp
  2. Add the Toolchain or Continuous Integration (CI)
  3. Setup Localhost
  4. Add JSPs and Servlet for News Search
  5. Add REST API that calls the AlchemyData News API
  6. Save the AlchemyData News Search Results in CloudantDB
  7. Add a D3js Sentiment Score Graph
  8. Configure the CloudantDB for Querying
  9. Show History of Search Results

1. Create the StarterApp

  1. Sign in to,
  2. Go to Catalog,
  3. Under ‘Boilerplates’, click the ‘Java Cloudant Web Starter’,
  4. For ‘App name’ and ‘Host name’ enter ‘<username>-liberty-watson’,
  5. Click the ‘Create’ button,
  6. In ‘Application Details’ click the ‘Overview’ link,
  7. Review the application configuration,
  8. Click ‘Connections’ and click ‘Connect New’ to create the following services:
  9. If no AlchemyAPI service already exists, create a new AlchemyAPI service by clicking the ‘Connect New’ button,
  10. from the Catalog, filter by ‘Watson’, select the AlchemyAPI service, click the ‘Create’ button, and click ‘Restage’
  11. Note: by default you can only create 1 instance of the AlchemyAPI service under your organization in a single space, creating a second instance or connecting an existing service in another space will cause an error. If an instance already exists, click the ‘Connect Existing’ instead, select the existing AlchemyAPI service and click the ‘Connect’ button, click ‘Restage’,

2. Add the Toolchain or Continuous Integration (CI)

  1. Go to the Overview page again, scroll down to ‘Continuous Delivery’,
  2. Under Continuous Delivery click Enable > Create Toolchain > View Toolchain,
  3. Click Delivery Pipeline,
  4. In the Build stage, click the Settings icon > under the Input tab, check to configure build to ‘Run automatically on every Git push’ > and click ‘Save’ or if already checked click ‘Cancel’,
  5. Run the Build stage and review the Deploy stage,
  6. Go back to the Toolchain Overview page,
  7. Click the ‘Code’ icon, which will open the new Github repository,
  8. By default, the newly created Github repository is public. To make the new Github repository private, go to Github and if you have an upgraded account, click Settings > Make Repository private

Change the default Github repository to a fork of the repository used for this tutorial:

  1. Sign in to your Github account, and fork the following repository ‘
  2. Rename the fork to ‘<username>-liberty-watson’ or another repository name unique under your Github account, e.g. ‘<username>-liberty-watson-fork1’,
  3. In your forked repository, click the Code tab, and copy the repository Git URL of the forked repository,
  4. Go back to the Toolchain Overview page, on the Code icon click the dropdown menu, and select ‘Configure’,
  5. In the ‘Source repository URL:’ paste the forked Github repository URL, and click ‘Save Configuration’,
  6. If you want, you can delete the originally created Github repository, under the Settings tab, scroll down to the bottom and click ‘Delete this repository’.

The Toolchain by default comes with an online client IDE service called ‘Eclipse Orion Web IDE’.

  1. Click the Orion icon,
  2. Click the ‘’ to edit and replace all the markdown with the following:
    # A Java WebSphere Application using Watson AlchemyAPI, CloudantDB and D3js
  3. The IDE will auto-save or click > File > Save, or click command-S,
  4. In the left margin, click the Git icon,
  5. Under the ‘Working Directory Changes’, enter the commit message ‘init’ and press the Commit button,
  6. In the left column, under ‘Outgoing’ press the ‘Push’ button,
  7. Click the ‘Back’ icon in the top left margin, and review the results of the Build stage and the Deploy stage,
  8. Verify that the change was pushed to the repository on Github.

3. Setup Localhost

  1. Open a command line and change into your development directory,
    cd dev/src/github
  2. Clone the Github repository to your localhost with the Eclipse Git plugin or Git from a command line, and change into the local clone directory,
  3. git clone<username>/<username>-liberty-watson.git
    cd <username>-liberty-watson

  4. Import the local repository into Eclipse (or your Java IDE), from File > Import… > General > Existing Projects into Workspace > Next > select the cloned repository and click Finish, or
  5. In the Git perspective in Eclipse, right click the repository and click ‘Import Projects’ > Import existing Eclipse projects > Finish,
  6. Go to the Web perspective, open and edit the file
  7. Go back to the Git perspective > Stage all changed files and click the ‘Commit-push to Github’ button > OK
  8. Or use Git from command line
  9. Go to Bluemix, go to the Toolchain Overview page > Toolchain > Delivery Pipeline and check that the Build and Deploy stages run automatically and complete successfully.

To run the application on the WebSphere at localhost:

  1. Right click the project node > Run As > Run on Server
  2. Select ‘Choose an existing server’ and ‘WebSphere Application Server Liberty at Localhost’ and click ‘Next’ and ‘Finish’
  3. You should see the following application run on localhost:

Getting the services configuration:

  1. When running on localhost the application throws a ‘RuntimeException: VCAP_SERVICES not found’, cause it cannot read the VCAP_SERVICES environment variable from Bluemix.
  2. To read the services configuration on localhost and Bluemix, add a Singleton class ‘com.<username>’
  3. Also create a configuration file ‘~/WebContent/WEB-INF/classes/bluemix.json’,
  4. On Bluemix, go to the ‘Application Details’ page > Runtime > ‘Environment Variables’, copy the VCAP_SERVICES json, and paste the json in the bluemix.json file,
  5. Now to get the credentials for the CloudantDB, simply write:
    String user = BluemixConfig.getInstance().getCloudantDBUsername();
    String password = BluemixConfig.getInstance().getCloudantDBPassword();
  6. When you deploy the changes on localhost to Bluemix, Bluemix uses CloudFoundry’s ‘manifest.yml’ file to configure the application and the connections or services.
    In the ‘~/WebContent/WEB-INF/classes/bluemix.json’ look at the ‘name’ properties for each of the services, and edit the ‘services’ property in the ‘manifest.yml’ file, and make sure the ‘host’ and ‘name’ properties are set to the application name in the ‘Application details’:

I will also add the dependencies that we need later already:

  1. Create a new Maven file in the root of the project ‘~/pom.xml’:
  2. From the command line, run the following maven goal to download the required jars:
    mvn dependency:copy-dependencies -DoutputDirectory=target/dependencies
  3. Copy the following jars from ‘~/target/dependencies/’ to ‘~/WebContent/WEB-INF/lib/’ directory:
    • alchemy-3.5.1.jar
    • cloudant-client-2.6.2.jar
    • cloudant-http-2.6.2.jar
    • commons-io-2.5.jar
    • commons-lang3-3.5.jar
    • core-3.5.1.jar
    • gson-2.8.0.jar
    • okhttp-3.4.2.jar
    • okhttp-urlconnection-3.4.1.jar
    • okio-1.11.0.jar
  4. Edit the ‘~/.classpath’ file and add the following classpathentries to the classpath-tag:
  5. Also add the jars to the Ant’s build.xml:

4. Add JSPs and Servlet for News Search

  1. First delete the ‘example.nosql’ package and the 3 Java files in the package, we are not using these,
  2. To replace the default User Interface of the starter application with our own News Search function, edit the ‘~/WebContent/index.html’ file:
  3. Create the following directories: ‘~/WebContent/css’, ‘~/WebContent/js’ and ‘~/WebContent/js/jquery’,
  4. Delete ‘~/WebContent/util.js’ and ‘~/WebContent/index.js’,
  5. Move ‘~/WebContent/style.css’ to ‘~/WebContent/css/’,
  6. Edit the ~/WebContent/css/style.css’ file as follows:
  7. Download the minimized jQuery 3.1.1 from to ‘~/WebContent/js/jquery’,
  8. Download the minimilized JQuery Validate 1.5.1 from to ‘~/WebContent/js/jquery’
  9. Reload the home page on localhost, you should see the following home page:

The jQuery Validation code validates the form input, and if validated it sets the action of the form to the relative URI ‘news’ and then submits the form to the action URI:
$('form#searchform').attr('action', 'news')

Next I will add the results.jsp and the form request handling servlet:

  1. Create a new directory ‘~/WebContent/jsp/’ and add the file ‘~/WebContent/jsp/result.jsp’:
  2. Create a new package in the Java ‘~/src/’ directory, named ‘’ and add a class ‘’:
  3. WebSphere auto-refreshes the Web application, reload the homepage, fill out the form and submit:

5. Add REST API that calls the AlchemyData News API

  1. To process calls to the ‘Watson AlchemyData News API’, I create an internal REST API. In the package ‘’ add a new class ‘’:
  2. Edit the ‘’ and add the call to the internal ‘/watson/news’ REST API:

6. Save the AlchemyData News Search Results in CloudantDB

  1. Create a new package ‘com.<username>.dev.liberty.nosql’ and add a new class ‘’:
  2. Add a new method ‘saveToCloudantDb’ to the
  3. Call the method in the doGet method, right after the ‘build responseJson’ call:
    // Save to CloudantDB
    String cloudantResults = saveToCloudantDb(hosturl, responseJsonArray);
  4. In Bluemix go to the ‘Application Details’ > ‘Connections’, click the ‘Cloudant NoSQL DB’ connection, and click the green ‘LAUNCH’ button,
  5. In the ‘Cloudant Dashboard’, click ‘Databases’ and in the top right of the page, click ‘Create Database’ and for ‘Name of database’ enter: ‘alchemydatanews_searchresults’,
  6. Resubmit the search request, and check in the Cloudant Dashboard that the searchresults were saved to the Cloudant database.

You might need to add * to the WepSphere Liberty Profile (wlp) server’s Java Key Store (JKS):
Go to https://<cloudant-username> and download the certificate.
Use the keytool to import the cloudant certificate:
keytool -import -alias cloudantcert -file * -keystore /Applications/wlp/usr/servers/defaultServer/resources/security/key.jks -storepass mypassword

7. Add a D3js Sentiment Score Graph

  1. D3js is easiest when you return the results in the format of an array of JavsScript objects:
    [ {"publicationDate": 2016-10-01, "sentimentScore": 0.1234},
    {"publicationDate": 2016-10-01, "sentimentScore": 0.2345} ]
  2. Call a new ‘parseToD3jsFormat(responseJsonArray);’ method:
    // Format to D3js
    JsonArray d3jsResponseJsonArray = parseToD3jsFormat(responseJsonArray);
    request.getSession().setAttribute("result", d3jsResponseJsonArray);
  3. Add the new method ‘parseToD3jsFormat’ to the NewsSearchServlet, to format the results for D3js:

Last add the D3js to the ‘~/WebContent/jsp/results.jsp’ file:

  1. Create a new directory ‘~/WebContent/js/d3-v3/’ and save the minimized D3js file to the new ‘d3-v3’ directory,
  2. Create a new file ‘~/WebContent/css/d3js.css’ and add the following css:
  3. Create a new file ‘~/WebContent/js/d3jsgraph.js’ and add the following D3js code:
  4. Edit the ‘~/WebContent/jsp/result.jsp’ file as follows:
  5. Push all changes to Bluemix and review the online application.

8. Configure the CloudantDB for Querying


9. Show History of Search Results


Leave a Reply

Your email address will not be published. Required fields are marked *