Watson Developer Cloud Java SDK

The Java SDK uses the Watson Developer Cloud services, a collection of REST APIs and SDKs that use cognitive computing to solve complex problems.

Introduce reactive API call for v3.0.1

To do a reactive call, you need to add rx(). With reactive you can use synchronous or asynchronous calls as you like, and you can combine multiple rest calls more efficiently.

Use callback way

service.getDialogs().rx().thenApply(new CompletableFuture.Fun<List<Dialog>, Integer>() {
  @Override
  public Integer apply(List<Dialog> dialogs) {
    return dialogs.size();
  }
}).thenAccept(new CompletableFuture.Action<Integer>() {
  @Override
  public void accept(Integer integer) {
    System.out.println(integer);
  }
});

Use asynchronous callback way

service.getDialogs().rx().thenApplyAsync(new CompletableFuture.Fun<List<Dialog>, Integer>() {
  @Override
  public Integer apply(List<Dialog> dialogs) {
    return dialogs.size();
  }
}).thenAccept(new CompletableFuture.Action<Integer>() {
  @Override
  public void accept(Integer size) {
    System.out.println(size);
  }
});

Use synchronous way

Integer size=service.getDialogs().rx().get().size();
System.out.println(size);

Breaking Changes for v3.0

The version 3.0 is a major release focused on simplicity and consistency. Several breaking changes were introduced.

Synchronous vs. Asynchronous

Before 3.0 all the API calls were synchronous.

List<Dialog> dialogs = dialogService.getDialogs();
System.out.println(dialogs);

To do a synchronous call, you need to add execute().

List<Dialog> dialogs = dialogService.getDialogs().execute();
System.out.println(dialogs);

To do an asynchronous call, you need to specify a callback.

service.getDialogs().enqueue(new ServiceCallback<List<Dialog>>() {
  @Override
  public void onResponse(List<Dialog> response) {
    System.out.println(response);
  }

  @Override
  public void onFailure(Exception e) {
  }}
);

See the CHANGELOG for the release notes.

Migration

To migrate to 3.0 from a previous version, simply add .execute() to the old methods. For example if you previously had

List<Dialog> dialogs = dialogService.getDialogs();
System.out.println(dialogs);

Just add execute() on the end, and your code will work exactly the same as before.

List<Dialog> dialogs = dialogService.getDialogs().execute();
System.out.println(dialogs);

Installation

Maven

<dependency>
	<groupId>com.ibm.watson.developer_cloud</groupId>
	<artifactId>java-sdk</artifactId>
	<version>3.3.0</version>
</dependency>

Gradle

'com.ibm.watson.developer_cloud:java-sdk:3.3.0'

Snapshots of the development version are available in Sonatype's snapshots repository.

JAR

Download the jar with dependencies here.

Now, you are ready to see some examples.

Usage

The examples below assume that you already have service credentials. If not, you will have to create a service in Bluemix.

If you are running your application in Bluemix, you don't need to specify the credentials; the library will get them for you by looking at the VCAP_SERVICES environment variable.

Getting the Service Credentials

You will need the username and password (api_key for AlchemyAPI) credentials for each service. Service credentials are different from your Bluemix account username and password.

To get your service credentials, follow these steps:

Log in to Bluemix at https://bluemix.net.
Create an instance of the service:
1. In the Bluemix Catalog, select the service you want to use.
2. Under Add Service, type a unique name for the service instance in the Service name field. For example, type my-service-name. Leave the default values for the other options.
3. Click Create.
Copy your credentials:
1. On the left side of the page, click Service Credentials to view your service credentials.
2. Copy username and password(api_key for AlchemyAPI).

Once you have credentials, copy config.properties.example to src/test/resources/config.properties, and fill them in as necessary.

Questions

If you are having difficulties using the APIs or you have a question about the IBM Watson Services, please ask a question on dW Answers or Stack Overflow.

IBM Watson Services

The Watson Developer Cloud offers a variety of services for building cognitive applications.

Alchemy Language

Alchemy Language offers 12 API functions as part of its text analysis service, each of which uses sophisticated natural language processing techniques to analyze your content and add high-level semantic information.

Use the Sentiment Analysis endpoint to identify positive/negative sentiment within a sample text document.

AlchemyLanguage service = new AlchemyLanguage();
service.setApiKey("<api_key>");

Map<String,Object> params = new HashMap<String, Object>();
params.put(AlchemyLanguage.TEXT, "IBM Watson won the Jeopardy television show hosted by Alex Trebek");
DocumentSentiment sentiment = service.getSentiment(params).execute();

System.out.println(sentiment);

