Leverage Watson Java SDK from Play Application
As a Software Engineer and Dev Advocate for IBM Cloud and Watson platform, we are always looking for new ways to build cloud-native cognitive solution leveraging IBM Watson Platform in collaboration with external technologies. I am really excited about this morning’s announcement from IBM regarding a new collaborative development initiative with Lightbend. The joint effort will provide developers a single stop solution for building and deploying distributed cognitive application both on premises and in the cloud.
Although I use IBM Cloud & Watson Platform day in and day out, I haven’t really worked on Lightbend Reactive Platform that comprises of Akka, Play and Lagom. As a developer, the best way to find out is to start building something simple out of those technologies and take it from there. The rest of the blog discusses the technical recipes involved to add a cognitive capability into Java based Play application with the help of online documentation and other resources about Lightbend Reactive Platform. For the purpose of this blog, we will use Watson Java SDK from within the Play application to add the cognitive capability.
The sample project for this blog post is available in Github.
First, let’s review the architecture.
The play application exposes following REST endpoints:
/imageClassification?imageUrl=<image_url>
classify an image i.e. identify objects in an image leveraging Watson Visual Recognition. Watson Visual Recognition enables developer to classify image content using machine learning.
/translation?text=<text>&from=<source_langauge>&to=<target_langauge>
translates given text to target language using Watson Lanugage Translator
In the above application, each asynchronous call to a watson cognitive service is encapsulated to an Akka Actor. Actor is capable of much more than just encapsulating a behavior to process a message that it receives. For more details on Akka Actor, I would recommend going though the following doc. The following talk from Jonas Bonér provides a great explanation on Akka Actor from the perspective of reactive system.
Get Started
The following starter project is a great way to get started with Java based Play application. You can clone the project and import into your IDE (Intellij, Eclipse..) of your choice. For details on how to import the project into your IDE, take a look the the following doc. Once you follow the steps, you should be able to run/debug the application from your IDE.
Add Watson Java SDK Dependency
In order to add a dependency to Watson Visual Recognition and Language, we will add the dependencies to Java SDK for Visual Recognition Service and Language Translator Service in the build.sbt file as shown below.
Add Watson Credentials to the Application Settings
Follow the steps provided in the following link to obtain the credentials of the services (Visual Recognition & Language Translator) for the project. Then create a watson.conf file under the conf directory of the starter project where we will specify the service credentials/key as shown below.
We will then import the watson.conf file in the application.conf file as shown below.
include "watson.conf"You can find detail information on the Akka configuration from the following link. http://doc.akka.io/docs/akka/2.5.3/java/general/configuration.html
As recommended by the Akka doc, we will place application specific settings in an Extension.
For that, we will create SettingsImpl.java class under the package settings as shown below.
Add Settings.java class as well under the package settings as shown below:
We will later use the application settings defined in configuration file through SettingsImpl & Settings classes in Actors.
Define Actors
We will create Actor that encapsulates behavior of corresponding Watson Service. Below is a visual recognition actor that given an image url, will classify the image and detect faces in the image using Watson Java SDK for visual recognition.
Notice here that the ImageClassifier defines a static method called getProps, this method returns a Props object that describes how to create the actor. This is a good Akka convention, to separate the instantiation logic from the code that creates the actor. Another best practice shown here is that the messages that ImageClassifier receives are defined as static inner classes called Message. It serves as a protocol of the message to send to the ImageClassifier actor. All the details on the Akka Actor can be read from the following doc.
http://doc.akka.io/docs/akka/current/java/actors.html
I am using the pattern matching for the received message in the Actor on line 34 to handle the Message. Under the implementation of the in-line message handler, I am using Watson Java SDK for Visual Recognition to recognize the object(s) in the image.
I was blown away by the Actor API design backed by strong documentation while working on this project. The functional approach to the API design made things lot simpler to write. The documentation is well writtern and provides various recommended practices for different situations when developing Actors. I would highly recommend going through the doc when getting started.
Define REST Endpoint
Now that we have defined an Actor and encapsulated a behavior, we can now create a REST endpoint for client to consume Actor’s behavior over the web through HTTP Request. We can create a REST Endpoint by defining a Controller that creates and uses the ImageClassifier actor.
The ActorSystem is used to create and/or use an actor. The basic functionality available with Actor is to send a message for computation or processing. There are two patterns for that:
- tell pattern (Fire-forget) where there is no response from actor. I would recommend reading the following doc on tell pattern:
http://doc.akka.io/docs/akka/current/java/actors.html#tell-fire-forget - ask pattern (Send-And-Receive-Future) where actor sends response. This pattern is used when sending message to actor from a REST endpoint where client expects the response.
I would recommend reading the following doc on the ask pattern:
http://doc.akka.io/docs/akka/current/java/actors.html#ask-send-and-receive-future
Add Routes
The final step is to add routes for the rest endpoint. Add the following route in routes file for image classification as shown below:
Here we have created a REST endpoint /imageClassification that can be accessed by GET method and it requires a query parameter called imageUrl. For more details on routing, you can read the following doc.
Test REST endpoint with curl command
Now we can run the play application and test image classification REST endpoint through following command:
You will see the following response message in the console:
Conclusion
All in all, I had fun trying this out since my goal was to get something up and running in a quick time. Akka & Play are mature frameworks widely used in the industry and backed by strong documentation and developer community. That really helped me to get my hands dirty in quick time and be able to build a simple application. Although, the recipe may not be the production ready but it did help me to understand the bits and pieces of Lightbend Reactive Platform and gave me a good foundation take it to the next level.
Resources
https://github.com/pkhanal/lightbend-watson-integration http://doc.akka.io/docs/akka/current/java/actors.html https://www.playframework.com/documentation/2.5.x/IDE https://www.playframework.com/documentation/2.6.x/JavaAkka https://www.ibm.com/watson/developercloud/visual-recognition.html https://www.ibm.com/watson/developercloud/language-translator.html
Originally published at pkhanal.github.io.