Alchemy Vision

Alchemy Vision uses deep learning innovations to understand a picture's content and context. It sees complex visual scenes in their entirety —without needing any textual clues— leveraging a holistic approach to understand the objects, faces, and words in an image.

Example: Extract keywords from an image.

AlchemyVision service = new AlchemyVision();
service.setApiKey("<api_key>");

File image = new File("src/test/resources/alchemy/obama.jpg");
Boolean forceShowAll = false;
Boolean knowledgeGraph = false;
ImageKeywords keywords =  service.getImageKeywords(image, forceShowAll, knowledgeGraph).execute();

System.out.println(keywords);

Alchemy Data News

Alchemy Data News indexes 250k to 300k English language news and blog articles every day with historical search available for the past 60 days.
Example: Get 7 documents between Friday 28th August 2015 and Friday 4th September 2015.

AlchemyDataNews service = new AlchemyDataNews();
service.setApiKey("<api_key>");

Map<String, Object> params = new HashMap<String, Object>();

String[] fields =
    new String[] {"enriched.url.title", "enriched.url.url", "enriched.url.author",
        "enriched.url.publicationDate", "enriched.url.enrichedTitle.entities",
        "enriched.url.enrichedTitle.docSentiment"};
params.put(AlchemyDataNews.RETURN, StringUtils.join(fields, ","));
params.put(AlchemyDataNews.START, "1440720000");
params.put(AlchemyDataNews.END, "1441407600");
params.put(AlchemyDataNews.COUNT, 7);

DocumentsResult result = service.getNewsDocuments(params).execute();

System.out.println(result);

Conversation

Use the Conversation service to identify intents, entities, and conduct conversations.

ConversationService service = new ConversationService(ConversationService.VERSION_DATE_2016_07_11);
service.setUsernameAndPassword("<username>", "<password>");

MessageRequest newMessage = new MessageRequest.Builder().inputText("Hi").build();
MessageResponse response = service.message("<workspace-id>", newMessage).execute();
System.out.println(response);

Concept Insights

The Concept Insights has been deprecated, AlchemyLanguage's concept function can be used as a replacement for most Concept Insights use cases; therefore, we encourage existing Concept Insights service users to migrate to AlchemyLanguage.

Dialog

Returns the dialog list using the Dialog service.

DialogService service = new DialogService();
service.setUsernameAndPassword("<username>", "<password>");

List<Dialog> dialogs = service.getDialogs().execute();
System.out.println(dialogs);

Document Conversion

The Document Conversion service allows to convert pdf, word, and html documents into formats useful to other Watson Cognitive services. Target formats include normalized html, plain text, and sets of potential answers for Watson question answering. You can convert documents synchronously one at a time, or asynchronously in batches

Returns the document list using the Document Conversion service.

DocumentConversion service = new DocumentConversion("2015-12-01");
service.setUsernameAndPassword("<username>", "<password>");

File doc = new File("src/test/resources/document_conversion/word-document-heading-input.doc");
Answers htmlToAnswers = service.convertDocumentToAnswer(doc).execute();
System.out.println(htmlToAnswers);

Language Translation

Select a domain, then identify or select the language of text, and then translate the text from one supported language to another.
Example: Translate 'hello' from English to Spanish using the Language Translator service.

LanguageTranslator service = new LanguageTranslation();
service.setUsernameAndPassword("<username>", "<password>");

TranslationResult translationResult = service.translate(
  "hello", Language.ENGLISH, Language.SPANISH)
  .execute();

System.out.println(translationResult);

Natural Language Classifier

Use Natural Language Classifier service to create a classifier instance by providing a set of representative strings and a set of one or more correct classes for each as training. Then use the trained classifier to classify your new question for best matching answers or to retrieve next actions for your application.

NaturalLanguageClassifier service = new NaturalLanguageClassifier();
service.setUsernameAndPassword("<username>", "<password>");

Classification classification = service.classify("<classifier-id>", "Is it sunny?").execute();
System.out.println(classification);

Note: You will need to create and train a classifier in order to be able to classify phrases.

Personality Insights

Use linguistic analytics to infer personality and social characteristics, including Big Five, Needs, and Values, from text.
Example: Analyze text and get a personality profile using the Personality Insights service.

PersonalityInsights service = new PersonalityInsights();
service.setUsernameAndPassword("<username>", "<password>");

// Demo content from Moby Dick by Hermann Melville (Chapter 1)
String text = "Call me Ishmael. Some years ago-never mind how long precisely-having "
    + "little or no money in my purse, and nothing particular to interest me on shore, "
    + "I thought I would sail about a little and see the watery part of the world. "
    + "It is a way I have of driving off the spleen and regulating the circulation. "
    + "Whenever I find myself growing grim about the mouth; whenever it is a damp, "
    + "drizzly November in my soul; whenever I find myself involuntarily pausing before "
    + "coffin warehouses, and bringing up the rear of every funeral I meet; and especially "
    + "whenever my hypos get such an upper hand of me, that it requires a strong moral "
    + "principle to prevent me from deliberately stepping into the street, and methodically "
    + "knocking people's hats off-then, I account it high time to get to sea as soon as I can. "
    + "This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself "
    + "upon his sword; I quietly take to the ship. There is nothing surprising in this. "
    + "If they but knew it, almost all men in their degree, some time or other, cherish "
    + "very nearly the same feelings towards the ocean with me. There now is your insular "
    + "city of the Manhattoes, belted round by wharves as Indian isles by coral reefs-commerce surrounds "
    + "it with her surf. Right and left, the streets take you waterward.";

Profile profile = service.getProfile(text).execute();
System.out.println(profile);

Note: Don't forget to update the text variable! Also, if you experience authentication errors, remember that the Personality Insights service is not a free service.

Retrieve and Rank

The Retrieve and Rank service helps users find the most relevant information for their query by using a combination of search and machine learning to find "signals" in the data.

RetrieveAndRank service = new RetrieveAndRank();
service.setUsernameAndPassword("<username>", "<password>");

// 1 create the Solr Cluster
SolrClusterOptions options = new SolrClusterOptions("my-cluster-name", 1);
SolrCluster cluster = service.createSolrCluster(options).execute();
System.out.println("Solr cluster: " + cluster);

// 2 wait until the Solr Cluster is available
while (cluster.getStatus() == Status.NOT_AVAILABLE) {
  Thread.sleep(10000); // sleep 10 seconds
  cluster = service.getSolrCluster(cluster.getId()).execute();
  System.out.println("Solr cluster status: " + cluster.getStatus());
}

// 3 list Solr Clusters
System.out.println("Solr clusters: " + service.getSolrClusters().execute());

Retrieve and Rank is built on top of Apache Solr. Look at this example to learn how to use Solrj.

Speech to Text

Use the Speech to Text service to recognize the text from a .wav file.

SpeechToText service = new SpeechToText();
service.setUsernameAndPassword("<username>", "<password>");

File audio = new File("src/test/resources/sample1.wav");

SpeechResults transcript = service.recognize(audio, HttpMediaType.AUDIO_WAV).execute();
System.out.println(transcript);

WebSocket support

Speech to Text supports WebSocket, the url is:
wss://stream.watsonplatform.net/speech-to-text/api/v1/recognize

SpeechToText service = new SpeechToText();
service.setUsernameAndPassword("<username>", "<password>");

File audio = new File("src/test/resources/sample1.wav");

RecognizeOptions options = new RecognizeOptions.Builder()
.continuous(true)
.interimResults(true)
.contentType(HttpMediaType.AUDIO_WAV)
.build();

service.recognizeUsingWebSocket(audio, options, new BaseRecognizeCallback() {
  @Override
  public void onTranscription(SpeechResults speechResults) {
    System.out.println(speechResults);
  }
);
// wait 20 seconds for the asynchronous response
Thread.sleep(20000);

Text to Speech

Use the Text to Speech service to get the available voices to synthesize.

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("<username>", "<password>");

List<Voice> voices = service.getVoices().execute();
System.out.println(voices);

Tone Analyzer

Use the Tone Analyzer service to get the tone of your email.

ToneAnalyzer service = new ToneAnalyzer(ToneAnalyzer.VERSION_DATE_2016_05_19);
service.setUsernameAndPassword("<username>", "<password>");

String text =
  "I know the times are difficult! Our sales have been "
      + "disappointing for the past three quarters for our data analytics "
      + "product suite. We have a competitive data analytics product "
      + "suite in the industry. But we need to do our job selling it! "
      + "We need to acknowledge and fix our sales challenges. "
      + "We can’t blame the economy for our lack of execution! "
      + "We are missing critical sales opportunities. "
      + "Our product is in no way inferior to the competitor products. "
      + "Our clients are hungry for analytical tools to improve their "
      + "business outcomes. Economy has nothing to do with it.";

// Call the service and get the tone
ToneAnalysis tone = service.getTone(text, null).execute();
System.out.println(tone);

Tradeoff Analytics

Use the Tradeoff Analytics service to find the best phone that minimizes price and weight and maximizes screen size.

TradeoffAnalytics service = new TradeoffAnalytics();
service.setUsernameAndPassword("<username>", "<password>");

Problem problem = new Problem("phone");

String price = "price";
String ram = "ram";
String screen = "screen";

// Define the objectives
List<Column> columns = new ArrayList<Column>();
problem.setColumns(columns);

columns.add(new NumericColumn().withRange(0, 100).withKey(price).withGoal(Goal.MIN).withObjective(true));
columns.add(new NumericColumn().withKey(screen).withGoal(Goal.MAX).withObjective(true));
columns.add(new NumericColumn().withKey(ram).withGoal(Goal.MAX));

// Define the options to choose
List<Option> options = new ArrayList<Option>();
problem.setOptions(options);

HashMap<String, Object> galaxySpecs = new HashMap<String, Object>();
galaxySpecs.put(price, 50);
galaxySpecs.put(ram, 45);
galaxySpecs.put(screen, 5);
options.add(new Option("1", "Galaxy S4").withValues(galaxySpecs));

HashMap<String, Object> iphoneSpecs = new HashMap<String, Object>();
iphoneSpecs.put(price, 99);
iphoneSpecs.put(ram, 40);
iphoneSpecs.put(screen, 4);
options.add(new Option("2", "iPhone 5").withValues(iphoneSpecs));

HashMap<String, Object> optimusSpecs = new HashMap<String, Object>();
optimusSpecs.put(price, 10);
optimusSpecs.put(ram, 300);
optimusSpecs.put(screen, 5);
options.add(new Option("3", "LG Optimus G").withValues(optimusSpecs));

// Call the service and get the resolution
Dilemma dilemma = service.dilemmas(problem).execute();
System.out.println(dilemma);

Visual Recognition

Use the Visual Recognition service to recognize the following picture.

VisualRecognition service = new VisualRecognition(VisualRecognition.VERSION_DATE_2016_05_20);
service.setApiKey("<api-key>");

System.out.println("Classify an image");
ClassifyImagesOptions options = new ClassifyImagesOptions.Builder()
    .images(new File("src/test/resources/visual_recognition/car.png"))
    .build();
VisualClassification result = service.classify(options).execute();
System.out.println(result);

Android

The library supports Android 2.3 and above. For Java, the minimum requirement is 1.7.
It depends on OkHttp and gson.

Running in Bluemix

When running in Bluemix, the library will automatically get the credentials from VCAP_SERVICES. If you have more than one plan, you can use BluemixUtils to get the service credentials for an specific plan.

PersonalityInsights service = new PersonalityInsights();
String apiKey = BluemixUtils.getAPIKey(service.getName(), BluemixUtils.PLAN_STANDARD);
service.setApiKey(apiKey);

Build + Test

To build and test the project you can use Gradle (version 1.x): or Apache Maven.

Gradle:

$ cd java-sdk
$ gradle jar  # build jar file (build/libs/watson-developer-cloud-3.3.0.jar)
$ gradle test # run tests

or Maven:

$ cd java-sdk
$ mvn install

Working with Eclipse and Intellij IDEA

If you want to work on the code in an IDE instead of a text editor you can easily create project files with gradle:

$ gradle idea     # Intellij IDEA
$ gradle eclipse  # Eclipse

or maven:

$ mvn idea:idea # Intellij IDEA
$ mvn eclipse:eclipse # Eclipse

Open Source @ IBM

Find more open source projects on the IBM Github Page

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.

Contributing

See CONTRIBUTING.md.

Name		Name	Last commit message	Last commit date
Latest commit History 1,113 Commits
.github		.github
.utility		.utility
examples		examples
src		src
.config.properties.enc		.config.properties.enc
.gitattributes		.gitattributes
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
build.gradle		build.gradle
pom.xml		pom.xml
settings.gradle		settings.gradle

License

atilatosta/java-sdk

Folders and files

Latest commit

History

Repository files navigation

Watson Developer Cloud Java SDK

Table of Contents

Introduce reactive API call for v3.0.1

Breaking Changes for v3.0

Synchronous vs. Asynchronous

Migration

Installation

Maven

Gradle

JAR

Usage

Getting the Service Credentials

Questions

IBM Watson Services

Alchemy Language

Alchemy Vision

Alchemy Data News

Conversation

Concept Insights

Dialog

Document Conversion

Language Translation

Natural Language Classifier

Personality Insights

Retrieve and Rank

Speech to Text

WebSocket support

Text to Speech

Tone Analyzer

Tradeoff Analytics

Visual Recognition

Android

Running in Bluemix

Build + Test

Working with Eclipse and Intellij IDEA

Open Source @ IBM

License

Contributing

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages